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

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

Audio

User Text

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": "+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

Xenioo Controlled.

Operator Requested. The conversation is waiting to be taken over by an operator

Taken Over. The conversation is being handled by an operator

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.

PreviousCustom NextAPI Variables

Last updated 1 month ago