- XCALLY Knowledge (Unlicensed)
- Product Knowledge
- Developers Xenialab (Unlicensed)
- Andrea Bianco
Instagram Integration with XCALLY
XCALLY Motion enables you to integrate Instagram as a New Channel, using the Open Channel.
XCALLY allows you to integrate the Instagram Direct Messenger (DMs).
The Instagram plugin at the moment does not support Posts and Reels' comments or Stories' reply.
Customers can interact with your Agents, sending and receiving direct messages, from your Instagram Official Account.
Agents are able to receive the incoming messages on a special Instagram Queue and to reply from the XCALLY Motion standard GUI.
To make the Integration work, you need to configure your SINCH Account, associated to your Instagram Account, and your XCALLY Motion.
Let’s see how to configure Instagram Integration!
Requirements
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
XCALLY Motion version 3.1.3 or higher
Access to a SINCH Account
Access to a Facebook Account
Access to an Instagram Account
SINCH Account Configuration
XCALLY enables you to send and receive messages globally over Instagram messenger using the SINCH Conversation API.
Follow these steps to set up a SINCH Account, associated to the Instagram Account, and enable its integration with XCALLY Motion.
SINCH
Access or create a SINCH Account Sinch Customer Dashboard - public App
From the Conversation API Menu, select Overview and create a new app
Save the app ID. We will need it to setup the Instagram plugin.
Access or create a Facebook Account https://www.facebook.com/login/
Create a new Facebook Page Create a Facebook Page | Facebook Help Center
Access or create an Instagram Account https://www.instagram.com/accounts/login/
From Instagram Settings, connect the Instagram Account to the Facebook Account through the Meta Accounts Center
From Instagram Settings, switch to professional account
Log in to Facebook
From Pages section, choose the Page created before and enable the sync between Facebook and Instagram Accounts
SINCH
Log in to SINCH
Open Apps section and create your App
As Processing Mode, select Conversation mode
In Set up channels, choose Instagram and click on set up channel
Agree the Terms of Service and continue
Click on Log in With Facebook and agree the Terms of Service (wait for the Active green check icon)
Go to Webhooks section and Add a new Webhook
Fill the popup form
Target Type: Choose HTTP
Target URL: https://[YOUR PUBLIC DOMAIN]/api/plugins/webhook?port=3900&path=/webhook
The URL must be HTTPS. Save the generated Webhook. We will need it to setup the Instagram plugin.
Secret token: Insert a secret token. Save the Secret Token. We will need it to setup the Instagram plugin.
Triggers: please check if all the triggers in the image are selected
(At the moment OAuth2 authentication is not supported)
Click CREATE to save webhook settings.
To generate an API Key, go to the SINCH Profile
From the Access Keys section, save the Project ID. We will need it to setup the Instagram plugin.
Create a New Key, using api_key as dispaly name. Then click on Confirm.
Save the Key ID and Key Secret in a safe place. We will need them to setup the Instagram plugin.
Confirm to Save the Keys.
Now your SINCH Account is completed!
XCALLY Configuration
In this section you’ll see how to install and configure the XCALLY Motion Instagram Plugin interface, in order to let your Agents interact with Instagram users.
In this phase of the process, you need to access your XCALLY Motion as Admin.
Setup Instagram 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 Instagram Account
Key: enter a specif key (it must different for each channel)
Reply URL: http://localhost:3900/send-message . 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 Instagram Account:
Select the Instagram Account in the list of Openchannel Accounts, click on the button and Edit it:
Check the information and complete the Instagram Account configuration:
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 Instagram plugin.
Setup Instagram Queue
In order to have Agents receive notifications from the Instagram Account and manage interactions, you need to configure a specific Queue.
Follow the next steps:
Create a new Open Channel Queue, as Instagram Queue.
Add Agents or Teams to the Instagram Queue.
Associate he Instagram Queue to the Instagram Account.
Please refer to this documentation to complete this phase of the process.
Generate API Key
Plug-ins, as Instagram, 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 GENERATE button:
Save the API Key. We will need it to setup the Instagram plugin.
Upload the Plugin to XCALLY
It is necessary to upload the plugin.
Download the Instagram Plugin zip file: https://repository.xenialab.com/repository/plugins/instagram-plugin/instagram-plugin-v1.1.0.zip
Open the App Zone section
Upload the Instagram 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 Instagram Plugin is active!
XCALLY Motion does not support two or more identical plugins, concurrently active. For more information, please contact us via Support Portal.
Setup Instagram Plugin
To configure the Plugin for Instagram, access the Plugins section and select Instagram Openchannel.
Fill and check the fields:
Webhook (XCALLY Motion Omnichannel): <http://localhost:9000/api/openchannel/accounts/<OPENCHANNEL_ID>/notify> , where the 'OPENCHANNEL_ID' is the Openchannel Account ID previously saved.
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 HTTPS XCALLY Motion URL
Proxy token: If necessary, insert the proxy token.
SINCH webhook: “/webhook”
SINCH secret webhook token: Insert the SINCH secret webhook token previously saved
SINCH project ID: Insert the SINCH project ID previously saved
SINCH app ID: Insert the SINCH app ID previously saved
SINCH Key ID: Insert the SINCH Key ID previously saved
SINCH Key Secret: Insert the SINCH Key Secret previously saved
Unsupported type of message text: Message that appears to your Customers in case of unsupported message
Network error. Retry sending the message. Contact IT support if it doesn't work: Message that appears to your Agents in case of network or configuration error
Remember to Restart the Plugin:
Go to the App Zone section, select the Instagram plugin
click on the button and choose the Restart plugin command:
Instagram Integration is ready to be used!
Additional Information
Debugging/Troubleshooting
Log files are saved in the following locations:
error logs only: /var/log/xcally/instagram-plugin-plugin.error.pm2.log
error and info logs: /var/log/xcally/instagram-plugin-plugin.pm2.log
Attach log files in support request ticket in order to have a faster solution.
Messages are not delivered to XCALLY Motion
Login to SINCH.
Check in Conversation API → Analytics if messages Received and Sent are there.
Sent Messages is the count of messages delivered from SINCH to Instagram.
Received Messages is the count of messages delivered from XCALLY Motion to SINCH.
Check the following settings:
XCALLY Motion is accessible by public network with a valid HTTPS certificate
Check if these settings are correct:
plugin port
webhook URL
Check if plugin service is active with the command: pm2 ls
Restart the plugin service with Admin user → App Zone, select plugin, click on the button and click on Restart Plugin.
Messages are not delivered to Instagram
Check if there are Failed Messages in SINCH Analytics.
If there are Failed messages check Facebook, Instagram and SINCH settings.
If there are not Failed or Sent messages, check XCALLY Motion settings
Check in the app that Processing Mode is set to Conversation mode and not Dispatch mode (If Dispatch Mode is selected, message will be delivered to Motion but the replies will fail because the contact data is missing)
Check in the App Webhook that you have selected all the recommended Triggers. If Contact Create, Contact Update, Contact Merge triggers are not selected, replies to messages delivered to Motion could fail because contact data is missing.
Unrecognized delivery report
If in the log file logs/instagram-plugin-plugin.pm2.log “unrecognized delivery report” messages appear:
Uncheck the trigger MESSAGE_DELIVERY from the following triggers in the SINCH webhook: