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 And Security

Unless Simplified Authorization Scheme is enabled, 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.

When using Simplified Authorization Scheme, the Authorization header bearer value can simply contain the API Key of the bot.

While Simplified Authorization Scheme simplifies integration mechanism it also opens to potentially unwanted security concerns and it should be considered only as a last resort where auth token handling becomes too difficult. If you are integrating with Xenioo Custom Channel, we strongly recommend using the Bot Level Authorization token mechanism.

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.

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	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 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	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 \
  <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.

Chatting with BOT or OPERATOR mode requires an existing conversation and cannot be used to create or initiate a conversation with a brand new user.

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

Conversation position can only be changed when the conversation is handled by Xenioo. Taken over conversations will ignore this command.

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>",
	"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"
	]
}'

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

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.