ON THIS PAGE

Table of Contents

ANDREA: iL PLUGIN CONTIENE LINK A WIKI VECCHIA… CAMBIARE UNA VOLTA PUBBLICATA NEW WIKI V3.

How to manage Telegram Messages from XCALLY

RIVEDERE SOTTO

Image Removed XCALLY Motion Open Channel offers the integration of

Telegram Integration with XCALLY

allowing:the Customers to to ;your ;

Image Removedthe Customers to receive the messages back on Telegram messenger.

Requirements

Image Added

Panel

bgColor	#FFEBE6

☑️ The Motion instance must have a public address accessible via HTTPS. For security reasons we strongly recommend to use a Reverse Proxy → find out more

☑️ Access to a Telegram account

Telegram Account Configuration

Follow these steps to create a Telegram service (bot) and enable its integration with XCALLY Motion:

Access to the Telegram Open your Telegram and find bots app https://t.me/botfather

Image Removed

Image Added

Type as message /newbot to create a new bot
Choose a name for your bot
Choose a username for your bot. It must end in bot.
Save the BOT token to access the HTTP API. We will need it to setup the Telegram plugin.

Image Removed

Now your Telegram service is completed!

Image Added

XCALLY Configuration

In this section you’ll see how to install and configure the XCALLY Motion Telegram Plugin interface, in order to let your Agents interact with Telegram users.

In this phase of the process, you need to access your XCALLY Motion as Admin.

Setup Telegram Account

Access the Open Channel Section:.

Create a new Open Channel Account in your XCALLY Motion, clicking on the plus button and filling the fields:

Image Removed

Image Added

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 to which Telegram 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).

Complete the Open Channel account configuration.

3011 OLD PORT…. QUESTO SCRIPT FUNZIONA CON V3?

Info

The default Reply URL is http://localhost:3011/sendMessage and you usually don't need to change it.

But if the 3011 port is already in use (or you want to change it for any other reason), you can modify its value here and also in the configuration file: just before installing the plugin, unzip the files and change the property of the Port variable in the following file: server/config/config.json.

Code Block

language	js

{
	"token" : "{TOKEN}",
	"webhook": "https://{HOSTNAME}/api/plugins/webhook?port=3011&encoding=binary&path=/api/messages",
	"openChannel": {
		"id": "",
		"receiveUrl": "",
		"mapKey": ""
	},
	"authentication": {
		"username": "",
		"password": ""
	},
	"port": "3011"
}

At the end of these changes, zip all the folder files and upload the plugin you modified.

Perché dovrei farlo?

WarningDon't forget to select telegram (or any other custom field of the Customer profile) as mapKey and add the proper Agents to the account used for Telegram interactions

To configure the Telegram Account:

Select the Telegram Account in the list of Openchannel Accounts, click on the button and Edit it:

Image Added

Check the information and complete the Telegram Account configuration:

Image Added

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

Save the ID Account Openchannel. We’ll need it to setup the Telegram plugin.

Image Added

Save the Token. We’ll need it to setup the Telegram plugin.

Setup Telegram Queue

In order to have Agents receive notifications from the Telegram Account and manage interactions, you need to configure a specific Queue.

Follow the next steps:

Create a new Open Channel Queue, as Telegram Queue.
Add Agents or Teams to the Telegram Queue.
Associate he Telegram Queue to the Telegram Account.

Please refer to this documentation to complete this phase of the process.

CREATE ACTION FLOW IN NEW OPEN CHANNEL SETUP PAGE

Generate API Key

Plug-ins, as Telegram, are connected to XCALLY Motion through the API Key.

To generate the API Key, go to the Staff section and open the User section
Select your Admin user and press on the three dots button to Edit it:

Image Removed

Image Added

Click on the API Key Manager Icon:

Image Removed

Image Added

Generate the API KEY, clicking on GENERATEbutton:

Image RemovedImage Added
Save the API Key. We will need it to setup the Telegram plugin.
Upload the Plugin to XCALLY
Note
XCALLY Motion does not support two or more identical plugins, concurrently active. For more information, please contact us via Support Portal.
It is necessary to upload the plugin.
Download the Telegram Plugin zip file.
View filename
: https://repository.xenialab.com/repository/plugins/telegram-plugin/telegram-plugin-v2.
0
1.
0
2.zip
Open the App Zone section
Upload the Telegram Plugin:
Image RemovedImage Added
After the upload, you will find it in the list of the uploaded App Zone Plugins:
Image RemovedImage Added
To Install the plugin, click on Image Removed button, and click Install plugin:
now the plugin is Active.
Edit the plugin clicking Click on the button :
Image Removedand select
to edit the plugin. Select in the Sidebar field how/to whom this integration must be shown in the menu (default value: Admin Only):
Image RemovedImage Added
Now your Telegram Plugin is active!
Setup Telegram Plugin
Configure
To configure the Plugin for Telegram
by selecting Telegram integration from the list of Plugins:
Insert BOT Token (the one you obtained in previous steps)
Select your Open Channel account from the list (as created in the previous step)
Insert the admin username and password
Update the Webhook inserting your server name
Info
The webhook URL should follow the format: https://{HOSTNAME}/api/plugins/webhook?port={PORT}&path=/api/messages&token={TOKEN}
where {HOSTNAME} is usually your XCALLY hostname or IP address, or the hostname of another server in case you would like to host your integration/application separately.
{PORT} is usually 3011, or the specific port you have defined in your Telegram Plugin settings inside XCALLY Motion.
{TOKEN} is the Open Channel Account token
Info
Remember to modify the admin password you inserted here anytime you change it!
Info
Pay attention to the Port value: each Port can be associated only to one service. Check if the chosen value has already been assigned to another service.
After saving the changes, remember to Restart the Plugin: click on
Image Removed
and you'll find the proper command
Image Removed
Now you can test the communication between the Telegram users (who will write messages to the Telegram Bot you created) and your Agents (who will interact from the XCALLY Omnidesktop Interface)!, access the Plugins section and select Telegram Openchannel.
Fill and check the fields:

Image Added

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

API Key (Admin): Insert the API Key previously saved

Port: Plugin port (choose a different port for each plugin)

URL (public) XCALLY Motion: Enter the public XCALLY Motion URL

Proxy token: If necessary, insert the proxy token

Telegram section

Bot Token: Insert the Telegram token previously saved

Message in case of unsupported message: Message that appears to your Customers in case of unsupported message

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

Message in case of file upload fail: Message that appears to your Agents in case of file upload fail

Remember to Restart the Plugin:

Go to the App Zone section, select the Telegram plugin
click on theImage Added button and choose the Restart plugin command:

Image Added
Telegram Integration is ready to be used!
Telegram Interactions
The Telegram interaction below shows the communication between the Telegram user (who writes messages to the Telegram Bot created) and your Agent (who interacts from the XCALLY Omnidesktop Interface.
Image Added
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.
Additional Information
Configuring your firewall
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.
A few suggestions in this regard:
Try to find the IP address for Telegram server, that is sending webhook requests to XCALLY, using your preferable network analysis tool.
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
Disclaimer: This method will open port 443 of your XCALLY server for all IP addresses.
-- OR --
Accordingly to the following link https://core.telegram.org/bots/webhooks 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.
Debugging/Troubleshooting
All of the log files for Telegram Messenger plugin events are available at:
/var/log/xcally/
directory under
openchannel-
line- naming convention.
Telegram Interaction
scrivere dove visualizzare interazioni e stamp
InfoThe integration allows you to exchange text or attachments. To send both text and attachments, you must send more messages
interactions-combined.yyyy-mm-dd.log
/var/log/xcally/telegram-plugin-plugin.pm2.log

Versions Compared

Old Version 5

New Version Current

Key

Telegram Integration with XCALLY

Requirements

Telegram Account Configuration

XCALLY Configuration

Setup Telegram Account

Setup Telegram Queue

Generate API Key

Upload the Plugin to XCALLY

Setup Telegram Plugin

Telegram Interactions

Additional Information

Configuring your firewall

Debugging/Troubleshooting

Telegram Interaction

Page Comparison

Versions Compared

Old Version 5

New Version Current

Key

Telegram Integration with XCALLY

Requirements

Telegram Account Configuration

XCALLY Configuration

Setup Telegram Account

Setup Telegram Queue

Generate API Key

Upload the Plugin to XCALLY

Setup Telegram Plugin

Telegram Interactions

Additional Information

Configuring your firewall

Debugging/Troubleshooting

Telegram Interaction