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.

BotFather

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:

Copy

Copied

{
  "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)

jsonjson

Copy

Copied

{
  "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"
  }
}

Copy

Copied

{
  "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.

When sending text messages on the Telegram Bot channel, you can use Markdown syntax in the text content. See Telegram Bot channel Markdown support for more information.

The following image provides an example of a text message:

Text Message

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

The Telegram Bot channel natively supports choice messages.

When sending choice messages on the Telegram Bot channel, you can use Markdown syntax in the choice text. See Telegram Bot channel Markdown support for more information.

The following image gives an example of a choice message:

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

The Telegram Bot channel natively supports card messages with one media content.

When sending card messages on the Telegram Bot channel, you can use Markdown syntax in the card title and description. See Telegram Bot channel Markdown support for more information.

The following image gives an example of a card message:

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.

Carousel Message

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.

Location Message

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.

Note:

Please note that the media URLs included in the contact messages are valid for 7 days. After that the media is deleted from Conversation API storage.

All of these are delivered by a Conversation API POST to the MESSAGE_INBOUND webhook:

Example text MO:

Copy

Copied

{
   "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:

Copy

Copied

{
   "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:

Copy

Copied

{
   "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:

Copy

Copied

{
  "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.

Copy

Copied

{
   "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.

Copy

Copied

{
  "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.

Copy

Copied

{
  "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"
  }
}