The short answer
- 1The Gateway API delivers your verification codes in Telegram instead of SMS; recipients must use Telegram.
- 2Keep the token on your server; send with sendVerificationMessage and check status.
- 3Design Telegram-first with an SMS fallback.
In this article
What the Gateway API is
The Gateway API is a paid Telegram service that delivers the verification codes your service sends at sign-up or login as a Telegram message instead of an SMS. The recipient sees the code in the Telegram app as a verification-code notification. It is not a tool for building chat apps; it is a way to confirm identity for your own service. See the four Telegram APIs.
| Item | Detail (official information) |
|---|---|
| Who can receive | Only someone who uses Telegram with that phone number |
| Price | Listed as $0.01 per delivered code; it can change, so check the official page |
| Not delivered | Codes not delivered within a set time are refunded automatically |
| Testing | Sending to your own number is free |
| Payment | Deducted from a balance you top up in advance |
The basic flow
- Create a Gateway account at gateway.telegram.org and get an API token. Keep the token on your server only.
- (Optional) Call
checkSendAbilityto see whether a number can receive codes. A "cannot send" result is not charged. - Send the code with
sendVerificationMessage. Either pass a code you generated, or set only the length (4 to 8 digits) and let Telegram generate it. Also set how long it stays valid (30 to 3600 seconds). - When the user types the code into your screen, and Telegram generated it, confirm it with
checkVerificationStatus. - To withdraw a code that has not been delivered yet, call
revokeVerificationMessage.
Requests go over HTTPS to gatewayapi.telegram.org, with the token in the Authorization header as a Bearer token. Phone numbers use the international E.164 format, such as +15550100199 (an example).
Reading the status
| Status | Values (examples) | Meaning |
|---|---|---|
| Delivery | sent, delivered, read, expired, revoked | Sent, received, read, expired, withdrawn |
| Verification | code_valid, code_invalid, code_max_attempts_exceeded, expired | Correct, wrong, too many attempts, expired |
To receive delivery reports on your server, pass a callback_url when sending. Check that a report really came from Telegram by verifying the signature in its X-Request-Signature header the way the official documentation describes. It is the same idea as checking a mini app's signature; see verifying mini app users.
It cannot fully replace SMS
You cannot reach people who do not use Telegram. Design it in two stages: try Telegram first, and fall back to SMS if the number cannot receive or the code expires.
There is also a way to drop passwords and verification codes entirely: Log in with Telegram on your website.
FAQ
What is the Telegram Gateway API?
A paid service that sends your app's verification codes as Telegram messages instead of SMS.
Can I send codes to people who don't use Telegram?
No. Check with checkSendAbility and fall back to SMS when Telegram can't deliver.
How do I verify a Gateway delivery report?
Check the X-Request-Signature header as described in the official documentation.
Sources
At a glance
- 1Service
Paid per code, refunded if undelivered, free to your own number.
- 2Flow
checkSendAbility, sendVerificationMessage, checkVerificationStatus.
- 3Limits
Only Telegram users; verification only, no marketing.
Updated
