Telegram-OTP

Telegram-OTP-Schnellstart

Verifizierungscodes nativ über das Telegram Gateway senden. Die Plattform validiert Codes serverseitig – dein Backend muss den OTP niemals speichern oder vergleichen.

Testen ohne echtes Telegram-Konto? Sandbox-Modus verwenden – keine Nachrichten gesendet, kein verifizierter Kanal erforderlich und keine Abrechnung.

Voraussetzungen

Novauth-API-Schlüssel — im Dashboard holen

Ein verifizierter Telegram-Kanalname (sender_username) — optional, aber für Markenerkennung empfohlen

Telefonnummer des Nutzers im E.164-Format

Erreichbarkeit prüfen optional

Vor dem Senden kannst du prüfen, ob die Telefonnummer Telegram installiert hat und Nachrichten empfangen kann. Dies vermeidet Ausgaben für nicht zustellbare Anfragen.

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

1OTP-Code senden

Den generierten OTP-Code zusammen mit der Nummer des Empfängers per POST senden. Novauth leitet ihn an das Telegram Gateway weiter, das ihn als offizielle Nachricht in der Telegram-App zustellt.

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 — Antwort

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
}

Die request_id aus der Antwort speichern – sie wird benötigt, um den Verifizierungsstatus zu prüfen und den Code zu widerrufen, wenn der Nutzer einen erneuten Versand anfordert.

2Verifizierungsstatus prüfen

Der entscheidende Vorteil des Telegram Gateway: Du musst den OTP nicht selbst speichern oder vergleichen. Den vom Nutzer eingegebenen Code an check-verification-status übergeben – die Plattform teilt dir mit, ob er gültig ist.

Dieser Endpunkt erfordert eine request_id aus einem echten POST /telegram-Aufruf. Sandbox-request_ids werden hier nicht akzeptiert – sie sind nur innerhalb des Sandbox-Flows gültig.

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 — Antwort

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

3Verifizierung widerrufen (Erneut-Senden-Flow)

Wenn ein Nutzer einen neuen Code anfordert, bevor der aktuelle abläuft, zuerst die ausstehende Anfrage widerrufen – dies kann eine Rückerstattung für die ursprüngliche Gebühr auslösen. Dann POST /telegram erneut mit einem neuen Code aufrufen.

Erfordert eine echte request_id – Sandbox-IDs werden von diesem Endpunkt nicht akzeptiert.

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

API-Referenz

POST/telegramOTP-Code über Telegram senden

POST/telegram/check-send-abilityPrüfen, ob Nummer auf Telegram erreichbar ist

POST/telegram/check-verification-statusEingegebenen Code serverseitig validieren

POST/telegram/revoke-verificationAusstehende Anfrage abbrechen (Erneut-Senden-Flow)

GET/telegram/{uuid}/tdrTelegram-Zustellbericht abrufen

POST/telegram/tdrAlle Telegram-Datensätze auflisten (paginiert)

Request-Body — POST /telegram

tostringrequiredEmpfängertelefon im E.164-Format

codestringrequiredZu übermittelnder OTP-Code — 4 bis 8 Ziffern

ttlnumberoptionalAblaufzeit in Sekunden (30–3600). Standard: Plattformstandard

sender_usernamestringoptionalDein verifizierter Telegram-Kanalname

callback_urlstringoptionalWebhook-URL zum Empfangen von Zustell-/Verifizierungsstatusaktualisierungen