Links

REST Reference Guide

General

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.

Authorization

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.

Accessing Bot Configuration

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]"
}
}
Field
Type
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

Chatting on the Custom Channel

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.

Initiating Chat

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
Text
1
3
Image
5
6
Question
8
Go To
9
Video
10
Audio
11
File
12
List Card
13
14
17
Url
19
User Text
22
23
24
25
27
28
29
30
31
32
33
34
Location

Chatting

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.

Chatting on other channels

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.

Conversation Position

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]' \

Handling Variables and Tags

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>",
"Variables":[
{
"Name":"my_variable",
"Value":"some_value"
}
]
"Tags":[
"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!",
"Variables":[
{
"Name":"my_variable",
"Value":"some_value"
}
]
"Tags":[
"VIPUSER"
]
}'

Retrieving single values

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"
}

Retrieving all values

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
},
[...]
]
}

Conversation Status

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.

Current state

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.

Updating Current State

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