Telegram — OmniMessage Docs

Channels

Send and receive Telegram messages through your own bot.

Requirements#

A Telegram bot, created by talking to BotFather in Telegram.
The bot token that BotFather issued.
Connecting the bot routes its updates to OmniMessage. A webhook you configured for the bot elsewhere stops receiving them.

Connect the channel#

Paste the bot token in the console, or post it to POST /v1/channels with type: "telegram". The token is verified with Telegram while you connect and the username of the bot becomes the identifier, so you do not send one. A token Telegram does not accept fails with 422 upstream_rejected.

Field	Where to find it
`access_token`	The bot token from BotFather, in the form `<bot id>:<secret>`. Use the `/token` command in BotFather to show it again.

curl https://api.omnimessage.co/v1/channels \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "name": "Order bot",
    "credentials": {
      "access_token": "7312045981:AAH..."
    }
  }'

Recipients#

to is the Telegram chat ID, a number such as 482910375. For a private chat it equals the user ID; group and channel chat IDs are negative numbers.

A bot cannot start a conversation. The user has to open the bot and press Start (or write to it) first. That first message arrives as a message.received event whose from is the chat ID to store and use as to.

Supported message types#

Type	Use it for
`text`	Plain text of up to 4096 characters.
`attachments`	One image, video, document, audio file, voice note or sticker, fetched from an HTTPS URL.
`button`	Text with one to three quick-reply buttons.
`location`	A map pin with a name and an address.
`contacts`	One or more contact cards.
`poll`	A question with a list of answer options.

Channel rules#

There is no messaging window: once a user has started the bot you can write at any time, until the user blocks the bot.
If the user blocked the bot or never started it, the message fails with a provider_error.
button messages are rendered as an inline keyboard. A tap arrives as a message.received event carrying the button id.
poll is specific to Telegram. It needs a question and at least two options.
Telegram applies its own per-bot sending limits. Messages beyond them fail with a provider_error and are refunded.

Example request#

curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_2pT5gB8nM1kL4jH7fD0s",
    "to": "482910375",
    "type": "text",
    "text": {
      "body": "Your order #1042 has shipped."
    }
  }'

Delivery statuses#

Telegram does not report delivery or read receipts for bot messages. A successful message therefore stays at sent; treat sent as the final success status on this channel.

Pricing#

Each accepted outbound message on a telegram channel consumes one package credit or the telegram price from the wallet. Read your effective price from GET /v1/pricing. Inbound messages are free. Fees charged by the provider are separate. See Billing.