Conversation API Telegram Bot Support
The Telegram Bot channel enables communication with users of the Telegram ecosystem through the Conversation API.
Note:
If you are unfamiliar with Telegram and Telegram bots, we encourage you to visit the Telegram Knowledge Base on the Sinch Community site. There, you'll find articles that answer common questions and provide context for the information detailed below.
Prerequisites
You need a Telegram bot in order to integrate your Conversation API app with Telegram. If you don't already have one, follow the steps below to create a new Telegram bot:
- You must have an active Telegram account which will be used to administer your new bot. You already have an account if you have Telegram app installed and can sign in. Otherwise, download the Telegram app from the app store of your mobile device.
-
Find BotFather in Telegram app, type
/start
to get the list of all commands. type/newbot
to start creating your bot by following the instructions. Once your bot is created, its token will appear. Please keep this token.
Channel Configuration
The easiest way to configure your Telegram Bot channel on your Conversation API app is to use the Sinch Customer Dashboard. Just select your app and click on SET UP CHANNEL beside Telegram. You will be asked to enter the token for your Telegram bot.
Setup Telegram Bot integration using the API
If you decide to configure your app through API calls, you must update your Conversation API app with Telegram Bot channel credentials as given in the example snippet below:
{
"channel_credentials": [
{
"channel": "TELEGRAM",
"telegram_credentials": {
"token": "{{TELEGRAM_BOT_TOKEN}}"
}
}
]
}
You need to replace {{TELEGRAM_BOT_TOKEN}}
with your Telegram bot's access token.
Don't forget to add Conversation API webhooks to your app in order to receive delivery receipts and inbound messages. Adding webhooks can be done through the portal or using the management API.
Testing the integration
To test your integration, open the Telegram app and search for the name of your Telegram bot, click Start Bot
or Restart Bot
to subscribe to bot. You will get 2 callbacks on your Conversation API webhooks like:
(IDs and Identities are masked)
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T07:54:35.997638Z",
"event_time": "2021-06-08T07:54:35.171Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"opt_in_notification": {
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"channel": "TELEGRAM",
"identity": "1234567",
"status": "OPT_IN_SUCCEEDED",
"request_id": "01F7N9VEK2MZEX0Q9D613H1DH5"
}
}
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T07:54:35.997638Z",
"event_time": "2021-06-08T07:54:35.171Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message": {
"id": "01F7NEMGK72JA707P229260VJ2",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "/start"
}
},
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1234567",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"conversation_id": "01F6PEMQ3X4FAS1475DPQY10VT",
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"metadata": "",
"accept_time": "2021-06-08T07:54:35.171Z"
}
}
One is optin_in_notification
and the other is the actual message sent from the handset.
Both callbacks contain a field contact_id
which is the identifier of the contact which was automatically created when processing the inbound Telegram message. This contact contains the channel identity for the Telegram user, and you can use this contact_id
to reach the Telegram user.
The Telegram Bot channel identities are identifiers which are scoped to all apps. This means that the same Telegram user will have the same channel identities for two different Conversation API apps.
Sending Messages
Some rich messages are natively supported by Telegram Bot channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way Telegram renders the messages on mobile devices.
When sending messages on Telegram Bot channel, you can use Telegram Bot channel specific properties, like Telegram Link Disable. Check out Channel Specific Properties for more info.
Text Messages
Telegram Bot channel natively supports text messages.
The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.
Media Messages
Telegram Bot channel natively supports various type of media messages.
-
image: image/.jpeg, image/.jpg, image/.png
-
Video: video/.mp4
-
Audio: audio/.mp3, audio/.m4a, audio/.ogg, audio/.ocg
-
File: application/.zip, application/.pdf
The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.
Choice Messages
Telegram Bot channel natively supports choice messages. The following image gives an example of a choice message.
The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.
Card Messages
Telegram Bot channel natively supports card messages with one media content. The following image gives an example of a card message.
The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.
Carousel Messages
The Telegram channel doesn't natively support Carousel messages. The following transcoding rules are applied to Conversation Carousel messages so they can be delivered on the Telegram channel.
All Cards are joined as a single message. For each card:
- Title: Converted to text.
- Description: Converted to text.
- Media: Converted to clickable links.
- Choices: Converted to text.
The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.
Location Messages
Telegram Bot channel natively supports location messages.
The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.
Receiving Messages
The Telegram Bot channel supports various kinds of MO messages - text, media, and location. All of these are delivered by a Conversation API POST
to the MESSAGE_INBOUND
webhook:
Example text MO:
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T07:54:35.997638Z",
"event_time": "2021-06-08T07:54:35.171Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message": {
"id": "01F7NEMGK72JA707P229260VJ2",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "/start"
}
},
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1234567",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"conversation_id": "01F6PEMQ3X4FAS1475DPQY10VT",
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"metadata": "",
"accept_time": "2021-06-08T07:54:35.171Z"
}
}
Example location MO:
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T09:46:09.797607Z",
"event_time": "2021-06-08T09:46:09.797607Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message": {
"id": "01EKJ0Z07XKM6H04VB5Q941QBP",
"direction": "TO_APP",
"contact_message": {
"location_message": {
"title": "",
"coordinates": {
"latitude": 55.73064,
"longitude": 13.160131
},
"label": ""
}
},
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1344913942",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"contact_id": "01F6PMEFRNHR201C7ZKBX007PE",
"metadata": "",
"accept_time": "2021-06-08T09:46:09.797607Z"
}
}
Example media message:
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T09:45:39.284927Z",
"event_time": "2021-06-08T09:45:39.284927Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message": {
"id": "01F7NG6SF8BV9J0WHT0FNE0GFR",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://convapi-eu1tst.s3.eu-west-1.amazonaws.com/01EPRZJ1HXTDE9BNM6JT4417GE/01F7NG6S58PYX61S8FXPXW0GW0.mp4",
"thumbnail_url": ""
}
},
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1234567",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"conversation_id": "01F6PMEFTK88Z013PECHAW18G0",
"contact_id": "01F6PMEFRNHR201C7ZKBX007PE",
"metadata": "",
"accept_time": "2021-06-08T09:45:39.284927Z"
}
}
Example choice response message:
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-09-24T08:12:14.760691Z",
"event_time": "2021-09-24T08:12:14.219227Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message": {
"id": "01FGBDSC9WKCTN1RRRYNMR1B0N",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01FGBDS1DWMBPJ14MZEKWR03EY",
"postback_data": "OPTION1"
}
},
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1722576658",
"app_id": ""
},
"conversation_id": "01F8VEFYDN744C1SW51WT11TVD",
"contact_id": "01F8VEFETMV94W0M1NTPXA1H7S",
"metadata": "",
"accept_time": "2021-09-24T08:12:14.697034Z"
},
"message_metadata": ""
}
Receiving Status
Telegram Bot doesn't provide delivery status, the positive status of a message delivery to Telegram Bot channel will be QUEUED_ON_CHANNEL
.
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T10:14:25.450Z",
"event_time": "2021-06-08T10:14:25.866745Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message_delivery_report": {
"message_id": "01F7NHVFDA09MQ0QZZ3DMD1TCD",
"conversation_id": "01F6PEMQ3X4FAS1475DPQY10VT",
"status": "QUEUED_ON_CHANNEL",
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1234567",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"metadata": ""
}
}
If the status is FAILED
the reason will include more information about the failure.
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T10:05:06.244Z",
"event_time": "2021-06-08T10:05:06.551038Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"message_delivery_report": {
"message_id": "01F7NHADA4ACWR150GRK14102N",
"conversation_id": "01F6PEMQ3X4FAS1475DPQY10VT",
"status": "FAILED",
"channel_identity": {
"channel": "TELEGRAM",
"identity": "1234567",
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE"
},
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"reason": {
"code": "MEDIA_NOT_REACHABLE",
"description": "The provided media [https://someone.github.io/sample.png] responded with [Bad Gateway]",
"sub_code": "UNSPECIFIED_SUB_CODE"
},
"metadata": ""
}
}
Unsubscribe Bot
It's possible for users to block a Telegram Bot by using "Stop Bot" (or "Delete Chat" depending on iOS or Android) from their Telegram App. When this happens, an opt-out notification will be sent to App webhook callback so customers can take action such as removing contact_id from their user list.
{
"app_id": "01EPRZJ1HXTDE9BNM6JT4417GE",
"accepted_time": "2021-06-08T07:54:03.165316Z",
"event_time": "2021-06-08T07:54:02.112Z",
"project_id": "ab5336b1-d1b0-45e8-aaa6-b35f13c41d1b",
"opt_out_notification": {
"contact_id": "01EPSAJOPKWLQ80W5PM5P10HMY",
"channel": "TELEGRAM",
"identity": "1234567",
"status": "OPT_OUT_SUCCEEDED",
"request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
}
}