Telegram OTP

Telegram OTP Quick Start

Send verification codes natively through Telegram Gateway. The platform validates codes server-side — your backend never needs to store or compare the OTP.

Testing without a real Telegram account? Use Sandbox Mode — no messages sent, no verified channel required, and no billing.

Prerequisites

Novauth API key — get one from the dashboard

A verified Telegram channel username (sender_username) — optional but recommended for brand recognition

User's phone number in E.164 format

Check reachability optional

Before sending, you can verify the phone number has Telegram installed and can receive messages. This avoids spending on undeliverable requests.

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

1Send the OTP code

POST your generated OTP code along with the recipient's number. Novauth forwards it to Telegram Gateway, which delivers it as an official message in the Telegram app.

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

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
}

Save the request_id from the response — you need it to check verification status and to revoke the code if the user requests a resend.

2Check verification status

The key advantage of Telegram Gateway: you don't need to store or compare the OTP yourself. Pass the code the user entered to check-verification-status and the platform tells you if it's valid.

This endpoint requires a request_id from a real POST /telegram call. Sandbox request_ids are not accepted here — they are only valid within the sandbox flow.

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

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

3Revoke a verification (resend flow)

If a user requests a new code before the current one expires, revoke the outstanding request first — this may trigger a refund on the original charge. Then call POST /telegram again with a fresh code.

Requires a real request_id — sandbox IDs are not accepted by this 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"}'

API Reference

POST/telegramSend OTP code via Telegram

POST/telegram/check-send-abilityCheck if number is reachable on Telegram

POST/telegram/check-verification-statusValidate submitted code server-side

POST/telegram/revoke-verificationCancel outstanding request (resend flow)

GET/telegram/{uuid}/tdrGet Telegram delivery report

POST/telegram/tdrList all Telegram records (paginated)

Request body — POST /telegram

tostringrequiredRecipient phone in E.164 format

codestringrequiredOTP code to deliver — 4 to 8 digits

ttlnumberoptionalExpiry in seconds (30–3600). Default: platform default

sender_usernamestringoptionalYour verified Telegram channel username

callback_urlstringoptionalWebhook URL to receive delivery/verification status updates