Telegram Gateway: Sending Verification Codes Through Telegram Instead of SMS

Telegram Gateway is Telegram's service for businesses and developers that want to send login and verification codes to a user's phone number through Telegram instead of by SMS. If the phone number belongs to a Telegram account, the code arrives in a special Verification Codes chat inside Telegram. The business calls Telegram's Gateway API, pays per code from a prepaid balance, and keeps SMS as a fallback for people who are not on Telegram.

This guide explains how Gateway works for both sides: the business sending codes, and the person receiving one. It describes the API in words rather than code. Telegram's own Gateway documentation on core.telegram.org is the reference for current methods, parameters and pricing.

What problem Gateway solves

Many apps and websites confirm a phone number by texting a short code. SMS has three well-known weaknesses for the business: it costs money per message, delivery is unreliable in some countries, and SMS can be intercepted or redirected through SIM swapping.

Gateway uses the fact that many people already have Telegram tied to the same phone number. Instead of a text message, the code is delivered as a Telegram message to that number's account. Telegram presents this as faster and cheaper than SMS. Those are Telegram's own claims; whether it is cheaper for you depends on the countries you serve and the SMS prices you pay today.

What the user sees

When a service sends a code through Gateway:

1. The user enters their phone number on the service's website or app, as usual.
2. If the number is linked to a Telegram account, a message arrives in a chat named Verification Codes, sent by Telegram on the service's behalf.
3. The message contains the code and names the service. If the business has set it up, it can come from the business's own verified channel instead.
4. The user types the code back into the service.

Telegram's FAQ explains that a message in this chat means a service is using Telegram Gateway to send a code to your phone number.

If you did not request the code

A code you did not ask for usually means someone typed your phone number into that service, by mistake or as a login attempt. Do not share the code with anyone, including people who message you claiming they sent it to you by accident. That is a classic takeover trick. Our guide on never sharing your Telegram login code explains why, and how to spot Telegram scams covers the follow-up messages scammers send.

Gateway codes and Telegram's own login codes are different

Telegram's own login codes, used to sign in to your Telegram account, come from Telegram's official service notifications, not from the Verification Codes chat. A Gateway code is for a different app or website. If you are having trouble receiving the code to log in to Telegram itself, see Telegram not sending the login code.

How Gateway works for a business

The flow has four parts: an account, a balance, the API calls, and delivery reports.

Before you start

1. A Telegram account to own the Gateway account. You sign in to the Gateway platform with Telegram.
2. An API token, generated in the Gateway account. Keep it on your server only; never put it in a mobile app or web page.
3. Funds. Gateway runs on a prepaid balance. Telegram's quick-start guide describes adding funds through a button that routes to Fragment, Telegram's platform for payments in TON.
4. An SMS fallback for users without Telegram, if you want to reach everyone.
5. Optionally, a verified channel if you want codes to come from your own brand. Telegram's API reference says the channel used as the sender must be verified and owned by the same account as the API token.

Read Telegram's Gateway terms of service before funding the account. At the time of writing, they say unspent balance cannot be withdrawn or refunded, so add funds in amounts you expect to use.

Step by step: sending a code

1. Check whether the user can receive a code. The API offers a method, checkSendAbility, that confirms whether a phone number can receive a Gateway message. According to the documentation, this check is charged only when Telegram confirms that the message can be sent, and it returns a request ID.
2. Send the code. Call sendVerificationMessage with the phone number in international format. If you pass the request ID from the check, the send is not charged again. You can either let Telegram generate the code, choosing a length between 4 and 8 digits, or supply your own numeric code of that length.
3. Store the request ID against the user's sign-up attempt.
4. Verify what the user types. Either compare it with the code you generated yourself, or, if Telegram generated it, pass the user's entry to the checkVerificationStatus method, which reports whether it is correct.
5. Fall back to SMS if the check says the number cannot receive a Gateway message, or if the code is not delivered in time.

Other parameters let you set a time-to-live after which an undelivered message is treated as failed, a payload for your own reference, and a callback URL for reports. A revokeVerificationMessage method lets you cancel a code, for example when the user asks for a new one.

Delivery reports

If you supply a callback URL, Telegram sends a POST request to it with the status of the request: sent, delivered, read, expired or revoked, plus the result of a code check. Telegram's documentation asks you to verify the integrity of each report before trusting it, using the method it describes. A report that fails that check should be ignored.

Testing for free

Telegram's documentation says sending codes to your own phone number is always free. That lets you test the whole flow, including your fallback, before spending anything. A verified channel is not needed for these self-tests.

Designing the sign-up screen around Gateway

The API is only half the job. Users need to know where to look for the code, or they will wait for a text message that never comes.

1. Say where the code will arrive. After the user enters their number, show a line such as "We sent your code to Telegram. Open the Verification Codes chat." If you fell back to SMS, say "by SMS" instead. Your server knows which route it used, so the screen should too.
2. Offer the other route. Add a link like "Didn't get it? Send by SMS instead" that appears after a short wait. Some users have Telegram installed on a different phone or do not open it often.
3. Throttle resends. Each resend costs money and creates a new code. Show a countdown before the resend button becomes active, and revoke the old code when you send a new one so only the latest works.
4. Limit attempts. Allow only a few wrong entries per code before requiring a new one. A short code is guessable if you let anyone try indefinitely.
5. Keep the language plain. Many users will never have heard of Gateway. "Telegram" and "Verification Codes chat" are the only words they need.

Costs and refunds

Telegram publishes its Gateway price on the Gateway page and in its terms, and it can change. Read the current figure there rather than relying on a number from a blog post.

There is one point to read carefully. Telegram's developer documentation says that if a message is not delivered or read within the time-to-live, the fee is refunded. The terms of service, on the other hand, have stated that no reimbursements are made based on delivery status. Check both documents at the time you sign up, and assume the stricter reading until you have confirmed which applies. Each API response also reports the request cost, whether it was refunded and your remaining balance, so you can reconcile your spending yourself.

Example of the trade-off

This is illustrative, with no real prices. Suppose most of your users are in a country where SMS is expensive and unreliable, and many of them use Telegram. Gateway handles those users, and SMS handles the rest. Your cost per verified user becomes a blend of the two, and whether that blend beats SMS alone depends on how many of your users have Telegram. Run a small trial and measure it.

Rules that apply to the content

Gateway is for verification codes, not marketing. The service sends a structured message containing your code; it is not a way to message users about offers or news. Telegram's terms set out what senders may and may not do, and breaking them can end your access. If you want to talk to users on Telegram, build a bot they choose to start, as described in what Telegram bots are.

Privacy: what each side learns

• The user learns which service requested a code for their number, because the message names it.
• Telegram learns that this service sent a code to this phone number.
• The business learns whether the number can receive a Gateway message and whether the code was delivered and read. The check method's purpose is to tell a business whether a number can receive a Gateway message, so you should expect the answer to reveal, in effect, whether that number is reachable on Telegram.

If you are a business, mention Gateway in your privacy policy alongside your SMS provider. If you are a user who does not want to receive these codes, you can usually choose another verification method in the service you are signing up for.

Gateway compared with "Log in with Telegram"

Gateway and Telegram's login widget solve different problems. Gateway proves that someone controls a phone number, and the code is the proof. The login widget lets someone sign in to your site with their Telegram account and shares their Telegram profile details, without a phone number changing hands. If you want users to sign in with Telegram rather than verify a phone, the widget is the tool; our guide to adding Log in with Telegram to a website covers it.

Common mistakes

• Putting the API token in client-side code, where anyone can extract it.
• Not building an SMS fallback, so users without Telegram cannot sign up.
• Calling the send method without the request ID from a successful check, which creates a separate charged request.
• Ignoring report verification on the callback URL.
• Funding more than you need when unspent balance cannot be withdrawn.
• Trying to use it for marketing messages.

FAQ

Do users need to do anything to receive Gateway codes?

No setup is needed. If their phone number is linked to a Telegram account, codes arrive in the Verification Codes chat.

What happens if the user does not have Telegram?

The check reports that the number cannot receive a Gateway message, and the business should send the code another way, usually by SMS.

Can a business send codes from its own name?

Yes, from a verified channel owned by the same account as the API token. Otherwise the code arrives in the standard Verification Codes chat, which still names the service.

Is a Gateway code safer than an SMS code?

It avoids some SMS weaknesses, such as interception on the mobile network, but it is only as safe as the user's Telegram account. Users should protect it with two-step verification.

I got a code I did not request. Is my account hacked?

Not necessarily. It means someone entered your number into that service. Do not share the code, and if it keeps happening, check your Telegram account's active sessions.

Summary

Telegram Gateway lets a business deliver verification codes to a phone number's Telegram account instead of by SMS, through an HTTP API paid from a prepaid balance. A business checks whether a number can receive a message, sends the code, verifies the user's entry, and falls back to SMS where needed, testing for free on its own number first. Users see the code in a Verification Codes chat and should never pass it on to anyone who asks.