How to get SMS via API and webhooks

Turn on API access in your profile, generate a token, and call the API with it. To have incoming SMS pushed to your server, add a webhook URL on the same tab.

Updated 2 min read

You can read your messages and manage numbers from your own code. There are two ways to get new SMS: ask the API for them, or let a webhook send each one to your server as it arrives.

Get an API token

  1. Step 1. Open the API tab

    Go to Profile and open the API tab.

    Open the API tab. Go to Profile and open the API tab.
  2. Step 2. Turn on API access

    Switch API access to Enabled. The same switch cuts all API access off if you ever need that.

  3. Step 3. Generate the token

    Press Generate token under Personal access token. The token is shown once, so copy it and store it safely. Regenerate token issues a new one and revokes the previous one.

  4. Step 4. Call the API

    Send the token as a Bearer token in the Authorization header. The base URL and a ready curl example are on the same tab.

All calls, parameters and answers are in the API documentation.

Receive SMS with a webhook

With a webhook we send a POST request to your server when something happens, so you don't have to poll. Once API access is on, a Webhooks section appears below on the same tab.

  1. Step 1. Enter your URL

    Fill in Webhook URL, an address on your server that answers with a 2xx status within 10 seconds. Prefer https, because with plain http the SMS text and codes travel unencrypted.

    Enter your URL. Fill in Webhook URL, an address on your server that answers with a 2xx status within 10 seconds. Prefer https, because with plain http the SMS text and codes travel unencrypted.
  2. Step 2. Choose the events

    Pick from New SMS received, Number is online after wake-up, Rent renewed, Rent not renewed: not enough balance and Rent ended.

  3. Step 3. Create and test

    Press Create webhook, make sure Send events is on, then press Send test event. The result and the latest deliveries are listed on the page.

Each request is signed with your Signing secret, so check the signature on your side. Failed deliveries are retried for several hours.

Questions on this topic

In Profile, on the API tab. After you generate the token it is shown once. If you lost it, press Regenerate token.

No. You can poll the API instead. Webhooks just save you from polling.

If your server keeps failing to answer, deliveries are switched off. Fix the endpoint, turn on Send events and save.

No. It reads messages and manages numbers. Sending isn't offered.

Read next

Didn't find the answer?

Write to support in Telegram. Send the number and a screenshot of what you see, it speeds things up.

News Support