Guides

Telegram

Suggest Edits

🚧

Note

For early access clients only

Our business messaging API supports sending and receiving Telegram messages.

Fact sheet

FeatureSupportRemarks
encryptionyesAll Telegram messages are always encrypted. Messages in Secret Chats use client-client encryption, while Cloud Chats use client-server/server-client encryption and are stored encrypted in the Telegram Cloud.
delivery notificationnoTelegram does not support status reports. They state it in their FAQ "We don‘t have a ’delivered to device' status for messages because Telegram can run on as many devices as you want."
text messagesyesThe maximum length of a Telegram message is 4096 characters and it must be UTF-8 encoded.
urls in textyes
mediayesMedia name attribute should end in the proper file extension. You can send more media files in one message. When sending multiple files, each file will be sent in its own Telegram message.
media: imagesyesMaximum file size for an uploaded image with an publicly available url is 5 MB. Supported MIME types are image/jpeg, image/png, image/webp.
media: gifsyesMaximum file size for an uploaded animation with an publicly available url is 20 MB. Supported MIME types are image/gif, video/mpeg without sound.
media: videoyesMaximum file size for an uploaded video with an publicly available url is 20 MB. Supported MIME types are video/mp4, other mime types will be send as a document.
media: audioyesMaximum file size for an uploaded audio file with an publicly available url is 20 MB. Supported MIME types are audio/mpeg.
media: documentyesMaximum file size for an uploaded document with an publicly available url is 20 MB.
media: stickeryesMaximum file size for an uploaded sticker with an publicly available url is 20 MB. Supported MIME types are image/webp, and Telegram's own stickers .TGS files.
reply suggestionscoming soon


Onboarding

Onboarding pages for telegram are in development, in the meantime you are welcome to onboard your app via your customer success manager.

Business rules

Sending Telegram messages using the CM Business Messaging API also requires you to adhere to the Telegram policy.

It is allowed to have multiple bots under one CM.com account.

Considerations

The only way to have a Telegram conversation with end-users is when the end-user starts the conversation by sending your bot an initial message.

If you stop using Telegram and don't come online for at least six months, your account will be deleted along with all messages, media, contacts and every other piece of data you store in the Telegram cloud. You can change the exact period after which your inactive account will self-destruct in Settings.

Prerequisites

To be able to onboard, you need to set-up the following:



Sending messages

Unlike other channels, Telegram does not use telephone numbers as identifiers for sender (from) and recipient (to.number), instead it uses a so called "Chat ID" for the recipient and an "Bot ID" for the sender. A person is assigned a unique Chat ID for each bot they start a conversation with.



Text

Direct message with plain text contents

The example below will send a simple text-only Telegram message. 

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your bot ID",
                "to": [
                    {
                        "number": "Recipients Identifier"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Telegram Messenger"],
                "body": {
                    "type": "auto",
                    "content": "CM.com - Be part of it."
                }
            }
        ]
    }
}


Media

Display order

If you send a message including both Media and some text, Telegram will display this as one entity, always placing the text below the Media, and “joining” the two visually.

An explanation on how to send rich content messages in general can be found in the rich content description.

Direct message with text and image

In the example below, we send a simple rich content message that contains both text and an image that Telegram will display as one entity. 

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your bot ID",
                "to": [
                    {
                        "number": "Recipients Identifier"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Telegram Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "cm.png",
                                "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                                "mimeType": "image/png"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with text and video

In the example below, we send a simple rich content message that contains both text and a video that Telegram will display as one entity. 

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your bot ID",
                "to": [
                    {
                        "number": "Recipients Identifier"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Telegram Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "your-video.mp4",
                                "mediaUri": "your-video-url.mp4",
                                "mimeType": "video/mp4"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with text and audio

In the example below, we send a simple rich content message that contains both text and audio that Telegram will display as one entity. 

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your bot ID",
                "to": [
                    {
                        "number": "Recipients Identifier"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Telegram Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "your-audio.mp4",
                                "mediaUri": "your-audio-url.mp4",
                                "mimeType": "audio/mp4"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with text and document

In the example below, we send a simple rich content message that contains both text and a document that Telegram will display as one entity.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your bot ID",
                "to": [
                    {
                        "number": "Recipients Identifier"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Telegram Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "your-document.pdf",
                                "mediaUri": "your-document-url.pdf",
                                "mimeType": "application/pdf"
                            }
                        }
                    ]
                }
            }
        ]
    }
}


Receiving messages / Inbound flow

Since Telegram is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Telegram you need to set up your webhook API in the Channels app, not in the Gateway app.



Updated 8 months ago