REST Reference Guide

General

Each call made to your Xenioo chatbot must include the following headers:
Header
Value
Description
Authorization
Bearer [APIKEY]
This is the API Key you can copy from your Xenioo Custom Channel publishing dialog.
Content-Type
application/json
All data exchanged with Xenioo must be of this type
user-id
[any string]
This is the current chat user id. If no value is specified, Xenioo will create a new user
Your chatbot account is permanently tied to a Xenioo server node. Any call you make to the custom channel must be directed to your chatbot node or it will fail. Your server node is the same you see on the address bar when you're logged in Xenioo (e.g. app, app02 etc). If your server address is, for example, app03.xenioo.com, then you must use the same address.

Retrieving Configuration

You chatbot basic configuration, as specified in your Xenioo designer, can be retrieved using the config endpoint as follows:
1
curl -X GET \
2
https://<NODE>.xenioo.com/apihook/config \
3
-H 'Authorization: Bearer [APIKEY]' \
Copied!
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:
1
{
2
"Name": "My Awesome Bot",
3
"EnableTypeSpeed": true,
4
"WordsPerMinute": 800,
5
"Avatar": "https://<NODE>.xenioo.com/api/assets/8e23ff8b3ee7_60f1113c-8e6e-46ce-bf19-a53da5ff4ed0.jpg",
6
"Version": 96,
7
"DefaultBehaviour": {
8
"Name": "My Top Behaviour",
9
"APIKey": "[Behaviour API Key]"
10
}
11
}
Copied!
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 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
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

Initiating Chat

The fist connection to your chatbot chat must be done by calling the chat endpoint using the previously specified headers.
This endpoint, called without sending any data will reset the conversation to the starting point. If the user-id is specified in this call, the conversation will be reset but historic conversation will be kept in the Xenioo conversation history interface.
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id'
Copied!
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.
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"Command":"READY"
8
}'
Copied!
A succesful reply from Xenioo may look like this:
1
{
2
"Parts": [
3
{
4
"Type": 0,
5
"Text": "Hello...I am Xenioo 9000.",
6
"TypeDelay": 300,
7
"BehaviourName": "New Bot Behaviour",
8
"InteractionName": "Start Interaction",
9
"Parts": []
10
}
11
],
12
"UserId": "some-user-id",
13
"Creation": "2018-10-05T14:43:43.7057755+01:00",
14
"EnableUserChat": true,
15
"ControlType": 0
16
}
Copied!
The root reply fields have the following format:
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
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
description
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 have a mean of showing a typical 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
3
Image
6
Question
8
Go To
9
Video
10
Audio
11
File
12
List Card
13
14
17
Url
19
User Text
23
25

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:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"Text":"Hello there!"
8
}'
Copied!
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:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{ "Command":"3131292d-945e-4b6b-9f78-7f5eacebf5b6" }'
Copied!
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 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 chat-dir 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.
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-H 'chat-dir: OPERATOR'
7
-d '{"Text":"this is a human operator speaking!"}'
Copied!
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 your user channel.
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-H 'chat-dir: OPERATOR'
7
-d '{
8
"Parts":[
9
{
10
"Type":0,
11
"Text":"Hello there!"
12
},
13
{
14
"Type":1,
15
"Command":"my button id",
16
"Text":"Click me!"
17
}
18
]
19
}'
Copied!
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.
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.

Variables, Tags and Conversation State

You can update (or create new) variables value or conversation tags using the status endpoint like in the example below:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/status \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"UpdateType":"[type]",
8
"Name":"variable_name",
9
"Value":"variable_value"
10
}'
Copied!

Update Type

The UpdateType parameter specifies the type of operation to be done on the chatbot conversation. You have four different update types as specified in the table below:
type
description
set-var
Updates or set the variable with name specified in Name and value specified in Value
del-var
Drops the variable with name as specified in Name field
set-tag
Adds a new tag named Name in the conversation
del-tag
Removes the specified tag
take-over
The chat is taken over by an operator
hand-over
The chat is given back to Xenioo
user-ban
The user is banned until the chat state is sent back to hand-over or take-over. Messages incoming from banned users are ignored.

Additional Hand Over and Take Over parameters

When updating the status of a chat by altering the take over and hand overs status, an additional parameter can be specified to change how Xenioo handles currently active conversation urls. The parameter, named UpdateMode, can be specified as follows:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/status \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"UpdateType":"hand-over/take-over",
8
"UpdateMode":"drop-shares"
9
}'
Copied!
Refer to the following table for a quick reference on UpdateMode possible values:
Value
Description
drop-shares
Delete all currently existing shares
set-view-shares
Each active share will be transformed into a view-mode share
reset-shares
Each active share will return to be a take-over share if previously set to view-only.
Leaving UpdateMode empty will leave any conversation shared url untouched.

Multiple Variables

The status call can also be used to apply changes to multiple variables and tags by supplying an array of changes to the very same endpoint like below:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/status \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"Updates":[
8
{
9
"UpdateType":"set-var",
10
"Name":"test",
11
"Value":"hello"
12
},
13
{
14
"UpdateType":"set-var",
15
"Name":"test2",
16
"Value":"hello again"
17
},
18
{
19
"UpdateType":"del-var",
20
"Name":"test_to_be_removed"
21
},
22
]
23
}'
Copied!
Variable changes are immediate and can even alter variables that have been created or changed during last interaction execution.
The Status call can update any conversation related to the chatbot. You can use this rest call to update any conversation variable for any conversation of the chatbot. This means you can update a variable of a conversation happened on WhatsApp or Telegram, provided the chatbot is also active on the Custom Channel.

Retrieving values

Using custom channel it is possible to access a single variable, tag or privacy flag value using the following url path:
1
curl -X GET \
2
https://<NODE>.xenioo.com/apihook/status/<type>/<name> \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'user-id: some-user-id' \
Copied!
The following call, for example, will retrieve the value of the specified conversation user_telephone_number:
1
curl -X GET \
2
https://<NODE>.xenioo.com/apihook/status/variable/user_telephone_number \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'user-id: some-user-id' \
Copied!
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.
1
{
2
"Value": "+555-555-555"
3
}
Copied!
The type url part can be variable, tag or privacy, depending on the type of value you want to access.

Conversation Position

You can freely change the current conversation position using the set-pos command update as described below:
1
curl -X POST \
2
https://<NODE>.xenioo.com/apihook/status \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id' \
6
-d '{
7
"UpdateType":"set-pos",
8
"Behavior":"My Behavior",
9
"Interaction":"Some Interaction"
10
}'
Copied!
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 on the bot, no action is executed.
The set-pos update can be chained with other update types to first update and then redirect the conversation like in the example below:
1
{
2
"Updates":[
3
{
4
"UpdateType":"set-var",
5
"Name":"myvar",
6
"Value":"some value"
7
},
8
{
9
"UpdateType":"set-pos",
10
"Behavior":"My Behavior",
11
"Interaction":"Some Interaction"
12
}
13
]
14
}
Copied!
The execution of this state change is immediate: any channel attached to this conversation will receive any flow part rendered by Xenioo.
Updates are executed based on the order of arrival. If you move the conversation before updating other variables values will still be set, but the interaction execution will not be able to see the updates.

Conversation History

You can access the conversation history that is still available for any user by invoking the /chat endpoint like in the example below:
1
curl -X GET \
2
https://<NODE>.xenioo.com/apihook/chat \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id'
Copied!
The endpoint will return any conversation history (even if it happened on a different channel) as long as the user-id exists.
If the user is found, each part of the available conversation will be returned in a single array.

Status

Any time during conversation you can retrive the full chatbot status calling the status endpoint as in the example below:
1
curl -X GET \
2
https://<NODE>.xenioo.com/apihook/status \
3
-H 'Authorization: Bearer [APIKEY]' \
4
-H 'Content-Type: application/json' \
5
-H 'user-id: some-user-id'
Copied!
Xenioo reply will contain all of the currently valued variables, tags, Privacy flags and context in the following format:
1
{
2
"Variables": [
3
{
4
"Name": "user_name",
5
"Value": "User 1372503197"
6
},
7
[...]
8
],
9
"Tags": [
10
"new_user"
11
],
12
"PrivacyFlags": [
13
{
14
"Name": "personal_data_processing",
15
"Enabled": false
16
},
17
[...]
18
],
19
"Context": {
20
"BehaviorName": "My Current Behaviour",
21
"InteractionName": "Start Interaction"
22
}
23
}
Copied!
Depending on the complexity of your users conversations and on the amount of data stored in your variables, it may be more
Last modified 5mo ago