/
Instagram

Instagram

Overview

XCALLY Motion enables you to integrate Instagram as a New Channel, using the Open Channel module, for 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.

Requirements

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

  • XCALLY Motion version 3.1.3 or higher

  • Access to a Sinch Account

  • Access to a Facebook Account

  • Access to an Instagram Account

 

 

 

Instagram Account Configuration

XCALLY Motion allows you to send and receive messages globally over Instagram Messenger using the Sinch Conversation API.

image-20250818-125602.png

Follow these below steps to make the proper configuration under Sinch, Facebook and Instagram accounts.

sinch

  1. Access or create a Sinch Account https://dashboard.sinch.com/login

  2. From the Conversation API Menu, select Overview and create a new app

  3. Save the app ID. This will be required later during the Instagram plugin configuration.

facebook

  1. Access or create a Facebook Account https://www.facebook.com/login/

  2. Create a new Facebook page

instagram

  1. Access or create an Instagram Account https://www.instagram.com/accounts/login/

  2. From Instagram Settings, connect the Instagram Account to the Facebook Account through the Meta Accounts Center

  3. From Instagram Settings, switch to professional account

facebook

  1. Log in to Facebook

  2. From Pages section, choose the Page created before and enable the sync between Facebook and Instagram Accounts

image-20240919-075033.png
image (13)-20240919-075334.jpg

sinch

  1. Log in to Sinch

  2. Open Apps section and create your App. As Processing Mode, select Conversation mode

  3. In Set up channels, choose Instagram and click on set up channel. Agree the Terms of Service and continue

  4. Click on Log in With Facebook and agree the Terms of Service (wait for the Active green check icon)

sinch

  1. Go to Webhooks section and Add a new Webhook

  2. 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. This will be required later during the Instagram plugin configuration.

  • Secret token: Insert a secret token. Save the Secret Token. This will be required later during the Instagram plugin configuration.

  • Triggers: please check if all the triggers in the image are selected
    (At the moment OAuth2 authentication is not supported)

  1. Click CREATE to save webhook settings.

  1. To generate an API Key, go to the SINCH Profile

  2. From the Access Keys section, save the Project ID. This will be required later during the Instagram plugin configuration.

  3. Create a New Key, using api_key as dispaly name. Then click on Confirm.

  4. Save the Key ID and Key Secret. They will be required later during the Instagram plugin configuration.

  5. Confirm to Save the Keys.

 

XCALLY Configuration

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

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

1. Setup Instagram Account

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

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

  1. Fill the below 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.

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

  2. Click on the three dots button next to the Instagram account and select Edit Open Channel account.

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

  1. Save the ID Account Openchannel. This will be required later during the Instagram plugin configuration.

2. Setup Instagram Queue

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

  1. Create a new Open Channel Queue for Instagram.

  2. Add agents or teams to the Instagram Queue.

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

Please refer to the Open Channel Queues documentation.

3. Generate API Key

Plugins, such as Instagram, are connected to XCALLY Motion using an API Key.

To generate the API Key:

  1. Go to the Staff section

  2. Open the Users section

  3. Select the 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 Instagram 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 Instagram Plugin zip file: https://repository.xenialab.com/repository/plugins/instagram-plugin/instagram-plugin-v1.1.0.zip

  1. Open the App Zone section → Plugins

  2. Upload the Instagram Plugin clicking the plus button, choosing the zip file and clicking on Confirm

  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 plugin

  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. Setup the Plugin

To configure the Plugin for Instagram:

  1. Access the Plugins section and select Instagram Openchannel.

  2. 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.

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

  • Go to the App Zone section

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

  • Choose the Restart plugin command.

The Instagram Integration is ready to be used!

Debugging and Troubleshooting

If you experience issues with the plugin, please check the below scenarios:

If Messages are not delivered to XCALLY Motion, please follow the below steps:

  • 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.

If Messages are not delivered to Instagram, please follow the below steps:

  • 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.

If in the log file logs/instagram-plugin-plugin.pm2.log “unrecognized delivery report” messages appears:

Uncheck the trigger MESSAGE_DELIVERY from the following triggers in the SINCH webhook:

 

 

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.