OTP Telegram

Avvio rapido OTP Telegram

Invia codici di verifica nativamente tramite Telegram Gateway. La piattaforma valida i codici lato server — il tuo backend non deve mai archiviare né confrontare l'OTP.

Test senza un account Telegram reale? Usa la Modalità Sandbox — nessun messaggio inviato, nessun canale verificato richiesto e nessuna fatturazione.

Prerequisiti

Chiave API Novauth — ottienila dalla dashboard

Un nome utente di canale Telegram verificato (sender_username) — facoltativo ma consigliato per il riconoscimento del brand

Numero di telefono dell'utente in formato E.164

Controlla la raggiungibilità facoltativo

Prima di inviare, puoi verificare che il numero di telefono abbia Telegram installato e possa ricevere messaggi. Questo evita di spendere per richieste non recapitabili.

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

1Invia il codice OTP

Invia tramite POST il codice OTP generato insieme al numero del destinatario. Novauth lo inoltra a Telegram Gateway, che lo recapita come messaggio ufficiale nell'app 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 — Risposta

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
}

Salva il request_id dalla risposta — ti serve per verificare lo stato della verifica e per revocare il codice se l'utente richiede un nuovo invio.

2Controlla lo stato della verifica

Il principale vantaggio di Telegram Gateway: non devi archiviare né confrontare l'OTP tu stesso. Passa il codice inserito dall'utente a check-verification-status e la piattaforma ti dice se è valido.

Questo endpoint richiede un request_id ottenuto da una vera chiamata POST /telegram. I request_id sandbox non vengono accettati qui — sono validi solo all'interno del flusso 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 — Risposta

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

3Revoca una verifica (flusso di nuovo invio)

Se un utente richiede un nuovo codice prima che quello corrente scada, revoca prima la richiesta in sospeso — questo può attivare un rimborso sull'addebito originale. Poi chiama di nuovo POST /telegram con un codice aggiornato.

Richiede un request_id reale — gli ID sandbox non vengono accettati da questo 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"}'

Riferimento API

POST/telegramInvia codice OTP tramite Telegram

POST/telegram/check-send-abilityControlla se il numero è raggiungibile su Telegram

POST/telegram/check-verification-statusValida il codice inviato lato server

POST/telegram/revoke-verificationAnnulla la richiesta in sospeso (flusso di nuovo invio)

GET/telegram/{uuid}/tdrOttieni il rapporto di consegna Telegram

POST/telegram/tdrElenca tutti i record Telegram (paginato)

Corpo della richiesta — POST /telegram

tostringrequiredTelefono del destinatario in formato E.164

codestringrequiredCodice OTP da recapitare — da 4 a 8 cifre

ttlnumberoptionalScadenza in secondi (30–3600). Predefinito: valore predefinito della piattaforma

sender_usernamestringoptionalIl tuo nome utente di canale Telegram verificato

callback_urlstringoptionalURL webhook per ricevere aggiornamenti sullo stato di consegna/verifica