OTP de Telegram

Inicio rápido de OTP de Telegram

Envía códigos de verificación de forma nativa a través de Telegram Gateway. La plataforma valida los códigos del lado del servidor: tu backend nunca necesita almacenar ni comparar el OTP.

¿Deseas probar sin una cuenta real de Telegram? Usa el Modo Sandbox: sin mensajes enviados, sin canal verificado requerido y sin facturación.

Requisitos previos

Clave de API de Novauth: obtén una desde el panel

Un nombre de usuario de canal de Telegram verificado (sender_username): opcional pero recomendado para el reconocimiento de marca

Número de teléfono del usuario en formato E.164

Comprobar alcanzabilidad opcional

Antes de enviar, puedes verificar que el número de teléfono tiene Telegram instalado y puede recibir mensajes. Esto evita gastar en solicitudes que no pueden entregarse.

POST/api/v1/connect-hub/telegram/check-send-ability

bash

# Optional: check if this phone number is reachable on Telegram
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

1Enviar el código OTP

Envía mediante POST tu código OTP generado junto con el número del destinatario. Novauth lo reenvía a Telegram Gateway, que lo entrega como un mensaje oficial en la aplicación de Telegram.

POST/api/v1/connect-hub/telegram

bash

curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to":              "+14155552671",
    "code":            "482951",
    "ttl":             300,
    "sender_username": "your_verified_channel",
    "callback_url":    "https://your-server.com/telegram-webhook"
  }'

200 OK — Respuesta

json

{
  "uuid":              "01JQHM3P7KXNV8W2QF5DG6TYAB",  // internal Novauth ID
  "request_id":        "tg_req_4Kf8mNpQrS9xYz2A",      // Telegram Gateway ID — save this
  "to":                "+14155552671",
  "status":            "sent",
  "request_cost":      0.01,
  "remaining_balance": 99.99
}

Guarda el request_id de la respuesta: lo necesitarás para comprobar el estado de verificación y para revocar el código si el usuario solicita un reenvío.

2Comprobar estado de verificación

La ventaja clave de Telegram Gateway: no necesitas almacenar ni comparar el OTP tú mismo. Pasa el código introducido por el usuario a check-verification-status y la plataforma te indicará si es válido.

Este endpoint requiere un request_id de una llamada real a POST /telegram. Los request_id de sandbox no se aceptan aquí: solo son válidos dentro del flujo de sandbox.

POST/api/v1/connect-hub/telegram/check-verification-status

bash

# Verify user-entered code server-side
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_4Kf8mNpQrS9xYz2A",
    "code":       "482951"
  }'

200 OK — Respuesta

json

{
  "request_id":   "tg_req_4Kf8mNpQrS9xYz2A",
  "phone_number": "+14155552671",
  "request_cost": 0.01,
  "delivery_status": {
    "status":     "delivered",   // "sent" | "delivered" | "read" | "expired" | "revoked"
    "updated_at": 1713369600
  },
  "verification_status": {
    "status":       "code_valid",   // the submitted code matched
    "updated_at":   1713369612,
    "code_entered": "482951"
  }
}

3Revocar una verificación (flujo de reenvío)

Si un usuario solicita un nuevo código antes de que expire el actual, revoca primero la solicitud pendiente — esto puede activar un reembolso sobre el cargo original. Luego llama a POST /telegram de nuevo con un código nuevo.

Requiere un request_id real: los ID de sandbox no son aceptados por este endpoint.

POST/api/v1/connect-hub/telegram/revoke-verification

bash

# Invalidate an outstanding verification request (e.g. user requested a resend)
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_4Kf8mNpQrS9xYz2A"}'

Referencia de API

POST/telegramEnviar código OTP vía Telegram

POST/telegram/check-send-abilityComprobar si el número es alcanzable en Telegram

POST/telegram/check-verification-statusValidar el código enviado del lado del servidor

POST/telegram/revoke-verificationCancelar solicitud pendiente (flujo de reenvío)

GET/telegram/{uuid}/tdrObtener informe de entrega de Telegram

POST/telegram/tdrListar todos los registros de Telegram (paginado)

Cuerpo de la solicitud — POST /telegram

tostringrequiredTeléfono del destinatario en formato E.164

codestringrequiredCódigo OTP a entregar — de 4 a 8 dígitos

ttlnumberoptionalExpiración en segundos (30–3600). Por defecto: el predeterminado de la plataforma

sender_usernamestringoptionalTu nombre de usuario de canal de Telegram verificado

callback_urlstringoptionalURL de webhook para recibir actualizaciones de estado de entrega/verificación