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.

Suggest Edits

Return Data Format

Webhook Return Data Format

 

When the Webhook is done doing its work, it must return the list of actions to execute for the current step.
The minimal JSON Object to be returned should be a list of Actions associated to an Interlocutor, under the form:

{
  "actions": []
}

You can also add a Sessions object, to force some Session Values and an Interlocutor Object:

{
  "actions": [],
  "interlocutor": {},
  "session": {}
}

A more real life looking object should look like this:

{
	"actions": [{
		"type": "send_text_action",
		"alternatives": ["Hello", "Hi"]
	}],
	"interlocutor": {
		"type": "interlocutor",
		"id": "5b29016e24acbe58c292bbad",
		"userID": "123456",
		"firstName": "John",
		"lastName": "Doe",
		"email": "[email protected]",
		"customAttributes": {
			"age": "29"
		}
	},
	"sessions": {
		"foo": "bar",
		"name": "john"
	}
}

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

object

input that triggered the execution

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.interlocutor.phoneNumber

string

interlocutor's phone number

data.session.values

object

interlocutor's session's values

data.step.id

string

ID of step being executed

data.step.name

string

name of step being executed

data.step.userData

string

custom data set on the step with the [+] next to the "use webhook" toggle on the step form

data.step.actions

array

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

data.interlocutor.phoneNumber

string

interlocutor's phone number

Request

{
    "topic": "conversation.step_reached",
    "botID": "507f1f77bcf86cd799439011",
    "timestamp": 1514998709,
    "type": "event",
    "data": {
        "channel": "facebook",
        "input": {
            "type": "message",
            "text:" "hello",
            "attachments": []
        },
        "interlocutor": {
            "id": "507f1f77bcf86cd799439011",
            "userID": "xxyyzz",
            "location": {
                "lat": 77.415040,
                "long": -44.052074
            },
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "customAttributes": {
                "age": "25"
            },
            "phoneNumber": null
        },
        "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": "[email protected]",
      	"customAttributes": {
          	"age": "25"
        },
        "phoneNumber": null
    }
}
 

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-Hub-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 and the Date header.

Example :

import hashlib
import hmac


def generate_signature(private_key, request_body, date_header):
    """
    Args:
        private_key (str): webhook private key
        request_body (str): the HTTP request body
        date_header (str): the value of the 'Date' header of the request
    """
    buffer = "date=" + date_header + "\n" + payload
    return "sha1=" + hmac.new(private_key.encode(),
                              buffer.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)
  • webchat
Attribute
Type
Required
Description

type

string

always send_image_action

imageURL

string

a valid URL (length<=500)

alt

string

the alt attribute provides an alternate text for the user, if he/she for some reason cannot view the image

{
    "type": "send_image_action",
    "imageURL": "http://example.com/logo.png",
    "alt": "Company Logo"
}
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)

fromEmail

string

a valid email used to change the default sender email

fromName

string

a name used to change the default sender name

{
    "type": "send_email_action",
    "recipient": "[email protected]",
    "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
  • Clustaar Webchat
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.alt

string

The alt attribute provides an alternate text for the user, if he/she for some reason cannot view the image

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",
            "alt": "Company Logo",
            "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
  • webchat
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

Send JS event

 

Send a custom json event to the clustaar webchat.

Available on :

  • clustaar webchat
Attribute
Type
Required
Description

type

string

always send_text_action

event

string

the custom event name (event_length>=1, event_length<=200)

{
    "type": "send_js_event_action",
    "event": "test-event"
}
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": "[email protected]",
        "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
  • Clustaar Webchat
Attribute
Type
Required
Description

type

string

always go_to_action

target.type

string

target type (step or story)

target.id

string

target ID

sessionValues

object

values added to session if button is clicked

{
    "type": "go_to_action",
    "sessionValues": {
        "key": "value"
    },
    "target": {
        "type": "step",
        "id": "12"
    }
}
 

Open an URL when button is pressed.

Available on :

  • Facebook
  • Clustaar Webchat
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

Bot inputs

 

A bot input can be a message, an action, an event, etc.

 

A message sent by a user.

Attribute
Type
Description

type

string

always message

text

string

message content

attachments

array

a list of attachment objects (see below)

File attachment

Attribute
Type
Description

type

string

always file

url

string

file URL

Video file attachment

Attribute
Type
Description

type

string

always video

url

string

video file URL

Image file attachment

Attribute
Type
Description

type

string

always image

url

string

image file URL

Audio file attachment

Attribute
Type
Description

type

string

always audio

url

string

audio file URL

{
    "type": "message",
    "text": "hello",
    "attachments": []
}
{
    "type": "file",
    "url": "http://example.com/file.zip"
}
{
    "type": "video",
    "url": "http://example.com/file.mp4"
}
{
    "type": "image",
    "url": "http://example.com/file.png"
}
{
    "type": "audio",
    "url": "http://example.com/file.mp3"
}
Suggest Edits

URL loaded event

 

Sent when a step has been triggered when the webchat was loaded on a specific page.

Attribute
Type
Description

type

string

always url_loaded_event

url

string

URL that triggered the event

{
    "type": "url_loaded_event",
    "url": "http://example.com"
}
Suggest Edits

Custom event

 

Sent when a step has been triggered when the webchat sent a custom event.

Attribute
Type
Description

type

string

always custom_event

name

string

event name

{
    "type": "custom_event",
    "url": "div1_clicked"
}
Suggest Edits

Go to input

 

Sent when a step is triggered by a button click.

Attribute
Type
Required

type

string

always go_to_action

target.type

string

target type (step or story)

target.id

string

target ID

sessionValues

object

values added to session if button is clicked

{
    "type": "go_to_action",
    "sessionValues": {
        "key": "value"
    },
    "target": {
        "type": "step",
        "id": "12"
    }
}
Suggest Edits

Conversation Element

Piece of Conversation Object

 

A Conversation Element is an object containing an interlocutor interaction (text, button action, url loaded event, custom event) and the corresponding bot answer.
The Conversation Element objects are used in the return value of the Conversation history endpoints.

Attribute
Type
Description

interlocutor_id

String

The interlocutor id of the conversation element

interlocutor

Interlocutor

The interlocutor, consolidated only for search results

timestamp

Long

Time in second after epoch of the interlocutor query

bot_id

String

The bot ID

input_source

Source

Qualify the source on input_action, (interlocutor or user)

output_source

Source

Qualify the source of the answer, (the bot)

input_action.source

Source

Usually the same input_source

input_action.action

Action

The interlocutor action (Message or Go to) that trigger the bot answers or the support agent text (to the interlocutor)

input_event.source

Source

Qualify the source of input_event (when there is one)

input_event.event

Map

Open schema when can be save special event like the take_control event

output_actions

List

List of all the actions the bot executed to reply to the interlocutor. The list is distributed into 2 levels, so the actions are grouped by step source (where the actions are defined)

output_actions[].source

Source

The story/step source of the actions in following field "actions"

output_actions[].actions[].action

Action

An action as bot response

output_actions[].actions[].parents[]

List of actions

In case the previous action is transformed from another kind of action (ex : google_custom_search action is transformed into send_cards_action to be displayed to user), this is the list (usually one) of originated action.

Source object

Attribute
Type
Description

type

String

bot/interlocutor/story/step/actions_block/user

id

String

the Id of the type object

name

String

name of the type object


{
  "interlocutor_id": "5c58414ffd43ca0010fa1ae1",
  "timestamp": 1557157686,
  "bot_id": "5bfe9b243422d7000e046da8",
  "input_source": {
      "type": "interlocutor",
      "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
  },
  "output_source": {
      "type": "bot",
      "bot_id": "5bfe9b243422d7000e046da8"
  },
  "input_action": {
      "source": {
          "type": "interlocutor",
          "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
      },
     "action": {
       "type": "text",
         "message": "hello robot"
     }
  },
  "output_actions": [
    {
      "source": {
        "type": "actions_block",
        "actions_block_id": "5bfe9b25e6b7bb0009914338"
      },
      "actions": [
        {
          "action": {
            "type": "wait_action",
            "duration": 2
          },
          "parent_actions": []
        },
        {
          "action": {
            "type": "send_text_action",
            "alternatives": [
              "Hello you.\n"
            ],
            "text": "Hello you.\n"
          },
          "parent_actions": []
        },
        {
          "action": {
            "type": "wait_action",
            "duration": 2
          },
          "parent_actions": []
        },
        {
          "action": {
            "type": "send_text_action",
            "alternatives": [
              "How do you do ?"
            ],
            "text": "How do you do ?"
          },
          "parent_actions": []
        }
      ]
    }
  ]
}
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/....

Interlocutor Authentication

When creating an interlocutor via Create an interlocutor, the field socketToken is a security token used primarily to secure the conversation an interlocutor has with the bot.
This token can also be used to authenticated some API calls Get interlocutor actions.
To build a Bearer token, encode the following json in base64. Use the interlocutor socketToken as the value field, and the interlocutor_id as id field

{
 "value":"socketTokenvalue",
 "subject":{"id": "interlocutor_id", 
            "type": "interlocutor"}
 }
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

Query Params

use_websocket
boolean

When set to True, generate and return a 'socketToken' used for websocket connexion. The 'socketToken' is return only once for security reason

 

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

phoneNumber

string

interlocutor's phone number

customAttributes

object

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

socketToken

string

a security token set for the interlocutor. Must be set if this token must be known by the integrating website (in logged envirnement fro example). Otherwise might be automatically generated by clustaar (with query param 'use_websocket')

Response

Attribute
Type
Description

data

object

the interlocutor object

data.id

string

interlocutor ID

data.type

string

always interlocutor

data.socketToken

string

if use_websocket is passed in query parameters, socketToken is returned, but only once for security reason.

{
    "type": "interlocutor",
    "id": "5b29016e24acbe58c292bbad",
    "userID": "123456",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "0612239588"
    "email": "[email protected]",
    "customAttributes": {
        "age": "29"
    }
}
{
    "data": {
        "id": "58468b1978ad4421b0efc77a",
        "type": "interlocutor",
      	"socketToken":"fezfl3z4nfl5224zef6n_nfkj7znf735nze"
    }
}
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

channel
string

Use in fonction of the channel you want use. The response can be different between two channel. Channel can be clustaar_web_chat, facebook, intercom, twillo, google_assistant, iadvize

 

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, a go_to_action (in case of a button click) or an event (configured in the webchat channel).

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

If you want to trigger an event configured in the Webchat channel, you to use a custom_event

Attribute
Type
Description

type

string

must be custom_event

name

string

your event name

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"
    }
}
{
    "name": "EVENT_NAME",
    "type": "custom_event"
}
{
   "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

phoneNumber

string

interlocutors' phone number

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": "[email protected]",
    "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.botID

string

the bot 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.email

string

interlocutor email

data.phoneNumber

string

interlocutor phone number

data.createdAt

string

interlocutor creation date

data.lastReplyAt

string

interlocutor last reply date

data.customAttributes

object

custom attributes set on this interlocutor

{
   "data": {
        "type": "interlocutor",
        "id": "5d2af1df10cf4e000b67b97d",
        "userID": "clustaar-5fenfnew",
        "location": null,
        "firstName": null,
        "lastName": null,
        "createdAt": "2019-07-14T09:11:59+0000",
        "lastReplyAt": "2020-02-07T15:57:43+0000",
        "email": null,
        "phoneNumber": null,
        "customAttributes": {},
        "botID": "5c418eb73bb708000bc80386"
    }
}
Suggest Edits

Clear User Data History

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

Path Params

interlocutor_id
string
required

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

Clear interlocutor data history.

It will delete all sensible information about the interlocutor:

  • user attributes,
  • user sessions,
  • conversations.

The interlocutor will still be available, but emptied from all his data.

Interlocutor attributes:

  • All interlocutor attributes are deleted after the clear (first_name, last_name, email, phone_number, position).

Interlocutor attributes can be set by Set user attribute action.

Custom attributes:

  • All custom attributes are deleted after the clear.

Custom attributes can be set by Set user attribute action or from the clustaar webchat SDK.

Conversation session:

  • The interlocutor conversation session (which contains session values) is deleted after the clear.

Session values can be set by Store session value action.

Conversation history:

  • All interlocutor messages (and the bot replies) are deleted after the clear.

User request:

  • All user requests created by this interlocutor become anonymous and the interlocutor is no longer related to these user requests after the clear.

The "last reply" field related to this interlocutor will be also deleted.

Suggest Edits

Get Interlocutor Actions

Get history of the "verbose" interlocutor conversation as a list of actions

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

Path Params

interlocutor_id
string
required

id of the interlocutor

Query Params

limit
int32

limit the number of actions to return

page
int32

page of actions. The pagination is inversed compared to usual. The first page contains the last actions of the conversati

 

Get the actions of a conversation between an interlocutor and the bot (or support agents).
Only actions which are visible in the conversation will be returned by this endpoint; all silent actions will be absent.
.
The actions are returned in chronological order in the response (first is older, last is newer), but the pagination is inverted : page 1 returns the newest actions, page 2 older ones , ...)

The aim of this endpoint is to retrieve an interlocutor Conversation History in some situations where its is only meant to be displayed to a human.
This is the reason only displayed actions are retrieved, and the API is authenticated by the interlocutor token, instead of the bot public token.

Authenticated API

This endpoint can be used with your private API key, available in the API tab of your bot settings. But it's firstly meant to be used with the interlocutor authentication

Response

Attribute
Type
Description

data[].type

string

type of the action

data[].xxx

depending of the type

fields of the actions

{"data":[
   {
            "type": "go_to_action",
            "target": {
                "id": "5b55c9896efef6010be13a41",
                "type": "story",
                "name": "Menu"
            },
            "sessionValues": null
        },
        {
            "type": "wait_action",
            "duration": 1.1
        },
        {
            "type": "send_text_action",
            "alternatives": [
                "Let's go !"
            ],
            "text": "Let's go !"
        },
        {
            "type": "wait_action",
            "duration": 1
        },
        {
            "type": "send_js_event_action",
            "event": "close_div_1"
        }
  ]
}}
Suggest Edits

Statistics

 

The following endpoint allows to get the various statistics collected on a bot

Private API key needed

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

Suggest Edits

Statistic on bot

 
gethttps://api.clustaar.io/bots/bot_id/stats/bot

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get the total messages and interlocutors who interacted with the bot

Response

Attribute
Type
Description

data.type

string

always "bot_stats"

data.messagesCount

int

the number of messages received by the bot

data.interlocutorsCount

int

the numbers of interlocutors

data.buttonsActionsCount

int

the numbers of actions that are launched by a button

{
    "data": {
        "type": "bot_stats",
        "messagesCount": 0,
        "interlocutorsCount": 0,
        "buttonsActionsCount": 0
    }
}
Suggest Edits

Daily statistics on bot

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_bot

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get the total messages and interlocutors who interacted with the bot per day

Response

Attribute
Type
Description

data[].type

string

always "timed_bot_stats"

date

string

iso date of object. "2018-10-02T00:00:00+0000"

data[].messagesCount

int

the number of messages received by the bot

data[].interlocutorsCount

int

the numbers of interlocutors

data[].buttonsActionsCount

int

the numbers of actions that are launched by a button

{
    "data": [
        {
            "type": "timed_bot_stats",
            "date": "2018-10-01T00:00:00+0000",
            "messagesCount": 15,
            "interlocutorsCount": 10,
            "buttonsActionsCount": 20
        },
        {
            "type": "timed_bot_stats",
            "date": "2018-10-02T00:00:00+0000",
            "messagesCount": 25,
            "interlocutorsCount": 20,
            "buttonsActionsCount": 30
        },
        {
            "type": "timed_bot_stats",
            "date": "2018-10-03T00:00:00+0000",
            "messagesCount": 35,
            "interlocutorsCount": 30,
            "buttonsActionsCount": 40
        }
    ]
}
Suggest Edits

Intents matches statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/intents_matches

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

intent_ids
array of strings

define the targeted intents of the analyze (comma separated list of intent IDs)

order
string

define the order (can be +matches_percent or -matches_percent default order is DESC)

page
int32

the page number

limit
int32

define the number of returned results

 

Get for each intent the matches statistics for a given period

Response

Attribute
Type
Description

data[].type

string

always "intent_match_stats"

data[].intentID

string

the intent id

data[].intentName

string

the intent name

data[].matchesCount

int

the number of matches

data[].matchesPercent

float

the matches percent

{
    "data": [
        {
            "type": "intent_match_stats",
            "intentID": "a2a2a2a2a2a2a2a2a2a2a2a2",
            "intentName": "intent_stat_test",
            "matchesCount": 17,
            "matchesPercent": 0.298245614
        },
        {
            "type": "intent_match_stats",
            "intentID": "b1b1b1b1b1b1b1b1b1b1b1b1",
            "intentName": "intent_stat_test",
            "matchesCount": 25,
            "matchesPercent": 0.4385964912
        },
    ]
}
Suggest Edits

Daily intents matches statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_intents_matches

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

intent_ids
array of strings

define the targeted intents of the analyze (comma separated list of intent IDs)

 

Get for each intent the matches statistic for a given period

Response

Attribute
Type
Description

data[].type

string

always "timed_intent_match_stats"

data[].date

string

iso date of the statistic "2018-10-01T00:00:00+0000"

data[].intentID

string

the intent id

data[].intentName

string

the intent name

data[].matchesCount

int

the number of matches

data[].matchesPercent

float

the matches percent

{
    "data": [
        {
            "type": "timed_intent_match_stats",
            "date": "2018-10-01T00:00:00+0000",
            "intentID": "a2a2a2a2a2a2a2a2a2a2a2a2",
            "intentName": "intent_stat_test",
            "matchesCount": 17,
            "matchesPercent": 0.298245614
        },
        {
            "type": "timed_intent_match_stats",
            "date": "2018-10-01T00:00:00+0000",
            "intentID": "b1b1b1b1b1b1b1b1b1b1b1b1",
            "intentName": "intent_stat_test",
            "matchesCount": 25,
            "matchesPercent": 0.4385964912
        },
        {
            "type": "timed_intent_match_stats",
            "date": "2018-10-02T00:00:00+0000",
            "intentID": "b1b1b1b1b1b1b1b1b1b1b1b1",
            "intentName": "intent_stat_test",
            "matchesCount": 25,
            "matchesPercent": 0.5813953488
        }
    ]
}
Suggest Edits

Daily global matches rate statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_global_matches_rate

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get daily global matches rate of a bot for a given period

Response

Attribute
Type
Description

data[].type

string

always "timed_global_matches_rate_stats"

data[].date

string

iso date of the statistics
"2018-12-10T00:00:00+0000"

data[].matchesPercent

float

the matches percent

{
  "data": [
    {
      "type": "timed_global_matches_rate_stats",
      "date": "2018-12-10T00:00:00+0000",
      "matchesPercent": 0.9
    }
  ]
}
Suggest Edits

Bot satisfaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/bot_satisfaction

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get bot satisfaction stats for a given period. The satisfaction are collected thanks to User Feedback step

Response

Attribute
Type
Description

data.type

string

always "bot_global_satisfaction"

data.positiveRatingsCount

int

the number of positive ratings

data.negativeRatingsCount

int

the numbers of negative ratings

data.ratingsCount

int

total number of ratings received

data.satisfactionStepExecutionsCount

int

number of times satisfaction was asked

data.positiveRatingsPercent

float

percentage of positive ratings

data.negativeRatingsPercent

float

percentage of negative ratings

data.satisfactionCompletionPercent

float

percentage of person that completed the satisfaction

{
    "data": {
        "type": "bot_global_satisfaction",
        "positiveRatingsCount": 11,
        "negativeRatingsCount": 10,
        "ratingsCount": 21,
        "satisfactionStepExecutionsCount": 38,
        "positiveRatingsPercent": 0.5238095238,
        "negativeRatingsPercent": 0.4761904762,
        "satisfactionCompletionPercent": 0.5526315789
    }
}
Suggest Edits

Daily bot satisfaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_bot_satisfaction

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get daily bot satisfaction stats for a given period. The satisfaction are collected thanks to User Feedback step

Response

Attribute
Type
Description

data[].type

string

always "timed_bot_global_satisfaction"

data[].date

string

date of the statistic "2018-10-05"

data[].positiveRatingsCount

int

the number of positive ratings

data[].negativeRatingsCount

int

the numbers of negative ratings

data[].ratingsCount

int

total number of ratings received

data[].satisfactionStepExecutionsCount

int

number of times satisfaction was asked

data[].positiveRatingsPercent

float

percentage of positive ratings

data[].negativeRatingsPercent

float

percentage of negative ratings

data[].satisfactionCompletionPercent

float

percentage of person that completed the satisfaction

{
    "data": [
        {
            "type": "timed_bot_global_satisfaction",
            "positiveRatingsCount": 5,
            "negativeRatingsCount": 5,
            "ratingsCount": 10,
            "satisfactionStepExecutionsCount": 20,
            "positiveRatingsPercent": 0.5,
            "negativeRatingsPercent": 0.5,
            "satisfactionCompletionPercent": 0.5,
            "date": "2018-10-05"
        },
        {
            "type": "timed_bot_global_satisfaction",
            "positiveRatingsCount": 6,
            "negativeRatingsCount": 5,
            "ratingsCount": 11,
            "satisfactionStepExecutionsCount": 18,
            "positiveRatingsPercent": 0.5454545455,
            "negativeRatingsPercent": 0.4545454545,
            "satisfactionCompletionPercent": 0.6111111111,
            "date": "2018-10-06"
        }
    ]
}
Suggest Edits

Stories satisfaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/stories_satisfaction

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

order
string

column to sort (prefix with - ou +) the results upon (can be one of ratings_count, positive_ratings_count, negative_ratings_count)

search
string

search story by name (case insensitive)

limit
int32

number of results per page

page
int32

page of results

 

Get stories satisfaction stats for a given period. The satisfaction are collected thanks to User Feedback step. There can be one User Feedback step per story. This endpoint allow to get the satisfaction per story.

Response

Attribute
Type
Description

data[].type

string

always "story_satisfaction"

data[].storyName

string

the story name

data[].storyID

string

the story ID

data[].positiveRatingsCount

int

the number of positive ratings

data[].negativeRatingsCount

int

the numbers of negative ratings

data[].ratingsCount

int

total number of ratings received

data[].satisfactionStepExecutionsCount

int

number of times satisfaction was asked

data[].positiveRatingsPercent

float

percentage of positive ratings

data[].negativeRatingsPercent

float

percentage of negative ratings

data[].satisfactionCompletionPercent

float

percentage of person that completed the satisfaction

{
    "data": [
        {
            "type": "story_satisfaction",
            "storyName": "story 27",
            "storyID": "a27a27a27a27a27a27a27a27",
            "positiveRatingsCount": 55,
            "negativeRatingsCount": 24,
            "ratingsCount": 79,
            "satisfactionStepExecutionsCount": 95,
            "positiveRatingsPercent": 0.6962025316,
            "negativeRatingsPercent": 0.3037974684,
            "satisfactionCompletionPercent": 0.8315789474
        }
    ]
}
Suggest Edits

Daily stories satisfaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_stories_satisfaction

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

story_ids
array of strings

comma separated list of story IDs

 

Get daily stories satisfaction stats for a given period. The satisfaction are collected thanks to User Feedback step. There can be one User Feedback step per story. This endpoint allow to get the satisfaction per story.

Response

Attribute
Type
Description

data[].type

string

always "timed_story_satisfaction"

data[].date

string

date of the statistic "2018-10-05"

data[].storyName

string

the story name

data[].storyID

string

the story ID

data[].positiveRatingsCount

int

the number of positive ratings

data[].negativeRatingsCount

int

the numbers of negative ratings

data[].ratingsCount

int

total number of ratings received

data[].satisfactionStepExecutionsCount

int

number of times satisfaction was asked

data[].positiveRatingsPercent

float

percentage of positive ratings

data[].negativeRatingsPercent

float

percentage of negative ratings

data[].satisfactionCompletionPercent

float

percentage of person that completed the satisfaction

{
    "data": [
        {
            "type": "timed_story_satisfaction",
            "storyName": "story 27",
            "storyID": "a27a27a27a27a27a27a27a27",
            "positiveRatingsCount": 18,
            "negativeRatingsCount": 4,
            "ratingsCount": 22,
            "satisfactionStepExecutionsCount": 24,
            "positiveRatingsPercent": 0.8181818182,
            "negativeRatingsPercent": 0.1818181818,
            "satisfactionCompletionPercent": 0.9166666667,
            "date": "2018-01-27"
        }
    ]
}
Suggest Edits

Steps executions statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/steps_stats

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

story_id
string
required

the story ID

step_ids
array of strings

comma separated list of step IDs

search
string

filter string. If set, return only steps which contains the value in its name

order
string

column to sort the results upon (can be executions_count, in both order - prefix with + or -)

limit
int32

number of results per page

page
int32

page of results

 

Get the daily steps executions stats.

Response

Attribute
Type
Description

data[].type

string

always "step_executions_stats"

data[].stepID

string

the step ID

data[].stepName

string

the step name

data[].executionsCount

int

the number of hit of the step

data[].fallbacksCount

int

the number of hit of the step’s fallback

data[].executionsPercent

float

rate of hit of the step on the total hit of steps for the day

{
    "data": [
        {
            "type": "step_executions_stats",
            "stepID": "5b06d94cb76715002e6a12a6",
            "stepName": "hello world",
            "executionsCount": 42,
            "fallbacksCount": 0,
            "executionsPercent": 0.3962264151
        },
        {
            "type": "step_executions_stats",
            "stepID": "5c3f037a4525f0005fecd5e5",
            "stepName": "JOKE (event triggered)",
            "executionsCount": 34,
            "fallbacksCount": 0,
            "executionsPercent": 0.320754717
        },
        {
            "type": "step_executions_stats",
            "stepID": "5c3f0a474525f0005fecd609",
            "stepName": "PRICING",
            "executionsCount": 20,
            "fallbacksCount": 0,
            "executionsPercent": 0.1886792453
        }
    ]
}
Suggest Edits

Daily steps executions statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_steps_stats

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

story_id
string
required

the story ID

step_ids
array of strings

comma separated list of step IDs

limit
int32

number of results per page

page
int32

page of result

 

Get the daily steps executions stats.

Response

Attribute
Type
Description

data[].type

string

always "timed_step_executions_stats"

data[].date

string

date of object. "2018-10-02"

data[].stepID

string

the step ID

data[].stepName

string

the step name

data[].executionsCount

int

the number of hit of the step

data[].fallbacksCount

int

the number of hit of the step’s fallback

data[].executionsPercent

float

rate of hit of the step on the total hit of steps for the day

{
    "data": [
        {
            "type": "timed_step_executions_stats",
            "stepID": "5b06d94cb76715002e6a12a6",
            "stepName": "hello world",
            "executionsCount": 2,
            "fallbacksCount": 0,
            "executionsPercent": 0.6666666667,
            "date": "2019-01-24"
        },
        {
            "type": "timed_step_executions_stats",
            "stepID": "5b06d94cb76715002e6a12a6",
            "storyName": "hello world",
            "executionsCount": 1,
            "fallbacksCount": 0,
            "executionsPercent": 1,
            "date": "2019-01-27"
        }
    ]
}
Suggest Edits

Stories executions statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/stories_stats

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

story_ids
array of strings

comma separated list of story IDs

search
string

filter string. If set, return only stories which contains the value in its name

order
string

column to sort the results upon (can be executions_count, in both order )

limit
int32

limit number of results

page
int32

page of results

ignore_welcome_story
boolean

ignore the welcom story for the results. welcom story is configured in clustaar channel

ignored_story_ids
array of strings

comma separated list of story ID to ignore from the results

 

Get bot stories executions stats

Response

Attribute
Type
Description

data[].type

string

always "story_executions_stats"

data[].storyID

string

the story ID

data[].storyName

string

the story name

data[].executionsCount

int

the number of hit of the story

data[].fallbacksCount

int

the number of hit of the story’s fallback step

data[].executionsPercent

float

rate of hit of the story on the total hit of stories for the day

{
    "data": [
        {
            "type": "story_executions_stats",
            "storyID": "5b06d94cb76715002e6a12a6",
            "storyName": "hello world",
            "executionsCount": 42,
            "fallbacksCount": 0,
            "executionsPercent": 0.3962264151
        },
        {
            "type": "story_executions_stats",
            "storyID": "5c3f037a4525f0005fecd5e5",
            "storyName": "JOKE (event triggered)",
            "executionsCount": 34,
            "fallbacksCount": 0,
            "executionsPercent": 0.320754717
        },
        {
            "type": "story_executions_stats",
            "storyID": "5c3f0a474525f0005fecd609",
            "storyName": "PRICING",
            "executionsCount": 20,
            "fallbacksCount": 0,
            "executionsPercent": 0.1886792453
        },
        {
            "type": "story_executions_stats",
            "storyID": "5b07d3c7b7671500d2a47375",
            "storyName": "Expériences",
            "executionsCount": 5,
            "fallbacksCount": 2,
            "executionsPercent": 0.0471698113
        },
        {
            "type": "story_executions_stats",
            "storyID": "5b06d8fdd370e4000791a422",
            "storyName": "Fallback story",
            "executionsCount": 4,
            "fallbacksCount": 0,
            "executionsPercent": 0.0377358491
        },
        {
            "type": "story_executions_stats",
            "storyID": "5b07d3f5b7671500d2a47377",
            "storyName": "Data Bricolage",
            "executionsCount": 1,
            "fallbacksCount": 0,
            "executionsPercent": 0.0094339623
        }
    ]
}
Suggest Edits

Daily stories executions statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_stories_stats

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

story_ids
array of strings

comma separated list of story IDs

limit
int32

number of results per page

pages
int32

page of results

 

Get bot steps executions stats

Response

Attribute
Type
Description

data[].type

string

always "timed_story_executions_stats"

data[].date

string

date of statistic "2019-01-24"

data[].storyID

string

the story ID

data[].storyName

string

the story name

data[].executionsCount

int

the number of hit of the story

data[].fallbacksCount

int

the number of hit of the story’s fallback step

data[].executionsPercent

float

rate of hit of the story on the total hit of stories for the day


{
    "data": [
        {
            "type": "timed_story_executions_stats",
            "storyID": "5b06d94cb76715002e6a12a6",
            "storyName": "hello world",
            "executionsCount": 2,
            "fallbacksCount": 0,
            "executionsPercent": 0.6666666667,
            "date": "2019-01-24"
        },
        {
            "type": "timed_story_executions_stats",
            "storyID": "5b06d94cb76715002e6a12a6",
            "storyName": "hello world",
            "executionsCount": 1,
            "fallbacksCount": 0,
            "executionsPercent": 1,
            "date": "2019-01-27"
        },
        {
            "type": "timed_story_executions_stats",
            "storyID": "5b06d94cb76715002e6a12a6",
            "storyName": "hello world",
            "executionsCount": 6,
            "fallbacksCount": 0,
            "executionsPercent": 0.4285714286,
            "date": "2019-01-28"
        },
        {
            "type": "timed_story_executions_stats",
            "storyID": "5c3f037a4525f0005fecd5e5",
            "storyName": "JOKE (event triggered)",
            "executionsCount": 16,
            "fallbacksCount": 0,
            "executionsPercent": 1,
            "date": "2019-01-23"
        },
        {
            "type": "timed_story_executions_stats",
            "storyID": "5c3f037a4525f0005fecd5e5",
            "storyName": "JOKE (event triggered)",
            "executionsCount": 1,
            "fallbacksCount": 0,
            "executionsPercent": 0.3333333333,
            "date": "2019-01-24"
        },
        {
            "type": "timed_story_executions_stats",
            "storyID": "5c3f037a4525f0005fecd5e5",
            "storyName": "JOKE (event triggered)",
            "executionsCount": 5,
            "fallbacksCount": 0,
            "executionsPercent": 0.3571428571,
            "date": "2019-01-28"
        }
    ]
}
Suggest Edits

Interlocutor interaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/interlocutor

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

 

Get statistic on interlocutor interaction with the bot for the period

Response

Attribute
Type
Description

data.type

string

always "interlocutors_interactions_stats"

data.interactionsCount

int

the number of interaction (messagesCount + buttonActionCount)

data.messagesCount

string

the number of messages

data.buttonActionsCount

int

the number of button action

data.interlocutorsCount

int

the number of unique interlocutor who interact during the period

data.interlocutorsDayCount

int

the number of interlocutor x day on the period. a unique interlocutor who talk to the bot on two days, count as 2

data.interactionsPerInterlocutorCount

float

mean of number of interaction per interlocutor

data.messagesPerInterlocutorCount

float

mean of number of message per interlocutor

data.buttonActionsPerInterlocutorCount

float

mean of button action of interaction per interlocutor

data.interactionsPerInterlocutorDayCount

float

mean of number of interaction per interlocutor x day

data.messagesPerInterlocutorDayCount

float

mean of number of message per interlocutor x day

data.buttonActionsPerInterlocutorDayCount

float

mean of button action of interaction per interlocutor x day

{
    "data": {
        "type": "interlocutors_interactions_stats",
        "interactionsCount": 11,
        "messagesCount": 7,
        "buttonActionsCount": 4,
        "interlocutorsCount": 1,
        "interlocutorsDayCount": 3,
        "interactionsPerInterlocutorCount": 11,
        "messagesPerInterlocutorCount": 7,
        "buttonActionsPerInterlocutorCount": 4,
        "interactionsPerInterlocutorDayCount": 3.6666666667,
        "messagesPerInterlocutorDayCount": 2.3333333333,
        "buttonActionsPerInterlocutorDayCount": 1.3333333333
    }
}
Suggest Edits

Daily interlocutor interaction statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/daily_interlocutor

Path Params

bot_id
string
required

a bot ID

Query Params

start_date
string
required

define the start date of the analysis, format must be %Y-%m-%d

end_date
string
required

define the end date of the analysis, format must be %Y-%m-%d.

limit
int32

limit number of results

page
int32

page of results

 

Get statistic on interlocutor interaction with the bot

Response

Attribute
Type
Description

data[].type

string

always "timed_interlocutors_interactions_stats"

data[].date

string

date of statistic "2019-01-24"

data[].interactionsCount

int

the number of interaction (messagesCount + buttonActionCount)

data[].messagesCount

string

the number of messages

data[].buttonActionsCount

int

the number of button action

data[].interlocutorsCount

int

the number of interlocutor who interact on the date

data[].interactionsPerInterlocutorCount

float

mean of number of interaction per interlocutor

data[].messagesPerInterlocutorCount

float

mean of number of message per interlocutor

data[].buttonActionsPerInterlocutorCount

float

mean of button action of interaction per interlocutor

{
    "data": [
        {
            "type": "timed_interlocutors_interactions_stats",
            "date": "2019-06-28",
            "interactionsCount": 1,
            "messagesCount": 1,
            "buttonActionsCount": 0,
            "interlocutorsCount": 1,
            "interactionsPerInterlocutorCount": 1,
            "messagesPerInterlocutorCount": 1,
            "buttonActionsPerInterlocutorCount": 0
        },
        {
            "type": "timed_interlocutors_interactions_stats",
            "date": "2019-06-27",
            "interactionsCount": 4,
            "messagesCount": 3,
            "buttonActionsCount": 1,
            "interlocutorsCount": 1,
            "interactionsPerInterlocutorCount": 4,
            "messagesPerInterlocutorCount": 3,
            "buttonActionsPerInterlocutorCount": 1
        },
        {
            "type": "timed_interlocutors_interactions_stats",
            "date": "2019-07-02",
            "interactionsCount": 6,
            "messagesCount": 3,
            "buttonActionsCount": 3,
            "interlocutorsCount": 1,
            "interactionsPerInterlocutorCount": 6,
            "messagesPerInterlocutorCount": 3,
            "buttonActionsPerInterlocutorCount": 3
        }
    ]
}
Suggest Edits

Step dilution statistics

 
gethttps://api.clustaar.io/bots/bot_id/stats/step_dilution_stats

Path Params

bot_id
string
required

a bot ID

Query Params

step_id
string
required

The id of step to get the dilution stats

 

Get step dilution stats on a 30 days period in a graph format from the step_id set in query param

Response

attribute
type
description

data.nodes[]

object

node of the dilution graph. represent a step

data.nodes[].id

string

id of node

data.nodes[].name

string

name of node (step or story name)

data.nodes[].in_target_story

boolean

true is the node is a step in the same story as the request step id

data.nodes[].exit_story

boolean

is the node is outside the story (case of NLP fallback)

data.edges[]

object

edge between the step and the nodes

data.edge[].to_id

string

id of node in the nodes list

data.edge[].to_name

string

name of node in the nodes list

data.edge[].to_type

string

type of node in the nodes list

data.edge[].dilution

float

% of dilution toward this node

data.edge[].hit

int

number of hit toward this node

data.edge[].type

string

LeafStepEdge/StepEdge. LeafStepEdge the edge gives information between 2 node, StepEdge aggregate several edges information (see detail)

data.edge[].detail

list

if StepEdge, list of other StepEdges wich this one agregate. if LeafStepEdge, list of the type of link to this step, the number of hit for each one, and the % of repartition

data.summary.in_story_count

int

number of hit toward step in the same story

data.summary.out_story_count

int

number of hit toward other stories

data.summary.exit_story_count

int

number of hit toward stories via nlp fallback

summary.total_count

int

total of hit out of the step

{
    "data": {
        "nodes": [
            {
                "id": "5b07d61bb7671500d2a4737b",
                "name": "Cherche XP",
                "in_target_story": true,
                "exit_story": false
            },
            {
                "id": "5b07d3f5b7671500d2a47378",
                "name": "Data Bricolage",
                "in_target_story": false,
                "exit_story": false
            },
            {
                "id": "5b07d417b7671500cf92491f",
                "name": "La Barbe",
                "in_target_story": false,
                "exit_story": false
            },
            {
                "id": "5bd81c2bb6452f000efe6f18",
                "name": "Company Set",
                "in_target_story": true,
                "exit_story": false
            }
        ],
        "edges": [
            {
                "to_id": "5b07d3f5b7671500d2a47378",
                "to_name": "Data Bricolage",
                "dilution": 0,
                "hits": 0,
                "type": "LeafStepEdge",
                "details": [],
                "to_type": "step"
            },
            {
                "to_id": "5b07d417b7671500cf92491f",
                "to_name": "La Barbe",
                "dilution": 0,
                "hits": 0,
                "type": "LeafStepEdge",
                "details": [],
                "to_type": "step"
            },
            {
                "to_id": "5bd81c2bb6452f000efe6f18",
                "to_name": "Company Set",
                "dilution": 100,
                "hits": 3,
                "type": "LeafStepEdge",
                "details": [
                    {
                        "link_type": "links_to_link",
                        "hits": 3,
                        "hits_percent": 100
                    }
                ],
                "to_type": "step"
            }
        ],
        "summary": {
            "in_story_count": 3,
            "out_story_count": 0,
            "exit_story_count": 0,
            "total_count": 3
        }
    }
}
Suggest Edits

Conversation History

Set of endpoints to manipulate Conversation History

 

The Conversation History services allow you to retrieve and manipulate conversations interlocutors have had with the bot.

Suggest Edits

Conversations

Get conversations from a given bot

 
gethttps://api.clustaar.io/bots/bot_id/conversations

Path Params

bot_id
string
required

A bot ID

Query Params

page
int32

Page of elements

limit
int32

Number of returns elements

extract_limit
int32

Number of user interactions to get as extact of its conversation, on each conversation item

only_text
boolean

If true, retrive only text user interaction in the extract, not the button_action

start_timestamp
float

Timestamp to filter the conversations where the last message was made after this time

 

List all conversations ( a conversation is unique for one interlocutor ) made with the bot

Private API key needed

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

Response

Returns a list of Conversation Element.

Attribute
Type
Description

data[].interlocutor

Interlocutor

An Interlocutor object

data[].extract[]

A list of the last 'extract_limit' Conversation Element of the conversation

data[].count

Integer

Number of Conversation Element made by this interlocutor

data[].userRequestsTodoCount

Integer

Number of userRequest open by this interlocutor still in TODO state

{
    "data": [
          {
              "interlocutor": {
                "type": "interlocutor",
               ...
                "lastReplyAt": "2019-03-11T17:02:41+0000"
            },
            "extract": [
                {
                    "interlocutor_id": "5c58414ffd43ca0010fa1ae1",
                    "timestamp": 1557157686,
                    "bot_id": "5bfe9b243422d7000e046da8",
                    "input_source": {
                        "type": "interlocutor",
                        "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
                    },
                    "output_source": {
                        "type": "bot",
                        "bot_id": "5bfe9b243422d7000e046da8"
                    },
                    "input_action": {
                        "source": {
                            "type": "interlocutor",
                            "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
                        },
                        "action": {
                            "type": "text",
                            "message": "hello robot"
                        }
                    },
                    "output_actions": [
                        {
                            "source": {
                                "type": "actions_block",
                                "actions_block_id": "5bfe9b25e6b7bb0009914338"
                            },
                            "actions": [
                                {
                                    "action": {
                                        "type": "wait_action",
                                        "duration": 2
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "send_text_action",
                                        "alternatives": [
                                            "Hello you.\n"
                                        ],
                                        "text": "Hello you.\n"
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "wait_action",
                                        "duration": 2
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "send_text_action",
                                        "alternatives": [
                                            "How do you do ?"
                                        ],
                                        "text": "How do you do ?"
                                    },
                                    "parent_actions": []
                                }
                            ]
                        }
                    ]
                },
              	...
            ],
            "count": 24,
            "userRequestsTodoCount": 0
        }
    ],
    "pagination": {
        "page": 1,
        "objectsCount": 10,
        "pagesCount": 1,
        "limit": 1
    }
}
Suggest Edits

Conversation

Get conversation from a user

 
gethttps://api.clustaar.io/bots/bot_id/conversations/interlocutor_id

Path Params

bot_id
string
required

A bot ID

interlocutor_id
string
required

An interlocutor ID

Query Params

extract_limit
int32

Number of user interactions to get as extact of this conversation

only_text
boolean

If true, etrive only text user interaction in the extract, not the button_action

 

Get one conversation with an interlocutor

Private API key needed

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

Response

Attribute
Type
Description

data.interlocutor

Interlocutor

An Interlocutor object

data.extract[]

A list of the last 'extract_limit' Conversation Element of the conversation

data.count

Integer

Number of Conversation Element made by this interlocutor

data.userRequestsTodoCount

Integer

Number of UserRequest open by this interlocutor still in TODO state

{
    "data": {
              "interlocutor": {
                "type": "interlocutor",
               ...
                "lastReplyAt": "2019-03-11T17:02:41+0000"
            },
            "extract": [
                {
                    "interlocutor_id": "5c58414ffd43ca0010fa1ae1",
                    "timestamp": 1557157686,
                    "bot_id": "5bfe9b243422d7000e046da8",
                    "input_source": {
                        "type": "interlocutor",
                        "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
                    },
                    "output_source": {
                        "type": "bot",
                        "bot_id": "5bfe9b243422d7000e046da8"
                    },
                    "input_action": {
                        "source": {
                            "type": "interlocutor",
                            "interlocutor_id": "5c58414ffd43ca0010fa1ae1"
                        },
                        "action": {
                            "type": "text",
                            "message": "hello robot"
                        }
                    },
                    "output_actions": [
                        {
                            "source": {
                                "type": "actions_block",
                                "actions_block_id": "5bfe9b25e6b7bb0009914338"
                            },
                            "actions": [
                                {
                                    "action": {
                                        "type": "wait_action",
                                        "duration": 2
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "send_text_action",
                                        "alternatives": [
                                            "Hello you.\n"
                                        ],
                                        "text": "Hello you.\n"
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "wait_action",
                                        "duration": 2
                                    },
                                    "parent_actions": []
                                },
                                {
                                    "action": {
                                        "type": "send_text_action",
                                        "alternatives": [
                                            "How do you do ?"
                                        ],
                                        "text": "How do you do ?"
                                    },
                                    "parent_actions": []
                                }
                            ]
                        }
                    ]
                },
              	...
            ],
            "count": 24,
            "userRequestsTodoCount": 0
        }
}
Suggest Edits

Conversation Details

Get conversation details for a given user

 
gethttps://api.clustaar.io/bots/bot_id/conversations/interlocutor_id/conversation_elements

Path Params

bot_id
string
required

a bot ID

interlocutor_id
string
required

an interlocutor ID

Query Params

limit
int32

Number of conversation_element to retrieve

boundary
string

Enum : (from_start, from_time, around_time, to_time, to_end)

timestamp
int64

Second from epoch. used with the boundary values from_time, around_time, to_time. timestamp from which get the elements

include
boolean

For ‘from_time’ and ‘to_time’ if true, returns the element whose timestamp equals the timestamp param

 

Get all the Conversation Element constituting the whole conversation between an interlocutor and the bot (or support agent)
The endpoint is paginated as explained next.

Private API key needed

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

The Conversation Element are always chronologically sorted.
The endpoint allows you to scroll the conversation from the start (first message between interlocutor and the bot), or from the end (last message between interlocutor and the bot), or from any point in time, and then carry on scrolling up (older) or down (newer).

Example

to scroll from the end :
first call api with params : boundary=to_end
then call api with params boundary=to_time&timestamp=t&include=false where t is the timestamp of the first element of the previous results

to scroll from a given element : take the timestamp of the element :
first call api with params : boundary=around_time&timestamp=t (will return array of element where the one with timestamp=t is in the middle)

to scroll up :
call api with params : boundary=to_time&timestamp=t2&include=false where t2 is the timestamp of the first element of the previous results (or the older element you have)

to scroll down :
call api with params : boundary=from_time&timestamp=t2&include=false where t2 is the timestamp of the last element of the previous results (or the newer element you have)

returns a list of 'conversation_element'

Attribute
Type
Description

data[]

A list of the Conversation Element of the conversation

Suggest Edits

Search in all Conversations

Full-text search through your Bot Conversations

 
gethttps://api.clustaar.io/bots/bot_id/conversation_elements

Path Params

bot_id
string
required

A bot ID

Query Params

limit
int32

Number of returns elements

page
int32

Page of elements

query
string
required

Text to search in the interlocutors queries

start_timestamp
int64

Format epoch UTC . filter results after this timestamp

end_timestamp
int64

Format epoch UTC . filter results before this timestamp

levels
string

Array of ‘interlocutor’/‘bot’/‘other’. define in which kind of texts the query is searched. interlocutor: in interlocutor messages, bot in bot answser, other: all other silent actions

 

Search in the text of conversations

Response

Returns a list of search results as Conversation Element.
An element is returned only of some part of the query was matched through the conversation.

Attribute
Type
Description

data[]

A list of the Conversation Element of the conversation

pagination.page

Integer

The asked page

pagination.objectsCount

Integer

The number of element

pagination.pagesCount

Integer

The number of page to get all elements

pagination.limit

Integer

Tha asked limit

Suggest Edits

Initialize the Clustaar Webchat

 

This configuration allows you to initialize the Clustaar webchat.
If you want to configure your webchat in a logged environnement (i.e: with a defined user id as an email address), it's necessary to use an userToken parameter to identify the user.

The first time you push a userId, this token will be saved on Clustaar side, and used to identify further swaps for this userId.

We advise you to use a private key on your side to encrypt userId, and use this hash as token.

window.clustaarSettings = {
  bot_id: 'BOT_ID',
  bot_token: 'BOT_TOKEN',
  userID: '[email protected]', //Optional
  user_token: 'USER_SECRET_TOKEN'  //Optional
};
Suggest Edits

Events from the bot

Send Events from your bot

 

Listen to events from your Bot; this is useful to make your website react to the ongoing conversation on the webchat.

Built-in Events

There are Built-In events you can use to customize the behaviour of your application.
Here is a comprehensive list of the predefined events on the platform:

Event
Description
Payload

CLSTR_WEBCHAT_INITIALIZED

Webchat initialized and interlocutor created.

null

CLSTR_USER_OPENED_CHAT

The webchat window has been opened by the user.

null

CLSTR_USER_CLOSED_CHAT

The webchat window has been closed by the user.

null

CLSTR_USER_REPLIED

The user sent a reply to the bot in the webchat.

Last reply send by user, as a string.

CLSTR_BOT_SWAPPED

The bot was successfully swapped.

Bot id of the new bot, as a string.

CLSTR_USER_SWAPPED

The user was successfully swapped.

User Id of the new user, as a string.

Custom Events

Use the Send Event action to send a custom event from one of the steps of your stories.

When listening to the event, take care of using the exact same syntax as the one configured on the Send Event action of your bot.

Suggest Edits

Listen to an Event

Listen to events from the bot, and use them on your website.

 

Listener Function

You will have to update the bot script in order to define the function which will be called when receiving events.

Add an eventListener parameter in the clustaarSettings.

window.clustaarSettings = {
            bot_id: YOUR_BOT_ID,
            bot_token: YOUR_BOT_TOKEN,
            eventListener: clustaarEventsListener
};

Then, define the clustaarEventsListener function on your website so it can react to the events you are interested in.

function clustaarEventsListener(eventName) {
  switch(eventName) {
    case "MY_EVENT_NAME": {
      window.location.href = "https://clustaar.com/";
      break;
    }
    case "REDIRECT_TO_GOOGLE": {
      window.location.href = "https://google.com/";
      break;
    }
  }
}

If you want to use an event with a payload, as the CLSTR_USER_REPLIED event, you must provide the optional payload argument.

function clustaarEventsListener(eventName, payload) {
  switch(eventName) {
    case "CLSTR_USER_REPLIED": {
      alert("User said: " + payload);
      break;
    }
  }
}
Suggest Edits

Events from the website

Send Events from your website to the bot.

 

Make your bot react from Events sent by the website, to start specific stories.

URL Events

You can use the URL where the webchat is loaded as an event, to trigger a specific story.

Custom Events

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 to the Bot 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 to the Bot via the 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();
Suggest Edits

Set Debug mode for Replies

 

Enable / Disable the debug (verbose) mode for user replies

window.ClustaarWebchat.setDebug(debug: boolean);
Suggest Edits

User Attributes

Push user attributes from your website

 

User Attributes

You can push user attributes from your Website.
Attributes will have first to be whitelisted in your API settings.

Suggest Edits

Push a user attribute

 

Push a User Attribute via the webchat SDK.
In order to push an attribute, its name must have been declared in the whitelist configured in the API settings of your bot.

You can push an attribute and ignore request result.

window.ClustaarWebchat.pushAttribute('city', 'Paris');

Or you can push an attribute with a promise, in order to know if the call was successful.
The returned attribute is a boolean.

window.ClustaarWebchat.pushAttribute('city', 'Paris').then(function(ok){
  // "ok" is a boolean: true if the attribute is whitelisted and has been set successfully
  console.log(ok);
});

Important

If you want this piece of code to run in IE11 (which does not support much of ES6 at all), then you need to get a 3rd party promise library :
<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=es6"></script>

Suggest Edits

Check if user attribute is set

 

Check if a User Attribute already exists via the webchat SDK.
A user exists if it has been whitelisted, and has been set at least one time.

Call will return a promise:

window.ClustaarWebchat.isSet('city').then(function(exists){
  // "exists" is a boolean: true if the attribute is whitelisted, and has been set
  console.log(exists)
});
Suggest Edits

Send Reply

Act as a user, and send a reply to the bot.

 

This method allows you to send a message to the bot as if you were the current user.
The behaviour will be exactly the same : the reply will appear on the webchat conversation, and the bot will answer to it as a a normal one.

// display (boolean) : Optional value to display or not the replied message in the conversation. Default value is true. 
window.ClustaarWebchat.sendReply("your message", display = true);
Suggest Edits

Send Bot Reply

Act as a bot, and send a reply to the user.

 

This method allows you to send a message to the user as if you were the bot.
The behaviour will be exactly the same : the reply will appear on the webchat conversation, and the user will receive it as a a normal one.

window.ClustaarWebchat.sendBotReply("your message");
Suggest Edits

Swap bot

Allows to swap bot on the webchat

 

This method allows you to swap the bot used by the webchat.

var newSettings = {
	bot_id: 'YOUR_BOT_ID',
	bot_token: 'YOUR_BOT_TOKEN',
	disableWelcomeStory: true, // default false
  userID: 'YOUR_USER_ID', // optional user ID
  user_token: 'YOUR_USER_TOKEN' // optional user token
};
window.ClustaarWebchat.swapBot(newSettings);
Suggest Edits

Swap user

Allows to swap user on the webchat.

 

This method allows you to swap the user identified in the webchat.
It will soon need an obligatory userToken parameter to identify the user.

The first time you push a userId, this token will be saved on Clustaar side, and used to identify further swaps for this userId.

We advise you to use a private key on your side to encrypt userId, and use this hash as token.

// with User Token parameter
window.ClustaarWebchat.swapUser('USER_ID', 'USER_TOKEN');
Suggest Edits

Integrated webchat

Allows to use integrated webchat on your website

 

You will have to update the bot script in order to define the element id which will be use to integrate the webchat on your page.

Add an integrate parameter in the clustaarSettings.

window.clustaarSettings = {
            bot_id: YOUR_BOT_ID,
            bot_token: YOUR_BOT_TOKEN,
            integrate: "MY_CONTAINER_ID"
};
Suggest Edits

Get interlocutor ID

 

This method allows you to get the interlocutor id

window.ClustaarWebchat.getInterlocutorID();
Suggest Edits

Conversation

Allows the webchat to be loaded with another user.

 

You can use JavaScript to get information about current conversation, such as converstion url, or history.

Suggest Edits

Get conversation url

 

This method allows you to get the conversation url

window.ClustaarWebchat.getConversationURL();
Suggest Edits

Get conversation history

 

This method allows you to get the conversation history

// count (number) : Optional value to get the last x element of the conversation history.
Default value is 0 to get all the history. 
// from (string) : Optional value ('user','bot','both') to filter the conversation history. Default value is 'both'. 
window.ClustaarWebchat.getConversationHistory(count=0,from='both');
Suggest Edits

Synchronize user history

 

If you want to synchronize your user history with our database you have to add the attribute synchronizeUserConversation in your clustaar settings. userID and userToken are mandatory to use this feature

window.clustaarSettings = {
                bot_id: 'MY_BOT_ID',
                bot_token: 'MY_BOT_TOKEN',
                userID: 'MY_USERID',
                user_token: `MY_USER_TOKEN`,
                synchronizeUserConversation: true,
                eventListener: handleEvents
            };
Suggest Edits

Force display header

 

If you want to force the display of the header in case you want to use the webchat in different way on your website

window.clustaarSettings = {
                bot_id: 'MY_BOT_ID',
                bot_token: 'MY_BOT_TOKEN',
                displayHeader: false', // force to hide the header, even if you activated it on the platform
            };
Suggest Edits

Force welcome message

 

If you want to force the welcome message in case you want to use the webchat in different way on your website

window.clustaarSettings = {
                bot_id: 'MY_BOT_ID',
                bot_token: 'MY_BOT_TOKEN',
                welcomeMessage: 'Welcome this is a different welcome message', // force the welcome message, even if you configured it on the platform
            };