REST Reference Guide
In this page you will find all of the Xenioo endpoints exposed by the Custom Channel. All endpoints are related to your integration endpoint, as specified in the general channel settings.
Each request to the custom channel must include a valid bot-level authorization token. Please refer to this section to know how to generate one. Once obtained, the authorization token must be specified in a standard Authorization header.
Additionally, each to you custom endpoint will contain an Authorization header set to the source bot API Secret. Please ensure that your endpoint correctly filters any request that doesn't contain the correct value.
You chatbot basic configuration, as specified in your settings, can be retrieved using the following route:
curl -X GET <INTEGRATION ENDPOINT>/custom/config \
-H 'Authorization: Bearer [AuthToken]' \
Since this is a global configuration, you don't need to specify the current user-id here. Xenioo reply to this request will be similar to this one:
{
"Name": "My Awesome Bot",
"EnableTypeSpeed": true,
"WordsPerMinute": 800,
"Avatar": "https://...",
"Version": 96,
"DefaultBehaviour": {
"Name": "My Top Behaviour",
"APIKey": "[Behaviour API Key]"
}
}
Description | ||
Name | string | The name of your chatbot |
EnableTypeSpeed | boolean | Indicates if the chatbot is configured to use typespeed simulation. If so, TypeDelay will be valued for actions where necessary |
WordsPerMinute | number | The number of words per minute your chatbot can write. This affects the TypeDelay parameter value |
Avatar | string | The full url of the avatar specified under your chatbot general settings |
Version | number | The version number of your chatbot. This number is automatically increased by Xenioo when any kind of edit happens. |
DefaultBehaviour | object | The name and the API Key associated to your default chatbot Behaviour. You can use the API Key to forcefully redirect your chatbot conversation to another Behaviour |
Each message call that is made to the Custom Channel API can contain a UserId field.
This field is used by Xenioo to uniquely identify a user conversation for your current bot. If no value is supplied, Xenioo will create a unique UserId for you. The UserId value is threated as a string and can contain any value.
The fist connection to your chatbot chat must be done by calling the chat endpoint using the previously specified headers.
By issuing the RESET command, the conversation will be reset to the starting point. If the UserId is specified in this call, the conversation will be reset but historic conversation will be kept in the Xenioo conversation history interface.
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"Command":"RESET"
}'
If you wish instead to continue a previous conversation with a know user you can add the READY command to the request as below. In this case, Xenioo will not reset the conversation and return the full history as first reply.
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"Command":"READY"
}'
If you expect the user to be triggering your bot with a specific keyword, you can skip standard initiation and go directly to the chat flow. In this scenario, you should expect a start user text in the flow and trigger a response accordingly.
A successful reply from Xenioo may look like this:
{
"Parts": [
{
"Type": 0,
"Text": "Hello...I am Xenioo!",
"TypeDelay": 300,
"BehaviourName": "New Bot Behaviour",
"InteractionName": "Start Interaction",
"Parts": []
}
],
"UserId": "<user-id>",
"Creation": "2018-10-05T14:43:43.7057755+01:00",
"EnableUserChat": true,
"ControlType": 0
}
The reply response has the following parts:
Field | Type | Description |
Parts | array | This is an array of 1 or more chat parts. Each chat part is usually a Xenioo Action Result |
UserId | string | The user-id of the current user chatting with you. If you did not create it yourself store it and re-use it for subsequent calls |
Creation | datetime | The Xenioo reply creation date and time. Date and Time are server based and may vary, depending by the Xenioo node associated to the call. |
EnableUserChat | boolean | This may change depending on your chatbot design. You should comply to the chabot designer choices by either allowing or forbidding an open reply from the user |
ControlType | number | The control state of the chatbot. 0-Xenioo, 1-Operator Requested, 2-Operator Taken Over |
Each part may contain different fields, depending on the type. All general fields are as follows:
Field | Type | |
Type | number | The type of content represented by the part of the reply. Your client is responsible for displaying the correct content based on this value. See below for a list of all actions |
Text | string | The text content of the action. If available it should be displayed to the user in some way |
Command | string | The command payload associated to this action. To execute this action you should send back this payload to Xenioo |
TypeDelay | number | The delay, in milliseconds, you should wait before displaying the content. Your interface should display a typing indicator |
BehaviourName | string | This is the name of the Behaviour that generated this conversation part |
InteractionName | string | The interaction, inside the Behaviour that generated this conversation part |
Parts | array | This array may hierarchically contain more parts, depending on the complexity of the action. |
The type parameter is a number representing different types of contents. Refer to the table below for a full list of all possible types.
Values are not fully sequential as some of the contents are reserved for internal use by the Xenioo engine. The missing values should not be expected in a standard parts reply.
Value | Content |
|---|---|
0 | |
1 | |
3 | |
5 | |
6 | |
8 | |
9 | |
10 | Audio |
11 | |
12 | |
13 | |
14 | |
17 | |
19 | User Text |
22 | |
23 | |
24 | |
25 | |
27 | |
28 | |
29 | |
30 | |
31 | |
32 | |
33 | |
34 |
Once the chat control is given to the user, he can interact with your chatbot in two ways: executing a command or saying something (sending a text).
After acquiring the user input, you can relay it to Xenioo using the same connection endpoint, with the following syntax:
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"Text":"Hello there!"
}'
Depending on how you've implemented your chatbot reactions and interactions the answer may change but will always be compliant to the previous reply fields. If your user has instead any mean to click on chat buttons you've implemented or on Carousel contents you must forward to Xenioo the command payload as follows:
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"Command":"3131292d-945e-4b6b-9f78-7f5eacebf5b6"
}'
Command payloads are always GUID values generated by Xenioo. If the command payload is recognized, the command will trigger and the conversation continue, according to the flow you've designed.
The chat command can be used to send messages from a third party platform to an existing Xenioo conversation on any published channel. When invoking the endpoint, if user-id is related to an existing user-id for the selected chatbot, the related conversation will be used and the message sent on the associated channel.
Additionally, you can use the <DIRECTION> header parameter to indicate the direction of the message according to the table below. Leaving the parameter empty will by default assign the supplied text to the user.
Value | Meaning |
BOT | The message will be said by Xenioo and marked as chatbot source |
OPERATOR | The message will be said by Xenioo and marked as if an operator wrote it. This does not require a real take-over of the conversation. |
USER | Default. The message will be set in the conversation as if the user wrote it. |
The <CHANNEL> parameter is required and identifies the name of the channel you wish to target. Channel names are case insensitive and are equal to the "channel" variable associated with the conversation.
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat/<CHANNEL>/<DIRECTION> \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"your-user-id",
"Text":"hello!"
}'
Since chatting on other channels can be used to simulate the chatbot talking, it also possible to send more complex content to your users target channel by using the same syntax of standard chatbot outgoing messages.
The example below will send a text bubble and a button to Telegram as an operator
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat/Telegram/OPERATOR \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"user id",
"Parts":[
{
"Type":0,
"Text":"Hello there!"
},
{
"Type":1,
"Command":"my button id",
"Text":"Click me!"
}
]
}'
Please note that since it has been built by the request, the above button will not be recognized by Xenioo and the click will trigger a fallback. You can adjust your flow to expect the button text and still send it as a chat text when the user clicks it.
If the Include All Channels Conversations option is enabled your hook will also receive real-time notification of users and chatbot messages to the custom webhook endpoint.
All these additional real-time notification will count as an additional action message for the active account.
You can freely change the current conversation position using the ForcedBehaviour and ForcedInteraction parameters as described below:
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<userid>",
"ForcedBehaviour":"My Custom Behaviour",
"ForcedInteraction":"My Custom Interaction"
}'
The result of this call will redirect the conversation to the specified Behavior and Interaction and execute its contents (exactly like a standard Go To Action). If the behavior or the interaction cannot be found the flow will redirect to the start interaction of the start behaviour.
The current conversation position can be instead retrieved with the following route:
curl -X GET \
<INTEGRATION ENDPOINT>/context/<userid> \
-H 'Authorization: Bearer [AuthToken]' \
Conversation position can only be changed when the conversation is handled by Xenioo. Taken over conversations will ignore this command.
During the conversation you can use the custom channel to update variables and tags in real-time. These variables will be immediately acquired by your flow and can be used by your bot flow to make decisions or display data.
The following call will create (or update, if it exists) a variable named "my_variable" and add a tag named "VIPUSER".
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"InputVariables":[
{
"Name":"my_variable",
"Value":"some_value"
}
]
"InputTags":[
"VIPUSER"
]
}'
As you many have noticed the endpoint for Variables and Tag updates is the same of the standard chat. Chat updates and data updates can be sent in the very same payload. In the following example, we receive a text from the user and we also forward the same data as above:
curl -X POST \
<INTEGRATION ENDPOINT>/custom/chat \
-H 'Authorization: Bearer [AuthToken]' \
-H 'Content-Type: application/json' \
-d '{
"UserId":"<user-id>",
"Text":"Hello there!",
"InputVariables":[
{
"Name":"my_variable",
"Value":"some_value"
}
]
"InputTags":[
"VIPUSER"
]
}'
Variables, tags and privacy flag values can be accessed anytime by using the following call:
curl -X GET <INTEGRATION ENDPOINT>/custom/values/<userid>/<type>/<name> \
-H 'Authorization: Bearer [AuthToken]' \
The userid parameter identifies the unique id of the user you wish to target. Userid are unique regardless of channel: you can use this call to retrieve data associated to Custom Channel and any other published channel.
The type parameter can be any of the following:
Name | Type |
|---|---|
variable | Retrieve a variable vaue |
tag | Retrieve a tag value. The result of this call can be either true or false. |
privacy | Retrieve the privacy flag value. The result of this call can be either true or false. |
As an example, the following call will retrieve the value of the specified user user_telephone_number variable:
curl -X GET \
<INTEGRATION ENDPOINT>/custom/values/<userid>/variable/user_telephone_number \
-H 'Authorization: Bearer [AuthToken]' \
If successful, the request will answer with the value of the variable or, if a tag or privacy flag is required, with either true or false.
{
"Value": "+555-555-555"
}
If your integration needs a full snapshot of the current conversation values, you can use the following route to receive them all:
curl -X GET <INTEGRATION ENDPOINT>/custom/values/<userid> \
-H 'Authorization: Bearer [AuthToken]' \
Xenioo reply will contain all of the currently valued variables, tags, Privacy flags and context in the following format:
{
"Variables": [
{
"Name": "user_name",
"Value": "User 1372503197"
},
[...]
],
"Tags": [
"new_user"
],
"PrivacyFlags": [
{
"Name": "personal_data_processing",
"Enabled": false
},
[...]
]
}
When a conversation with a bot is taken over or handed over it changes of state. You can get or set the state of any conversation using Custom Channel.
Any time during conversation you can retrive the state of a conversation by using the following route:
curl -X GET <INTEGRATION ENDPOINT>/custom/state/<userid> \
-H 'Authorization: Bearer [AuthToken]' \
Xenioo reply will contain the current conversation state. If the user is banned, also the expiration day of the ban and the associated message will be returned.
{
"ControlState": <state>,
"BanExpires": "...",
"BanMessage": "...",
}
The state value returned by the request can be one of the following
Value | Description |
|---|---|
0 | Xenioo Controlled. |
1 | Operator Requested. The conversation is waiting to be taken over by an operator |
2 | Taken Over. The conversation is being handled by an operator |
3 | User Banned. The user has been banned and all messages sent by the associated channel are bounced. |
Using Custom Channel you can change a conversation state in real-time. Status updates may also affect Shared Conversations, depending on the parameters supplied.
The following route can be used to update a conversation state:
curl -X PUT <INTEGRATION ENDPOINT>/custom/state/<userid>/<state>/<mode>/<operator> \
-H 'Authorization: Bearer [AuthToken]' \
The state parameter can be one of the following:
Value | Description |
|---|---|
ban | The specified user will be banned |
unban | The ban will be lifted from the specified user |
forget | The conversation will be set in forget mode. All data related to the contact and the conversation will be deleted in a few seconds. |
takeover | The conversation is taken over by the operator specified in the operator parameter. |
handover | The conversation is handed over to Xenioo. The bot is now controlling the conversation. |
When handing over the conversation to Xenioo, the mode parameter can be used to specify how Shared Conversations URL are handled:
Value | Description |
|---|---|
viewshares | Existing take over shared url will automatically be transformed into view only. |
dropshares | All existing take over url will be deleted and become invalid. |
If the mode parameter does not apply to the state you're setting, use a * (asterisk).
The operator parameter must refer to a valid operator email. User a * (asterisk) to allow for any operator or to simply not specify one when the call does not require it.
Last modified 4mo ago