This article describes the Agent’s output directly to Telegram and the Agent’s communication capabilities in Telegram.
Telegram – a messenger that has a web version, a desktop version, and a version for mobile devices.
Agent connection
Creating a bot in Telegram
First of all, you need to make the configuration on the Telegram side.
- Open Telegram and log in.
- Search for the “BotFather” bot.
- Create a bot in the Telegram
- Send the BotFather bot a command /newbot.
- In response to the bot message, enter the desired name of your bot
- Submit your desired bot ID. It must be unique among all existing bots in Telegram and end with “bot”. For example, My_new_telegram_bot_username_bot.
If the submitted bot ID meets the requirements, you will receive a successful bot creation message. The message will contain a link to your bot in Telegram and an access token to the bot.
- Copy the access token
- Сonfigure the avatar, description, and other parameters of the bot through the BotFather bot.
Agent channel configuration in the Platform
The Agent needs to create and configure an Agent Channel with a Telegram connector.
- Enter the Edit menu for your Agent settings.
- In the window that appears, go to the Channels tab to configure channels, then:
- Select Messaging channel type
- Click the Add another channel button.
- Integration with Telegram occurs through a Connector called “Telegram”, set it in the Channel field.
- If necessary, enter a title for this channel in the Title field.
- The headers of different agent channels may be the same.
- After selecting Telegram, the Token field will become available for you to write, into which you need to paste the previously copied token.
- Activate the channel by switching the toggle switch so that the Agent starts responding to it after saving.
- If the Agent has not been trained, a warning will appear. In this case, it is necessary to train the Agent and then try again to activate the Agent Channel.
- After activation, if there are problems with its availability, a warning will be displayed (The channel will be activated despite the problems):
- Can’t reach channel – displayed if the server does not respond to the specified URL;
- Couldn’t register agent webhook – displayed if it was not possible to register a webhook in the removed channel.
- Save Agent’s Channel – click on the Save button.
All settings will be applied only after saving.
Communication
Communication in Telegram group chats
- A chatbot can be added to a Telegram group chat and process messages and events from that chat.
- If the Telegram bot is NOT a group administrator: in order to send a message that will be processed by the Agent and written to the client_message context variable, you must either reply to the bot’s message (reply) or write your message after the / symbol.
- If the Telegram bot is a group administrator: The agent processes all messages sent to the chat.
- After each processed message, the Channel variables will be set to the data of the group member who sent the message.
- The Agent also processes events about new users being added to the group chat. In this case, a string like “telegram_chat_new_member: telegram_user_id|telegram_username|telegram_first_name|telegram_last_name” will be written to the client_message variable.
Channel service messages
- The following service messages are transmitted from Telegram:
| Messages | Message’s template in variable client_message |
|---|---|
| Telegram group user joined the group | String: telegram_chat_new_member: {user.id}|{user.first_name}|{user.last_name} |
| Telegram group user left the group | String: telegram_member_left_chat: {user.id}|{user.first_name}|{user.last_name} |
- Mapping channel variables from a Telegram channel
| Channel Variables | Variable in the body of the incoming request | Features |
|---|---|---|
| channel_visitor_id | id | When replying to a bot message in a group chat, the id of the responding user is written to the variable |
| channel_conversation_id | id | |
| channel_visitor_firstname | first_name | |
| channel_visitor_lastname | last_name | |
| channel_visitor_account | ||
| channel_visitor_phone | ||
| channel_visitor_email | ||
| channel_visitor_source | ||
| channel_visitor_account | username | |
| channel_visitor_auth |
- Opportunities to communicate via Telegram
| Functional | Availability | Description |
|---|---|---|
| channel_chat_id | Yes | channel_visitor_id|telegram |
| Messages will reach the interlocutor if the agent writes first in an existing chat | Yes | |
| Buttons | Yes | The button click comes as button label text |
| Transfer to the operator | No | The button click comes as button label text |
| Transferring files as files from the Agent (Attachment slot) | Yes | Telegram can receive and send attachments of the “file” type only in gif, pdf and zip formats to interlocutors. Support for other formats is possible, but Telegram does not guarantee it. More details: https://core.telegram.org/bots/api#sending-files |
| Transferring files as links from the Agent (Attachment slot) | Yes | The file will be transferred by link if it does not meet Telegram’s requirements for files of this type. |
| Receiving a file from the Interlocutor into a script | Yes | The client_message variable contains a string like file:File type|File ID|File link. In this case, the file will be available via the link within 24 hours. To receive the file in the future, you will need to update the link to the file using the Telegram API. |
| Getting geolocation from the interlocutor in the scenario | Yes | Format: location:53.952693|27.781444 |
| Delivery of messages over 1000 characters from Agent to Interlocutor | Yes | Messages up to 4096 characters are allowed |
| Using markdown | Yes | Works according to documentation – https://core.telegram.org/bots/api#markdownv2-style |