Twitter Integration with XCALLY
XCALLY Motion enables you to integrate Twitter as a New Channel, using the Open Channel.
Customers can interact with your Agents, sending and receiving direct messages, or posting tweets replies, from your Twitter Official Account.
Agents are able to receive the incoming messages on a special Twitter Queue and to reply from the XCALLY Motion standard GUI.
To make the Integration work, you need to configure your Twitter Account and your XCALLY Motion.
Let’s see how to configure Twitter Integration!
Requirements
| Panel | ||
|---|---|---|
| ||
☑️ 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 Twitter developer account with Enterprise access enabled (Instructions about how to acquire one are described here. Applications for Enterprise access are reviewed by Twitter's sales team, and the exact timings may vary). |
Twitter Account Configuration
Follow these steps to create a Twitter service (bot) and enable its integration with XCALLY Motion:
Apply for Developer Account with Enterprise access and then access to your Twitter Developer Account, from https://developer.twitter.com/en/apply-for-access.
Create a new Twitter project, as described here.
From your dashboard add a new app to your project, as described here.
Go to your app settings:
Edit the User Authentication settings:
We suggest the following settings:
OAUth 2.0 is not required
OAUth 1.0a is required
Emails from users are not required
Reading and writing and Direct messages is required
Select Web App as Type of App.
From your app, generate a set of tokens to allow the plugin to access your account, as described here:
Save the API Key, App Secret, Access Token and Secret. We will need it to setup the Twitter plugin.
Create and name an application environment, here:
Save the Application Environment name. We will need it to setup the Twitter plugin.
Now your Twitter service is completed!
| Note |
|---|
Twitter is currently still in the process of migrating its API from v1 to v2: as the migration proceeds, we will make sure to update this plugin as needed. |
| Info |
|---|
For further Twitter documentation, click here. |
XCALLY Configuration
In this section you’ll see how to install and configure the XCALLY Motion Twitter Plugin interface, in order to let your Agents interact with Twitter users.
In this phase of the process, you need to access your XCALLY Motion as Admin.
Setup Twitter 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:
Name: choose a name for your Twitter Account
Key: enter a specif key (it must different for each channel)
Reply URL: http://localhost:3009/api/from-motion-to-twitter 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.
To configure the Twitter Account:
Select the Twitter Account in the list of Openchannel Accounts, click on the
button and Edit it:
Check the information and complete the Twitter Account configuration:
On the top of the screen, you can see the ID Account (the number that follows the # ).
Save the Receive URL. We’ll need it to setup the Twitter plugin.
Save the Token. We’ll need it to setup the Twitter plugin.
Setup Twitter Queue
In order to have Agents receive notifications from the Twitter Account and manage interactions, you need to configure a specific Queue.
Follow the next steps:
Create a new Open Channel Queue, as Twitter Queue.
Add Agents or Teams to the Twitter Queue.
Associate he Twitter Queue to the Twitter Account.
Please refer to this documentation to complete this phase of the process.
Generate API Key
Plug-ins, as Twitter, 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:
Click on the API Key Manager Icon:
Generate the API KEY, clicking on GENERATEbutton:
Save the API Key. We will need it to setup the Twitter plugin.
Upload the Plugin to XCALLY Motion
It is necessary to upload the plugin.
Download the Twitter Plugin zip file: https://repository.xenialab.com/repository/plugins/twitter-plugin/xcally-twitter-plugin-v2.0.0.zip
Open the App Zone section
Upload the Twitter Plugin:
After the upload, you will find it in the list of the uploaded App Zone Plugins:
To Install the plugin, click on
button, and click Install plugin:
Click on the
button to edit the plugin. Select in the Sidebar field how/to whom this integration must be shown in the menu (default value: Admin Only)
Now your Twitter Plugin is active!
| Note |
|---|
XCALLY Motion does not support two or more identical plugins, concurrently active. For more information, please contact us via Support Portal. |
Setup Twitter Plugin
To configure the Plugin for Twitter, access the Plugins section and select Twitter Openchannel.
Fill and check the fields:
Plugin config
Motion API Key: Insert the API Key previously saved.
Plugin port: Plugin port (choose a different port for each plugin)
Map Key: Insert a key to map the plugin
Receive URL: Insert the Receive URL previously saved.
Public motion server address: Enter the public XCALLY Motion URL
Proxy token: If necessary, insert the proxy token
Twitter config
App key: Insert the Twitter App key previously saved.
App secret: Insert the Twitter App secret previously saved.
Access token: Insert the Twitter Access Token previously saved.
Access token secret: Insert the Twitter Access Token Secret previously saved.
Environment: Insert the Twitter Environment name previously saved.
Message config
Warning sent to agents for attachments too big to handle: Message that appears to your Agents in case the attachment sent by the Customer is too big for Motion to handle
Warning sent to users when the message could not be delivered to Motion: Message that appears to your Customers in caseof technical difficulties and your message could not be delivered
Warning sent to agents when the message could not be delivered to Twitter: Message that appears to your Agents in case of impossibility to forward your message to Twitter. Ask to your system admin to check your system logs.
Motion reply URL http://localhost:3009/api/from-motion-to-twitter
Remember to Restart the Plugin:
Go to the App Zone section, select the Twitter plugin
click on the
button and choose the Restart plugin command:
Twitter Integration is ready to be used!
Twitter Interactions
The Twitter interaction below shows the communication between the Twitter user (who writes messages to the Twitter Bot created) and your Agent (who interacts from the XCALLY Omnidesktop Interface.
Note that:
Attachments are sent as download links. Twitter will not allow anything other than media to be sent through their systems. For this reason, any other file (PDF, TXT, everything other than images and videos) will be hosted on Motion and exposed as a downloadable link.
Some videos are sent as download links, even though Twitter supports videos. Unfortunately, Twitter won't accept all kinds of videos. There is a list of requisites for media files, but the plugin can't check them; we try to upload the file, and fall back to a download link in case Twitter rejects it.
Additional Information
Debugging/Troubleshooting
All of the log files for Twitter plugin events are available at /var/log/xcally/openchannel-twitter-info.log.