Clustaar

The Clustaar Developer Hub

Welcome to the Clustaar developer hub. You'll find comprehensive guides and documentation to help you start working with Clustaar as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Principles

 

Webhooks will give you the opportunity to customize the behavior of your bot and enrich bot answers.

Webhooks will be useful to build advanced bots:

  • use information located in your database
  • use an internal tool, such as a CRM
  • use an internal API: recommandation engine, search, ...

Clustaar Webhooks allow you to be notified and take control of your bot when a specific event is triggered.
You can find the list of the event types in the events section.

Suggest Edits

Configuration

Configure your webservice

 

Webhook URL & authentification

In order to configure your webhook you have to go to your bot's settings page, in the webhook tab.

The only mandatory parameter is Webhook URL.
This is were you put the endpoint URL of your webhook.
It is the URL that will be called each time the platform will need to communicate with your webhook.
For example if you set http://example.com/ as the webhook URL, then our platform will send POST requests to the http://example.com/ URL.

Optionally but recommended you can set Auth username and Auth password in order to authenticate the HTTP requests through HTTP Basic authentication.

Finally to increase the security you can provide a private key in order to get a signature for each request that is sent to your webhook.
Please refer to the security section for more information.

Webhook activation

The webhook is activated at the step level. It means you will have to activate the webhook on every step which needs to communicate with the webhook.

The activation is done via the toggle button on the top right of the step panel.

Suggest Edits

Behaviour

Webhooks workflow

 

When the webhook is activated on a Step, it changes the platform behaviour.

As the Step is reached, the webhook will be called and given full Step context:

  • list of actions
  • session

The webhook can use the data received (save items in db, write in a spreadsheet, ...), and change the objects received.

When the webhook is finished doing its work, it must send back the list of actions to execute.

Format

Events share common information, data is the only property that changes among the different event types

Attribute
Type
Description

topic

string

topic name where the event came from

botID

string

ID of the bot that generated the event

type

string

always event

timestamp

number

timestamp of the event

data

object

the event custom data

{
    "topic": "conversation.step_reached",
    "botID": "507f1f77bcf86cd799439011",
    "timestamp": 1514998709,
    "type": "event",
    "data": {
    }
}
Suggest Edits

conversation.step_reached

 

This event is triggered when you switch on the use webhook button.

When an interlocutor will reached this step while talking to your bot, a POST request will be sent to your webhook to let you decide what to do.
The bot will wait for your webhook's response in order to continue the conversation.

It allows you to override the default behavior of the step by overriding the actions that must be executed by the bot.
You can also update the session's values.

Request format

Attribute
Type
Description

data.channel

string

channel used by interlocutor (facebook, intercom...)

data.interlocutor.id

string

interlocutor's ID

data.interlocutor.location.lat

float

interlocutor's latitude

data.interlocutor.location.long

float

interlocutor's longitude

data.interlocutor.firstName

string

interlocutor's first name

data.interlocutor.lastName

string

interlocutor's last name

data.interlocutor.email

string

interlocutor's email

data.interlocutor.customAttributes

object

interlocutor's other attributes

data.session.values

object

interlocutor's session's values

Response format

The response must include the list of the actions to be executed by the bot.
Optionally you can update the session's values by modifying them in the response.
If you omit the session object it will keep the session as it is, and if you set it to an empty object it will delete all the values.
Also you can update the interlocutor by providing new values for the fields you wan to update. If interlocutor is omitted in the response it won't be updated.

Attribute
Type
Required
Description

actions

array<action>

list of action objects

session.values

object

interlocutor's session's values

interlocutor

object

interlocutor object

interlocutor.id

string

interlocutor's ID

interlocutor.location

object

interlocutor's location (can be null)

interlocutor.firstName

string

interlocutor's first name (can be null)

interlocutor.lastName

string

interlocutor's last name (can be null)

interlocutor.email

string

interlocutor's email (can be null)

interlocutor.customAttributes

object

interlocutor's other attributes

Request

{
    "topic": "conversation.step_reached",
    "botID": "507f1f77bcf86cd799439011",
    "timestamp": 1514998709,
    "type": "event",
    "data": {
        "channel": "facebook",
        "interlocutor": {
            "id": "507f1f77bcf86cd799439011",
            "location": {
                "lat": 77.415040,
                "long": -44.052074
            },
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "customAttributes": {
                "age": "25"
            }
        },
        "session": {
            "values": {
                "name": "John"
            }
        },
        "step": {
            "id": "5a8c317624acbe05b1a36feb",
            "name": "A step",
            "userData": null,
            "actions": [
                {
                    "type": "pause_bot_action"
                }
            ]
        }
    }
}

Response

{
    "actions": [
        { 
            "type": "pause_bot_action"
        }
    ],
    "session": {
        "values": {
            "name": "John Doe"
        }
    },
    "interlocutor": {
        "id": "507f1f77bcf86cd799439011",
        "location": {
          	"lat": 77.415040,
            "long": -44.052074
        },
      	"firstName": "John",
      	"lastName": "Doe",
      	"email": "john.doe@example.com",
      	"customAttributes": {
          	"age": "25"
        }
    }
}
 

Once your webhook is configured you should spend some time securing it.

It can be easily done by :

  • activating HTTPS
  • using HTTP basic authentication
  • validating requests signatures

HTTPS

We recommend to use the HTTPS protocol for your webhooks.
This protocol allows to keep the communication between our servers and your webhook encrypted.

If you prefer to use the HTTP protocol, keep in mind that an attacker could be able to capture this traffic and extract some important data.

HTTP basic authentication

If you have set a username and password in your webhook configuration your webhook will receive requests with an Authorization header containing those credentials.

In order to secure your webhook you will have to validate those credentials for each incoming requests.

You should always discard a request with invalid credentials.
Basic authentication is only secured when used with HTTPS.

Request signature

Finally if you have set a private key in your webhook configuration you will be able to validate the incoming requests signatures.

Each request contains a X-Signature header that contains its signature.
This header represents the hexadecimal view of the SHA-1 signature computed using the HMAC algorithm of the request payload.

Example :

import hashlib
import hmac


def generate_signature(private_key, request_body):
    """
    Args:
        private_key (str): webhook private key
        request_body (str): the HTTP request body
    """
    return "sha1=" + hmac.new(private_key.encode(),
                              payload.encode(),
                              hashlib.sha1).hexdigest()

If the signature you receive does not match the one you compute, then it means that someone altered the request and may be trying to hack your webhook.

You should always discard a request with a wrong signature.

 
Suggest Edits

Send text

 

Send a text message.

If alternatives contains multiple elements then a random message will be chosen and sent to interlocutor.

If you want to send multiple text messages to the interlocutor, you will have to use multiple send_text_action actions.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always send_text_action

alternatives

array<string>

a list of text messages (message_length<=500, messages_count<=10)

{
    "type": "send_text_action",
    "alternatives": ["Hello", "Hi"]
}

Wait before executing the next action.

Available on :

  • all platforms

On Facebook it will show a typing animation.

Attribute
Type
Required
Description

type

string

always wait_action

duration

float

pause duration (must be between 0.5 and 7)

{
    "type": "wait_action",
    "duration": 2.0
}
Suggest Edits

Send image

 

Send an image.

Available on :

  • facebook
  • intercom
  • twilio (depends on the capabilities of your phone number)
Attribute
Type
Required
Description

type

string

always send_image_action

imageURL

string

a valid URL (length<=500)

{
    "type": "send_image_action",
    "imageURL": "http://example.com/logo.png"
}
Suggest Edits

Send email

 

Send an email message.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always send_email_action

recipient

string

a valid recipient email address (length<=150)

content

string

content of the message (length<=1500)

subject

string

subject of the message (length<=150)

{
    "type": "send_email_action",
    "recipient": "user@example.com",
    "content": "How are you ?",
    "subject": "Hi"
}

Stop the bot from responding to interlocutor.
Bot won't answer any new message from interlocutor.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always pause_bot_action

{
    "type": "pause_bot_action"
}
Suggest Edits

Send cards

 

Send cards to interlocutor.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always send_cards_action

cards

array<card>

a list of card objects (1<=count<=10)

cards.type

string

always card

cards.title

string

card title (length<=80)

cards.subtitle

string

(length<=80)

cards.imageURL

string

URL of an image to display in the card (length<=500)

cards.url

string

URL opened when card is clicked (length<=500)

cards.buttons

array<button>

list of buttons to show in the card (count<=3)

cards.buttons.type

string

always button

cards.buttons.title

string

button label (length<=20)

cards.buttons.action

object<button_action>

action executed when button is clicked

{
    "type":"send_cards_action",
    "cards":[
        {
            "type": "card",
            "title": "title",
            "subtitle": "subtitle",
            "imageURL": "http://example.com/logo.png",
            "url": "http://example.com",
            "buttons":[
                {
                    "type": "button",
                    "title": "open",
                    "action":{
                        "type": "open_url_action",
                        "url": "http://example.com"
                    }
                }
            ]
        }
    ]
}
Suggest Edits

Send quick replies

 

Send quick replies to interlocutor.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always send_quick_replies_action

message

string

message sent before the buttons (length<=500)

buttons

array<quick_reply>

list of quick reply objects (1<=count<=11)

buttons.title

string

button label (length <=20)

buttons.action

object<go_to_action>

Action executed when button is clicked (must be a go to action)

{
   "type":"send_quick_replies_action",
   "message":"What is your favourite color ?",
   "buttons":[
      {
         "title":"Red",
         "action": {
             "type": "go_to_action",
             "target": {
                 "type":"step",
                 "id":"507f191e810c19729de860ea"
             }
         }
      }
   ]
}
Suggest Edits

Ask location

 

Ask interlocutor to share its location.

When interlocutor accepts, its location attribute will be set.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always ask_location_action

message

string

message sent to ask interlocutor for its location (length<=500)

action

object<go_to_action>

a go to action, executed when the interlocutor accepted the geolocation request

{
    "type": "ask_location_action",
    "message": "Where are you?",
    "action": {
        "type": "go_to_action",
        "target": {
            "type": "step",
            "id": "507f191e810c19729de860ea"
        }
    }
}
Suggest Edits

Assign intercom conversation

 

Assign the intercom conversation of current interlocutor to the admin defined as the rescuer in your intercom bot client.

Available on :

  • intercom
Attribute
Type
Required
Description

type

string

always assign_intercom_conversation_action

assigneeID

string

desired assignee id (length <= 100)

{
    "type": "assign_intercom_conversation_action",
    "assigneeID": "64356433"
}
Suggest Edits

Close intercom conversation

 

Close the intercom conversation of current interlocutor.

Available on :

  • intercom
Attribute
Type
Required
Description

type

string

always close_intercom_conversation_action

{
    "type": "close_intercom_conversation_action"
}
Suggest Edits

Store session value

 

Set a session value.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always store_session_value_action

key

string

session key to set (1 <= length <= 100, must contain only letters, digits and underscores)

value

string

value to store (1<=length<= 150)

{
    "type": "store_session_value_action",
    "key": "name",
    "value": "John Doe"
}
Suggest Edits

Jump To

Force the jump to another step during current step execution.

 

Force the Jump from current step to another step without waiting for a response from the user.
A Jump To can leads to a step inside current story, or the first step of another story.

To fully understand how this action works you should read this page.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always jump_to_action

connections

array<connection>

a list of connection objects

defaultTarget

object<target>

default target when none of the connections matched (can be null)

{
    "type": "jump_to_action",
    "connections": [
        {
            "type": "flow_connection",
            "target": {
                "id": "5b292a5f24acbe20be174a1f",
                "type": "step",
                "name": "Second step"
            },
            "predicates": [
                {
                    "type": "connection_predicate",
                    "condition": {
                        "type": "is_not_set"
                    },
                    "valueGetter": {
                        "type": "message"
                    }
                }
            ]
        }
    ],
    "defaultTarget": {
        "id": "5b292a5f24acbe20be174a21",
        "type": "step",
        "name": "First step"
    }
}
Suggest Edits

Create zendesk ticket

 

Creates a zendesk ticket.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

str

always create_zendesk_ticket_action

ticketType

str

the desired ticket type (can be question, incident, problem, task)

ticketPriority

str

the desired ticket priority (can be urgent, high, normal, low)

description

str

correspond to the first message (length >= 5 and length <= 1500)

subject

str

correspond to the ticket title (length <= 100)

groupID

str

the desired group id (length <= 24 and only digits)

assigneeID

str

the desired assignee id (length <= 24 and only digits)

tags

str

permit to add custom Tags/Markers (array length <= 10, tags length <= 80)

user.name

str

the user name (length <= 100

user.email

str

the user email (length <= 100)

user.phoneNumber

str

the user phone number

{
  	"type": "create_zendesk_ticket_action",
    "ticketPriority": "low",
    "ticketType": "question",
    "subject": "I m the title",
    "description": "I m the first message",
    "assigneeID": "7777777",
    "groupID": "6666666",
    "tags": [
        "yolo"
    ],
    "user": {
        "email": "millou@titin.com",
        "name": "tintin",
        "phoneNumber": "0611654852"
    }
}
Suggest Edits

Set user attribute

Set attributes on your users which will be persisted.

 

Save an attribute associated to an interlocutor.
This attribute will persist forever, unlike session values which die at the end of the story where they were set.

It can be very useful to transmit valuable information from your database to the bot, and build more intelligent conversations.

Available on :

  • all platforms
Attribute
Type
Required
Description

type

string

always set_user_attribute_action

key

string

attribute name to set (1 <= length <= 100, must contain only letters, digits and underscores)

value

string

value to store (1<=length<= 150)

{
    "type": "set_user_attribute_action",
    "key": "name",
    "value": "John Doe"
}
Suggest Edits

Button actions

 

Execute the specified target when button is clicked.

Target can be either a step or a story.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always go_to_action

target.type

string

target type (step or story)

target.id

string

target ID

{
    "type": "go_to_action",
    "target": {
        "type": "step",
        "id": "12"
    }
}
 

Open an URL when button is pressed.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always open_url_action

url

string

URL to open (length<=500)

{
    "type":"open_url_action",
    "url":"http://example.com"
}

Share card holding the button to another person.

Available on :

  • facebook
Attribute
Type
Required
Description

type

string

always share_action

{
    "type": "share_action"
}
Suggest Edits

Other references

 
Suggest Edits

Flow Connection

 

A connection is an object composed of a target, and some predicates.
It's used by jump to actions to define the different links.

The target is the destination of the connection: if all the predicates of the connection are validated, the conversation will continue through this target.
A target can be a step or an actions_block.

Attribute
Type
Required
Description

type

string

always flow_connection

target

object<target>

target of the connection

predicates

array<predicate>

a list of predicate objects

Predicate

A predicate is the component that check if the connection can be triggered.

It is composed of :

A predicate matches when the value fetched by the value getter passes the condition.

Attribute
Type
Required
Description

type

string

always connection_predicate

condition

object<condition>

a condition object

valueGetter

object<value getter>

a value getter object

{
    "type": "flow_connection",
    "target": {
        "id": "a1a1a1a1a1a1a1a1a1a1a1a1",
        "type": "step",
        "name": "First step"
    },
    "predicates": [
        {
            "type": "connection_predicate",
            "condition": {
                "pattern": "^\d+$",
                "type": "match_regexp"
            },
            "valueGetter": {
                "key": "quantity",
                "type": "session_value"
            }
        }
    ]
}
{
    "type":"connection_predicate",
    "condition":{
        "pattern":"^\d+$",
        "type":"match_regexp"
    },
    "valueGetter":{
        "key":"quantity",
        "type":"session_value"
    }
}

A target represents a destination in the bot configuration, which will handle the continuity of the conversation.
It is used by GoTo button action to know where to go when the button is clicked.

Attribute
Type
Required
Description

type

string

can be one of step, story

id

string

ID of the step or story to target

{
    "id": "507f1f77bcf86cd799439011",
    "type": "step"
}
Suggest Edits

Conditions

 

This object is responsible for the validation of value according to configured conditions.

Contain

Condition that matches if value contains one of the values present in values.
This condition is case insensitive.

Examples :

  • contains("hello, how are you?", ["hell"]) :white-check-mark+:
  • contains("hello, how are you?", ["Hello"]) :white-check-mark+:
  • contains("hello, how are you?", ["bye", "hello"]) :white-check-mark+:
  • contains("hello, how are you?", ["bye"]) :x+:
Attribute
Type
Required
Description

type

string

always contains

values

array<string>

a list strings that should match the value

Equal

Condition that matches if value equals the expected one.
This condition is case sensitive.

Examples :

  • equals("hello", "hello") :white-check-mark+:
  • equals("hello, how are you?", "hello") :x+:
  • equals("hello", "Hello") :x+:
  • equals("hello", "bye") :x+:
Attribute
Type
Required
Description

type

string

always match_intent

expected

string

expected value

Match intent

Condition that matches if the intent is detected in the value.

Attribute
Type
Required
Description

type

string

always match_intent

intent.id

string

intent ID to detect

intent.name

string

intent name to detect

intent.type

string

always intent

Match regexp

Condition that matches if value matches a regular expression.

Examples :

  • matches("hello", /hello/) :white-check-mark+:
  • matches("hello 12", /\d+/) :white-check-mark+:
  • matches("hello", /\d+/) :x+:

Store matched pattern

If you want to store a matched pattern in a session value, it is easily possible. Just follow this tutorial.

Attribute
Type
Required
Description

type

string

always match_regexp

pattern

string

a valid regular expression pattern

Is set

Condition that matches if value is not null.

Examples :

  • is_set("hello") :white-check-mark+:
  • is_set(null) :x+:
Attribute
Type
Required
Description

type

string

always is_set

Is not set

Condition that matches if value is null.

Examples :

  • is_not_set(null) :white-check-mark+:
  • is_not_set("hello") :x+:
Attribute
Type
Required
Description

type

string

always is_not_set

Is number

Condition that matches if value is a number.
Floats can have . or a , as delimiter.

Examples :

  • is_number("1.3") :white-check-mark+:
  • is_number("1") :white-check-mark+:
  • is_number("1,3") :white-check-mark+:
  • is_number("hello") :x+:
Attribute
Type
Required
Description

type

string

always is_number

Is less than

Condition that matches if value is less than another number.

Examples :

  • is_less_than("12.3", 100) :white-check-mark+:
  • is_less_than("12,3", 100) :white-check-mark+:
  • is_less_than("12", 100) :white-check-mark+:
  • is_less_than("12", 1) :x+:
  • is_less_than("12", 12) :x+:
Attribute
Type
Required
Description

type

string

always is_less_than

maximum

number

maximum value

Is less than or equal

Condition that matches if value is less than or equal to another number.

Examples :

  • is_less_than_or_equal("12.3", 100) :white-check-mark+:
  • is_less_than_or_equal("12,3", 100) :white-check-mark+:
  • is_less_than_or_equal("12", 100) :white-check-mark+:
  • is_less_than_or_equal("12", 12) :white-check-mark+:
  • is_less_than_or_equal("12", 1) :x+:
Attribute
Type
Required
Description

type

string

always is_less_than_or_equal

maximum

number

maximum value

Is greater than

Condition that matches if value is greater than another number.

Examples :

  • is_greater_than("12.3", 10) :white-check-mark+:
  • is_greater_than("12,3", 10) :white-check-mark+:
  • is_greater_than("12", 10) :white-check-mark+:
  • is_greater_than("12", 12) :x+:
  • is_greater_than("12", 100) :x+:
Attribute
Type
Required
Description

type

string

always is_greater_than

maximum

number

maximum value

Is greater than or equal

Condition that matches if value is greater than or equal to another number.

Examples :

  • is_greater_than_or_equal("12.3", 10) :white-check-mark+:
  • is_greater_than_or_equal("12,3", 10) :white-check-mark+:
  • is_greater_than_or_equal("12", 10) :white-check-mark+:
  • is_greater_than_or_equal("12", 12) :white-check-mark+:
  • is_greater_than_or_equal("12", 100) :x+:
Attribute
Type
Required
Description

type

string

always is_greater_than_or_equal

maximum

number

maximum value

{
    "type": "contains",
    "values": ["hello"]
}
{
    "type": "equals",
    "expected": "hello"
}
{
    "type": "match_intent",
    "intent": {
        "id": "c1c1c1c1c1c1c1c1c1c1c1c1",
        "name": "an intent",
        "type": "intent"
    }
}
{
    "type": "match_regexp",
    "pattern": "[\w]+"
}
{
    "type": "is_set"
}
{
    "type": "is_not_set"
}
{
    "type": "is_number"
}
{
    "type": "is_less_than",
    "maximum": 10
}
{
    "type": "is_less_than_or_equal",
    "maximum": 10
}
{
    "type": "is_greater_than",
    "maximum": 10
}
{
    "type": "is_greater_than_or_equal",
    "maximum": 10
}
Suggest Edits

Value getters

 

Value getters are used to get the values which are going to be matched against conditions.
It can apply to session values, user attributes and users messages.

Session Value Getter

This value getter can be used to fetch a value from the interlocutor's session.

Attribute
Type
Required
Description

type

string

always session_value

key

string

session key to fetch

User attribute Getter

This value getter can be used to fetch a value from the interlocutor's attributes.

Attribute
Type
Required
Description

type

string

always user_attribute

key

string

attribute name to fetch

Message Value Getter

This value getter will return the content of the message sent by the interlocutor.

Attribute
Type
Required
Description

type

string

always message

{
    "key": "name",
    "type": "session_value"
}
{
    "key": "name",
    "type": "session_value"
}
{
    "type": "message"
}
Suggest Edits

Authentication

 

Our API uses access tokens to authenticate clients.

Each bot is associated to an access token.
You can find your token on your bot settings page.

Do not share your access tokens

Access tokens give access to important functions of your bot, you should keep them secret.

Usage

In order to use your access token, you need to provide it in the Authorization header when you make an HTTP request.

Make sure to use the Bearer type for your token in the header.

Example (replace ACCESS_TOKEN with your own token) :

curl -H 'Authorization: Bearer ACCESS_TOKEN' \
 https://api.clustaar.io/....
Suggest Edits

Interlocutors

 

An interlocutor represents a user talking to a bot.

In order to start talking to a Clustaar Bot using our API, you first need to create an interlocutor and then send messages to the bot referring to this interlocutor.

Suggest Edits

Create an interlocutor

 
posthttps://api.clustaar.io/bots/bot_id/interlocutors/clustaar_web_chat

Path Params

bot_id
string
required

a bot ID

 

In order to create an interlocutor you need to provide a userID.
This userID must have been generated by you, and will represent this interlocutor.

Note that if an interlocutor already exists with the same userID, the existing interlocutor is returned.

Request

Attribute
Required
Type
Description

type

string

must be interlocutor

userID

string

your ID for this interlocutor (0 < length < 100)

firstName

string

interlocutor's first name

lastName

string

interlocutor's last name

email

string

interlocutor's email

customAttributes

object

custom attributes (keys must only contain letters, digits and underscores)

Response

Attribute
Type
Description

data

object

the interlocutor object

data.id

string

interlocutor ID

data.type

string

always interlocutor

{
    "type": "interlocutor",
    "id": "5b29016e24acbe58c292bbad",
    "userID": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@provider.com",
    "customAttributes": {
        "age": "29"
    }
}
{
    "data": {
        "id": "58468b1978ad4421b0efc77a",
        "type": "interlocutor"
    }
}
Suggest Edits

Post reply

Get answer from a bot

 
posthttps://api.clustaar.io/interlocutors/interlocutor_id/reply

Path Params

interlocutor_id
string
required

the ID of the interlocutor talking to the bot

Query Params

debug
boolean

if set to 1 more information about webhook calls, and intent detection will be returned

 

This endpoint is useful to get answers from a bot.

It takes a message or an action in input and sends back actions from the bot.

Request

The request can be a text message or a go_to_action (in case of a button click).

If you sent a text message :

Attribute
Type
Description

type

string

must be text

message

string

the message content (0 < length < 500)

If user clicked on a button you must send the go_to_action associated to that button :

Attribute
Type
Description

type

string

must be go_to_action

target

object

action destination

target.type

string

can be step or story

target.id

string

target ID

Response

Attribute
Type
Description

fulfillment

object

the bot response

fulfillment.actions

array<Action>

list of the actions returned by the bot

fulfillment.source

object

where did these actions come from (can be step_actions, step_fallback_actions or story_fallback_actions)

session

object

the interlocutor's session object

session.values

object

the interlocutor's session values

interlocutor

object

the interlocutor object

input

object

input received from interlocutor

debug

object

filled only if debug parameter is 1, contains some debug information (webhook calls and intent detections scores)

debug.intentDetections

array<object>

contains the list of the detections triggered during the call

debug.intentDetections.query

string

query analyzed by the intent detector

debug.intentDetections.results

array<object>

results returned for query

debug.intentDetections.results.intent

object

intent detected for query

debug.intentDetections.results.score

float

detection score

debug.intentDetections.results.parameters

array<object>

parameters extracted from query

debug.webhookCalls

array<object>

webhook calls that happened during call

debug.webhookCalls.request

object

HTTP request sent to webhook

debug.webhookCalls.response

object

HTTP response from webhook

debug.webhookCalls.error

string

error while processing the webhook response

{
    "type": "text",
    "message": "hello",
}
{
    "type": "go_to_action",
    "target": {
        "type": "step",
        "id": "5a674ade24acbe05a8c9ade0"
    }
}
{
   "data": {
       "fulfillment": {
           "actions": [
               {
                   "type": "send_text_action",
                   "alternatives": [
                       "Hi!"
                   ]
               }
           ],
           "source": {
               "type": "step_actions",
               "step": {
                   "type": "step",
                   "id": "5a674ade24acbe05a8c9ade0",
                   "name": "First step"
               }
           }
       },
       "session": {
           "values": {}
       },
       "interlocutor": {
           "type": "interlocutor",
           "id": "5a674af524acbe7f2cb0d31a"
       },
       "input": {
           "type": "text",
           "message": "hello"
       },
       "debug": {
           "intentDetections": [
               {
                   "type": "intent_detection",
                   "query": "hello",
                   "results": [
                       {
                           "type": "intent_matching",
                           "intent": {
                               "id": "5a675cf724acbe4147b8e499",
                               "name": "bonjour"
                           },
                           "score": 1,
                           "parameters": [
                               {
                                   "name": "bonjour",
                                   "value": "bonjour"
                               }
                           ]
                       }
                   ]
               }
           ],
           "webhookCalls": [
               {
                   "request": {
                       "method": "POST",
                       "url": "https://example.com",
                       "body": "{}"
                   },
                   "response": {
                       "status": 200,
                       "body": "{"
                   },
                   "error": "RequestFailed: Invalid JSON document (JSON document from response is invalid)"
               }
           ]
       }
   }
}
Suggest Edits

Reset session

 
deletehttps://api.clustaar.io/interlocutors/interlocutor_id/session

Path Params

interlocutor_id
string
required

an interlocutor ID

 

Resets the interlocutor session.

It will clear all the session values and kick the interlocutor out of the scenario he currently is in.

Suggest Edits

Update an interlocutor

 
puthttps://api.clustaar.io/interlocutors/interlocutor_id

Path Params

interlocutor_id
string
required

an interlocutor ID

 

Private API key needed

This endpoint can only be used with your private API key, available in the API tab of your bot settings.

Update interlocutor attributes.

Note that the userID can't be updated.

Request

Attribute
Required
Type
Description

type

string

must be interlocutor

userID

string

your ID for this interlocutor (0 < length < 100)

firstName

string

interlocutor's first name

lastName

string

interlocutor's last name

email

string

interlocutor's email

customAttributes

object

custom attributes (keys must only contain letters, digits and underscores)

Response

At the moment this endpoint does not return anything.

{
    "type": "interlocutor",
    "id": "5b29016e24acbe58c292bbad",
    "userID": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@provider.com",
    "customAttributes": {
        "age": "29"
    }
}
Suggest Edits

Get an interlocutor

 
gethttps://api.clustaar.io/interlocutors/interlocutor_id

Path Params

interlocutor_id
string
required

an interlocutor ID

 

Private API key needed

This endpoint can only be used with your private API key, accessible in the API tab of your bot settings.

View an interlocutor's informations.

Response

Attribute
Type
Description

data

object

the interlocutor object

data.id

string

interlocutor ID

data.type

string

always interlocutor

data.userID

string

your ID for this interlocutor

data.firstName

string

interlocutor first name

data.lastName

string

interlocutor last name

data.customAttributes

object

custom attributes set on this interlocutor

{
   "data": {
        "type": "interlocutor",
        "id": "5b29016e24acbe58c292bbad",
        "userID": "123456",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@provider.com",
        "customAttributes": {
            "age": "29"
    	  }
    }
}

You can manually send events from your website, which will trigger pre-defined stories in the webchat.
It is useful to fine-tune the bot behaviour, and take the most from the context.

In order to configure your events, you have to go to your Clustaar Webchat settings page, in the channels tab.

In order to send an event, you first need to initialize the webchat.

Suggest Edits

Send a custom event

 

Send a custom event via the webchat.
The event name have to be the same than the one configured on the clustaar webchat channel settings of your bot.

window.ClustaarWebchat.sendCustomEvent('EVENT_NAME');
Suggest Edits

Send a url event

 

Send a URL event via webchat.
This is useful if you use a state management routing framework like Angular, React or Vuejs.

Automatic event

Don't send UrlEvent event manually if you are not using a state management routing framework: this will be done automatically.

window.ClustaarWebchat.sendUrlEvent('MY_ABSOLUTE_URL');
Suggest Edits

Webchat state

 

You can use JavaScript to chose webchat window state: open, or closed (minimized).

Suggest Edits

Toggle the webchat

 

Change webchat window state.

  • If it is open, it will be minimized,
  • If it is minimized, it will be open
window.ClustaarWebchat.ToggleWebchat();
Suggest Edits

Open the webchat

 

Force the opening of the webchat window.

window.ClustaarWebchat.openWebchat();
Suggest Edits

Close the webchat

 

Force the minimizing of the webchat window.

window.ClustaarWebchat.CloseWebchat();