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:

curl -X GET \
  https://<NODE>.xenioo.com/apihook/config \
  -H 'Authorization: Bearer [APIKEY]' \

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://<NODE>.xenioo.com/api/assets/8e23ff8b3ee7_60f1113c-8e6e-46ce-bf19-a53da5ff4ed0.jpg",
    "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 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.

curl -X POST \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id'

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 \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
	"Command":"READY"
}'

A succesful reply from Xenioo may look like this:

{
    "Parts": [
        {
            "Type": 0,
            "Text": "Hello...I am Xenioo 9000.",
            "TypeDelay": 300,
            "BehaviourName": "New Bot Behaviour",
            "InteractionName": "Start Interaction",
            "Parts": []
        }
    ],
    "UserId": "some-user-id",
    "Creation": "2018-10-05T14:43:43.7057755+01:00",
    "EnableUserChat": true,
    "ControlType": 0
}

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
1	Button / Quick Reply
3	Image
5	Generic Card
6	Question
8	Go To
9	Video
10	Audio
11	File
12	List Card
13	Button Card
14	Card Element
17	Url
19	User Text
22	Phone Number Button
23	Email Button
24	Location Button
25	Chat Delay
27	Client Side Script
28	IOT Device Session End
29	IOT Device Directive Command
30	Form Render
31	Template Message
32	One Time Notification Request
33	Interactive Message
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 \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
  	"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 \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{ "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 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.

curl -X POST \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -H 'chat-dir: OPERATOR'
  -d '{"Text":"this is a human operator speaking!"}'

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.

curl -X POST \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -H 'chat-dir: OPERATOR'
  -d '{
    "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.

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:

curl -X POST \
  https://<NODE>.xenioo.com/apihook/status \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
	"UpdateType":"[type]",
	"Name":"variable_name",
	"Value":"variable_value"
}'

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:

curl -X POST \
  https://<NODE>.xenioo.com/apihook/status \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
	"UpdateType":"hand-over/take-over",
	"UpdateMode":"drop-shares"
}'

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:

curl -X POST \
  https://<NODE>.xenioo.com/apihook/status \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
    "Updates":[
      {
        "UpdateType":"set-var",
        "Name":"test",
        "Value":"hello"
      },
      {
        "UpdateType":"set-var",
        "Name":"test2",
        "Value":"hello again"
      },
      {
        "UpdateType":"del-var",
        "Name":"test_to_be_removed"
      },
    ]
}'

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:

curl -X GET \
  https://<NODE>.xenioo.com/apihook/status/<type>/<name> \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'user-id: some-user-id' \

The following call, for example, will retrieve the value of the specified conversation user_telephone_number:

curl -X GET \
  https://<NODE>.xenioo.com/apihook/status/variable/user_telephone_number \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'user-id: some-user-id' \

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": "[phone]"
}

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:

curl -X POST \
  https://<NODE>.xenioo.com/apihook/status \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id' \
  -d '{
	"UpdateType":"set-pos",
	"Behavior":"My Behavior",
	"Interaction":"Some 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 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:

{
    "Updates":[
      {
        "UpdateType":"set-var",
        "Name":"myvar",
        "Value":"some value"
      },
      {
        "UpdateType":"set-pos",
        "Behavior":"My Behavior",
        "Interaction":"Some Interaction"
      }
    ]
}

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:

curl -X GET \
  https://<NODE>.xenioo.com/apihook/chat \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id'

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:

curl -X GET \
  https://<NODE>.xenioo.com/apihook/status \
  -H 'Authorization: Bearer [APIKEY]' \
  -H 'Content-Type: application/json' \
  -H 'user-id: some-user-id'

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
        },
        [...]
    ],
    "Context": {
        "BehaviorName": "My Current Behaviour",
        "InteractionName": "Start Interaction"
    }
}

Depending on the complexity of your users conversations and on the amount of data stored in your variables, it may be more