How to configure a Custom Open Channel
Overview
XCALLY Motion Open Channel allows you to interact with your customers through virtually any communication platform — including chat, messaging systems, video apps, and more.
Incoming interactions are routed through queues, and the assigned agents can manage and respond to these messages via the XCALLY Motion OmniDesktop Interface, just like they would with Email, SMS, or WhatsApp.
In this section, you will learn how to set up and build your Open Channel integrations, in particular:
how to configure XCALLY Motion to send outgoing messages to your service (Reply URL setup).
how to make HTTP POST requests to XCALLY Motion's Receive URL to deliver messages into the system.
How to Receive messages from XCALLY Motion
The API URL that the XCALLY Motion application uses to send a message is defined by you and specified in the Reply URL parameter.
The message is sent using the HTTP POST method.
Example
If you create a PHP file to handle the communication between XCALLY Motion and your desired service, remember that you can't access directly in $_POST but you need to add the following row in your code:
$_POST = json_decode(file_get_contents('php://input'), true);
The system will call your API endpoint, including the following parameters in the body of the request:
PARAMETER | DESCRIPTION |
|---|---|
body | Text of the message sent by Motion |
Contact | CM Contact details:
|
AttachmentId | Attachment id (attachment filename is written in the body parameter) |
Download attachments from Motion
If the message contains an attachment (AttachmentId parameter is different by NULL) you can download it using the following API:
https://YourMotionIpAddress/apidoc/#api-Attachments-downloadThe API returns a file stream and requires authentication.
How to Send messages to XCALLY Motion
When you create a new Open Channel account in XCALLY Motion, an API URL (also known as the Receive URL) is automatically generated.
You can retrieve it under the "Settings" tab of the specific Open Channel account.
To send messages to XCALLY Motion from your service:
You must use the HTTP POST method.
The message data should be included in the body of the request.
The request should be sent to the Receive URL.
Below is a list of default parameters you can include in your HTTP POST request body:
PARAMETER | DESCRIPTION |
|---|---|
from | mandatory Customer Identifier (this paramenter will be use for contact search by the system) |
body | mandatory Text of the message |
mapKey | mandatory Contact Manager contact field where the system will perform the search |
AttachmentId | Attachment id |
In addition to default parameters, you can insert Contact fields as extra parameters in body request:
firstName
lastName
tags
street
postalCode
city
country
dateOfBirth
description
phone
mobile
fax
email
url
facebook
If you would like to attach a file to an incoming Open Channel message, remember to first upload the file and then include the AttachmentId in the request body.
For each message sent to XCALLY Motion, the system searches for the contact in the Contact Manager List and associates it with the Open Channel interaction.
If the contact is not found, the system creates a new contact in the selected Contact Manager List with the following properties:
The contact field matching the mapKey is set to the value of the from request parameter.
The contact's firstName is set to the value of the from request parameter.
The contact's phone is set to the value of the from request parameter.
Any additional contact fields provided in the request are also set in the new contact.
Upload attachments to Motion
To upload a file, you need to use the following API:
https://YourMotionIpAddress/apidoc/#api-Attachments-createThe API requires a file stream and authentication
As response body, the system will return the object just created and you can use the property id in the body of the request for creating a new Open Channel message.