# 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](https://community.sinch.com/t5/Telegram/tkb-p/Telegram) 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:

1. 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.
2. 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](/assets/setup.7a35ddb02a754e3bc19c51d6fc3ecaa2948c66b8f4322fc1dbbebaaf795b4a30.22cfd7e9.jpg)

## Channel Configuration

The easiest way to configure your Telegram Bot channel on your Conversation API app is to use the [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/overview). 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:


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


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


```json
{
  "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**](/docs/conversation/channel-support/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**](/docs/conversation/channel-support/telegram/markdown) for more information.

The following image provides an example of a text message:

![Text Message](/assets/telegram_android_textmessage.0f843e68d8cbed4993099a17c1c21de80a30f67181ff31dc033557a4acda93a2.22cfd7e9.png)

The code to send a text message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/text-message).

### Media Messages

Telegram Bot channel natively supports various type of media messages.

- image: image/.jpeg, image/.jpg, image/.png 
![png](/assets/telegram_android_photomessage.2b307031b6ad11ccdcbac573d209139cf6ced8a00ad11545002b0fc0f3bbc9c8.22cfd7e9.png)
- Video: video/.mp4 
![mp4](/assets/telegram_android_videomessage.4ba3d65e4c88798f6d8df12ef45ddf7bfa4417f85b8f79ad0c00c8b36a53aa05.22cfd7e9.png)
- Audio: audio/.mp3, audio/.m4a, audio/.ogg, audio/.ocg 
![ogg](/assets/telegram_android_audiomessage.66e2c015eb636646093816e203240e63d31c50d098a3588fd959785553866aac.22cfd7e9.png)
- File: application/.zip, application/.pdf 
![zip](/assets/telegram_android_zipfilemessage.5297c2c353c16ea197d6c17553234e0e23432b4b08d80a90b4fe33611fe04ab3.22cfd7e9.png) ![pdf](/assets/telegram_android_pdffilemessage.0fd3418397582b9e4b142c045c3f6abe94602f482dd498b87a619bb83b8cf906.22cfd7e9.png)


The code to send a media message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/media-message).

### 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**](/docs/conversation/channel-support/telegram/markdown) for more information.

The following image gives an example of a choice message:

![Choice Message](/assets/telegram_android_choicemessage.504bf18691e37e0dbbe48691d182e71b6ed745a021b241a1873d35fde9dd585c.22cfd7e9.png)

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/choice-message).

### 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**](/docs/conversation/channel-support/telegram/markdown) for more information.

The following image gives an example of a card message:

![Card Message](/assets/telegram_android_cardmessage.ea674b9d57dc8c0dec0df964b8e2f05c5bcf2e949658d9ab123a7e4adcf41939.22cfd7e9.png)

The code to send a card message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/card-message).

### 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](/assets/carousel.50e2d365c7f6537d0cf5c7ef3d77827ba3f345685052509d52ac2155860e0637.22cfd7e9.png)

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/carousel-message).

### Location Messages

Telegram Bot channel natively supports location messages.

![Location Message](/assets/telegram_android_locationmessage.ffd83649ce8a455ca9094244b8bc9c749044f15c37db2ee6952aabaf55dcac11.22cfd7e9.png)

The code to send a location message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/location-message).

## 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:


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


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


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


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


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


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


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