/
Telegram

Telegram

Overview

XCALLY Motion allows you to integrate Telegram Messenger as a New Channel through the Open Channel module.

  • Customer can send and receive direct messages from your Telegram Official Account.

  • Agent receive incoming messages in a dedicated Telegram Queue and can reply directly from the XCALLY Motion GUI.

Requirements

  • The XCALLY Motion instance must have a public address accessible via HTTPS. For security reasons we strongly recommend to use a Reverse Proxy

  • Access to a Telegram account

  • If your XCALLY service is hosted behind a firewall then please make sure that the HTTPS port is able to accept incoming requests from Telegram webhook server as described below (Configuring your firewall).

A few suggestions in this regard:

  1. Find the IP address for Telegram server, that is sending webhook requests to XCALLY, using your preferable network analysis tool.

  2. Add the rule to allow incoming traffic from Telegram IP address, on Port 443, in your firewall policy.

-- OR --

For Debian, look at the iptables rules and modify those in the file: /etc/iptables/rules.v4 according with your needs

-- OR --

Modify the file /etc/sysconfig/iptables (for centOS Machines) and add the following line:

-A INPUT -s 0.0.0.0/0 -p tcp --dport 443 -j ACCEPT

This method will open port 443 of your XCALLY server for all IP addresses.

-- OR --

Accordingly to this link  you can open just the following TCP ports from the specified networks:

149.154.160.0/20

and

91.108.4.0/22

on port 443, 80, 88, or 8443.

 

 

Telegram Account Configuration

The Telegram account must be configured creating a service (bot) and enabling its integration with XCALLY Motion. See the below steps:

  1. Open your Telegram and find bots app: https://t.me/botfather

  2. Type as message /newbot to create a new bot

  3. Choose a name for your bot

  4. Choose a username for your bot. It must end in bot.

  5. Save the BOT token to access the HTTP API. We will need it to setup the Telegram plugin.

 

 

 

XCALLY Configuration

This section explains how to install and configure the XCALLY Motion Telegram Plugin interface, allowing your agents to interact with Telegram users.

To perform this configuration, you must log in to XCALLY Motion as an Admin.

1. Setup Telegram Account

  1. Access the Open Channel Accounts section, under Open Channel menu

  2. Create a new Open Channel Account clicking on the Add button

  1. Fill the below fields:

  • Name: choose a name for your Telegram Account

  • Key: enter a specif key (it must different for each channel)

  • Reply URL: http://localhost:3262/sendMessage This URL is going to be used by Open Channel to answer to the interactions.

  • List: Choose the List where the new contacts will be saved in the Contacts Manager. If a contact is already present in the List, the new interaction will be associated and reported in the Customer Journey. 

  • Description: (Optional) Describe to which bot the channel is associate (for example, bot_sales or bot_support).

  1. Find the Telegram Account, that you have just created, in the list of Openchannel Accounts

  2. Click on the three dots button next to the Telegram account and select Edit.

  1. Check the information and complete the Telegram Account configuration.

On the top of the screen, you can see the ID Account (the number that follows the # ).

  1. Save the Open Channel Account ID – This will be required later during the Telegram plugin configuration.

  2. Save the Token from the Advanced settings – This token is also needed for the Telegram plugin setup.

 

2. Setup Telegram Queue

To enable agents to receive notifications from the Telegram account and manage interactions, you must configure a specific Queue.

  1. Create a new Open Channel Queue for Telegram.

  2. Add agents or teams to the Telegram Queue.

  3. Associate the Telegram Queue with the corresponding Telegram Account.

Please refer to the Open Channel Queues documentation.

3. Generate API Key

Plugins, such as Telegram, are connected to XCALLY Motion using the API Key.

 To generate the API Key:

  1. Go to the Staff section

  2. Open the Users section

  3. Select the User account of interest and press on the three dots button to Edit it.

  1. Click on the API Key Manager Icon:

    1. Generate the API KEY. If the API KEY has been already generated, you just need to copy it.

  2. Copy the API Key. This will be required later during the Telegram plugin configuration.

 

4. Upload the Plugin to XCALLY

XCALLY Motion does not support two or more identical plugins, concurrently active. For more information, please contact us via Support Portal.

Follow the below steps to upload a new plugin:

  1. Download the Telegram Plugin zip file: https://repository.xenialab.com/repository/plugins/telegram-plugin/telegram-plugin-v2.3.1.zip

image-20250416-124141.png

  1. Open the App Zone section → Plugins

  2. Upload the Telegram Plugin clicking the plus button, choosing the zip file and clicking on Finish

  1. After the upload, you will find the plugin in the list of the uploaded App Zone Plugins

  2. To Install the plugin, click on the three dots button next to the plugin and click Install

  1. Click on the three dots button next to the plugin and click Edit plugin.

  2. In the Sidebar field, select how and to whom this integration should be displayed in the menu. (default value: Admin Only)

 

 

5. Configure the Plugin

To configure the Plugin for Telegram:

  1. Access the Plugins section and select Telegram Openchannel.

  2. Fill and check the fields:

  • Webhook (XCALLY Motion Omnichannel): http://localhost:9000/api/openchannel/accounts/ID-CHANNEL/notify , where the 'ID_CHANNEL' is the Openchannel Account ID previously saved (id number without # )

  • Admin user API Key: Insert the API Key previously saved

  • Plugin port: Choose a different port for each plugin

  • XCALLY Motion public URL: Enter the public XCALLY Motion URL

  • Proxy token: If necessary, insert the proxy token

  • Telegram Bot Token: Insert the Telegram token previously saved

  • Unsupported type of message text: Message that appears to your Customers in case of unsupported message

  • Message to show in case of network errors: Message that appears to your Agents in case of network fail

  • Message to show to the agent in case of failed upload: Message that appears to your Agents in case of file upload fail

  • Show custom reply keyboard for buttons: Show a reply keyboard for the buttons list instead of the buttons inside of the message

  • Remove custom reply keyboard on agent reply: Removes the reply keyboard created by the buttons list when the agent replies with a standard text

  1. After the changes, remember to Restart the Plugin:

  • Go to the App Zone section

  • Find the Telegram plugin and click on the three dots button next to the plugin

  • Choose the Restart command.

The Telegram Integration is ready to be used!

Agent experience

The following screenshot illustrates the communication between:

  • Telegram User – Sends messages to the Telegram Bot you created.

  • Agent – Manages and replies to these messages directly from the XCALLY Omnidesktop Interface.

Note that:

  • The Integration allows you to exchange text or attachments. Each message could transfer a text message or a file a time.

  • File >20 MB are not allowed, due to Telegram’s bot limitations.

  • Telegram supports only PDF and ZIP files. DOC, DOCX, TXT are not supported, unless included in a zipped file.

  • MP3 and MP4 are supported, WAV format is blocked by Telegram.

  • Animated GIF are transformed into static picture. GIF can be sent by Customers as file and the Agents receive a MP4 file.

  • PNG images sent by Customers are converted into JPG format: PNG transparent parts are shown in black (color).

  • DDL, EXE, SH files sent by Customers are blocked by XCALLY Motion for safety reason.

 

Debugging and Troubleshooting

All of the log files for Telegram Messenger plugin events are available at:

  • /var/log/xcally/openchannel-interactions-combined.yyyy-mm-dd.log

  • /var/log/xcally/telegram-plugin-plugin.pm2.log