Instagram

Owned by XCALLY Knowledge (Unlicensed)
Last updated: Dec 11, 2023 by Product Knowledge
8 min read

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

  • Save the app ID. We will need it to setup the Instagram plugin.

 

FACEBOOK

INSTAGRAM

  • From Instagram Settings, switch to professional account

FACEBOOK

  • 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

  • Choose Instagram as APP and set up the channel.

  • Agree the Terms of Service and continue

  • From the App section, select the Instagram channel

  • 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: Add MESSAGE_DELIVERY (mandatory), CONVERSATION_START (optional)

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.

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

 

 

 

 

 

 

Instagram

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/logs/instagram-plugin-plugin.error.pm2.log

  • error and info logs: /var/log/xcally/logs/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.

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: