OTP do Telegram

Início rápido do OTP do Telegram

Envie códigos de verificação nativamente através do Telegram Gateway. A plataforma valida os códigos do lado do servidor — o seu backend nunca precisa de armazenar ou comparar o OTP.

Quer testar sem uma conta Telegram real? Use o Modo sandbox — nenhuma mensagem enviada, nenhum canal verificado necessário e sem faturação.

Pré-requisitos

Chave de API da Novauth — obtenha uma no painel

Um nome de utilizador de canal Telegram verificado (sender_username) — opcional, mas recomendado para reconhecimento da marca

Número de telefone do utilizador em formato E.164

Verificar alcançabilidade opcional

Antes de enviar, pode verificar se o número de telefone tem o Telegram instalado e pode receber mensagens. Isto evita gastar em pedidos que não podem ser entregues.

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 o código OTP

Faça POST do código OTP que gerou juntamente com o número do destinatário. A Novauth reencaminha-o para o Telegram Gateway, que o entrega como mensagem oficial na aplicação 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 — Resposta

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
}

Guarde o request_id da resposta — vai precisar dele para verificar o estado da verificação e para revogar o código se o utilizador pedir um reenvio.

2Verificar o estado da verificação

A grande vantagem do Telegram Gateway: não precisa de armazenar nem comparar o OTP. Passe o código introduzido pelo utilizador a check-verification-status e a plataforma diz-lhe se é válido.

Este endpoint requer um request_id de uma chamada POST /telegram real. Os request_id de sandbox não são aceites aqui — só são válidos dentro do fluxo 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 — Resposta

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"
  }
}

3Revogar uma verificação (fluxo de reenvio)

Se um utilizador pedir um novo código antes de o atual expirar, revogue primeiro o pedido pendente — isto pode acionar um reembolso do débito original. Depois chame POST /telegram novamente com um código novo.

Requer um request_id real — os IDs de sandbox não são aceites 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"}'

Referência da API

POST/telegramEnviar código OTP via Telegram

POST/telegram/check-send-abilityVerificar se o número está acessível no Telegram

POST/telegram/check-verification-statusValidar o código submetido do lado do servidor

POST/telegram/revoke-verificationCancelar pedido pendente (fluxo de reenvio)

GET/telegram/{uuid}/tdrObter relatório de entrega do Telegram

POST/telegram/tdrListar todos os registos do Telegram (paginado)

Corpo do pedido — POST /telegram

tostringrequiredTelefone do destinatário em formato E.164

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

ttlnumberoptionalValidade em segundos (30–3600). Predefinição: valor predefinido da plataforma

sender_usernamestringoptionalO seu nome de utilizador de canal Telegram verificado

callback_urlstringoptionalURL de webhook para receber atualizações do estado de entrega/verificação