BotDistrikt
API docs by Redocly

BotDistrikt Platform (27 May 2023)

BotDistrikt is an end-to-end chatbot technology platform to build fantastic conversational experiences with no coding required

API Reference

The BotDistrikt API is organized around JSONAPI. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

Authentication

BotDistrikt offers two forms of authentication:

Name Request
Authorization Header
access_token Query Param

Please see https://loopback.io/doc/en/lb3/Making-authenticated-requests.html#making-authenticated-requests-with-access-tokens for more information on how to use them

bot

A bot account. When you create a new bot on BotDistrikt, a new bot account will be created which will be the base of all your other design, development, launch, and optimization work. The most important field to remember from your bot is the Bot ID. This ID is mandatory to use all other API endpoints in the platform. A bot and an account are synonymous. One account cannot have multiple bots. However, one acccount can have multiple integrations with multiple messaging channels and website chat placements. Furthermore, by using rules and stories, you can even "split" one bot into multiple bots with different memory or attribute checks. You can read more about this in the general documentation.

Get bot by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
about
string

An "About Me" description of your chatbot, used in Get Started screens of Messaging Apps

name
string

Your bot's name

profile_pic
string

URL of the bot profile picture

session_ttl
number <double>
Default: 10

The maximum number of minutes a bot_user chat session can be inactive before it expires. Used to calculate the length and frequency of chat sessions with bot_users

global_defaults
object

An object of key value pairs where keys are shortcuts and values and longer lengths of text. For example, if a key-value pair of { "office_address": "15 Yemen Road, Road" } exists here, a response text can be "Our office is located at {{bot.office_address}}" and the actual address will be shown to the bot_user.

status
string
Default: "active"
Enum: "active" "staging" "archived" "template"

Status of the bot. staging is for staging bots only, and template is templates only

template_name
string

Required if the bot is a template

from_template
string

(GENERATED) the name of the template that the bot was generated from

is_public
boolean
Default: false

Describes whether bot shows up in Public Profile

developer_email
string

Contact email of bot developer for Public Profile

account_name
string

Name of the account owning the bot

id
number <double>

Response samples

Content type
{
  • "about": "You can ask me about bus timings",
  • "name": "Bus Uncle",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "session_ttl": 10,
  • "global_defaults": {
    },
  • "status": "active",
  • "template_name": "string",
  • "from_template": "string",
  • "is_public": false,
  • "developer_email": "ah@busuncle.sg",
  • "account_name": "Bus Uncle Company (Pte. Ltd.)",
  • "id": 0
}

Update a bot

path Parameters
id
required
string <JSON>

bot id

Request Body schema:

An object of model property name/value pairs

about
string

An "About Me" description of your chatbot, used in Get Started screens of Messaging Apps

name
string

Your bot's name

profile_pic
string

URL of the bot profile picture

session_ttl
number <double>
Default: 10

The maximum number of minutes a bot_user chat session can be inactive before it expires. Used to calculate the length and frequency of chat sessions with bot_users

global_defaults
object

An object of key value pairs where keys are shortcuts and values and longer lengths of text. For example, if a key-value pair of { "office_address": "15 Yemen Road, Road" } exists here, a response text can be "Our office is located at {{bot.office_address}}" and the actual address will be shown to the bot_user.

status
string
Default: "active"
Enum: "active" "staging" "archived" "template"

Status of the bot. staging is for staging bots only, and template is templates only

template_name
string

Required if the bot is a template

from_template
string

(GENERATED) the name of the template that the bot was generated from

is_public
boolean
Default: false

Describes whether bot shows up in Public Profile

developer_email
string

Contact email of bot developer for Public Profile

account_name
string

Name of the account owning the bot

id
number <double>

Responses

Response Schema:
about
string

An "About Me" description of your chatbot, used in Get Started screens of Messaging Apps

name
string

Your bot's name

profile_pic
string

URL of the bot profile picture

session_ttl
number <double>
Default: 10

The maximum number of minutes a bot_user chat session can be inactive before it expires. Used to calculate the length and frequency of chat sessions with bot_users

global_defaults
object

An object of key value pairs where keys are shortcuts and values and longer lengths of text. For example, if a key-value pair of { "office_address": "15 Yemen Road, Road" } exists here, a response text can be "Our office is located at {{bot.office_address}}" and the actual address will be shown to the bot_user.

status
string
Default: "active"
Enum: "active" "staging" "archived" "template"

Status of the bot. staging is for staging bots only, and template is templates only

template_name
string

Required if the bot is a template

from_template
string

(GENERATED) the name of the template that the bot was generated from

is_public
boolean
Default: false

Describes whether bot shows up in Public Profile

developer_email
string

Contact email of bot developer for Public Profile

account_name
string

Name of the account owning the bot

id
number <double>

Request samples

Content type
{
  • "about": "You can ask me about bus timings",
  • "name": "Bus Uncle",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "session_ttl": 10,
  • "global_defaults": {
    },
  • "status": "active",
  • "template_name": "string",
  • "from_template": "string",
  • "is_public": false,
  • "developer_email": "ah@busuncle.sg",
  • "account_name": "Bus Uncle Company (Pte. Ltd.)",
  • "id": 0
}

Response samples

Content type
{
  • "about": "You can ask me about bus timings",
  • "name": "Bus Uncle",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "session_ttl": 10,
  • "global_defaults": {
    },
  • "status": "active",
  • "template_name": "string",
  • "from_template": "string",
  • "is_public": false,
  • "developer_email": "ah@busuncle.sg",
  • "account_name": "Bus Uncle Company (Pte. Ltd.)",
  • "id": 0
}

Export data to a CSV

Export different bot configurations and user-generated data to CSVs

path Parameters
id
required
string <JSON>

bot id

Request Body schema:
type
string
Enum: "generic" "messages" "users" "broadcasts" "clicks" "fb_bot_users" "cards" "stories" "rules" "responses" "broadcast_records" "compare"

The type of data to export

where
object

A Loopback Filter object

mode
string
Enum: null "uat"

The mode of export. Only useful if you want to export a UAT sheet for messages

Responses

Response Schema:
url
string

The URL of the exported CSV

Request samples

Content type
{
  • "type": "messages",
  • "where": {
    },
  • "mode": "uat"
}

Response samples

Content type
{}

Export the bot to a JSON

path Parameters
id
required
string <JSON>

bot id

Responses

Response Schema: application/force-download
string <binary>

The exported JSON file

Replay a message

Replays a message to check its response. Use this to test bot_user messages to your bot without saving them to your Inbox Note: Changes to memory or user attributes from actions or webhooks will NOT be applied

path Parameters
id
required
string <JSON>

bot id

Request Body schema:
required
object

The message to replay

required
object

The user to replay this message from

memory
object

An object of key-value pairs of memory keys

nlp
object

An object of key-value pairs of NLP keys

from_story_id
number

The ID of a story to replay the message from

Responses

Response Schema:
Array of objects (bot_message)

An array of responses sent to the user

Array of objects (quick_reply)

An array of quick replies sent to the user

object

The user that this message was replayed with

object

The group that was evaluated for this message

object

The rule that was evaluated for this message

object

The story that was evaluated for this message

story_context_diffs
object

An object of differences in context of memory and user attributes if from_story_id was used in the request

Request samples

Content type
{
  • "message": {
    },
  • "memory": {
    },
  • "user": {
    }
}

Response samples

Content type
{
  • "webchat_responses": [
    ],
  • "webchat_quickreplies": [
    ],
  • "user": {
    },
  • "rule": {
    },
  • "group": {
    },
  • "story": {
    },
  • "story_context_diffs": {
    }
}

List all properties

Lists all memory, user, and NLP properties used by the bot from rules, stories, and bot_users. This also shows the values of these properties for autocompletion in conditions and actions

path Parameters
id
required
string <JSON>

bot id

Responses

Response Schema:
bot
Array of strings[ items ]

List of bot shortcuts and their suggested values generated by existing conditions and actions

memory
Array of strings[ items ]

List of memory properties and their suggested values generated by existing conditions and actions

user
Array of strings[ items ]

List of user attributes and their suggested values generated by existing conditions and actions

nlp
Array of strings[ items ]

List of NLP attributes and their suggested values generated by existing conditions and actions

Response samples

Content type
{
  • "bot": [
    ],
  • "memory": [
    ],
  • "user": [
    ],
  • "nlp": [
    ]
}

audit_log

The audit log keeps track of the changes made by users to the bots.

Search audit logs

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this action belongs to

user_id
required
number <double>

The ID of the user who performed the action

action
required
string
Enum: "CREATED" "UPDATED" "DELETED"

The type of the action performed

entity_name
required
string
Enum: "action" "assistant_app" "audio" "bot" "bot_user" "broadcast" "button" "card" "chatbase_app" "condition" "dialogflow_app" "document" "facebook_app" "facebook_page" "form" "form_question" "function" "group" "image" "instagram_page" "openai_app" "persisted_menu" "quick_reply" "response" "response_group" "rule" "salesforce_app" "sheets_app" "skype_app" "sms_app" "step" "sticker" "story" "tag" "telegram_app" "template" "twitter_app" "video" "webchat_app" "webhook" "webhook_app" "wechat_app" "whatsapp_app" "wit_app" "zendesk_app"

The name of the model that was acted upon

entity_id
required
number <double>

The ID of the model that was acted upon

original_object
object

The original object before the action was performed

updated_object
object

The updated object after the action was performed

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audit_log was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audit_log was last updated.

Response samples

Content type
[
  • {
    }
]

Get audit log by ID

path Parameters
id
required
string <JSON>

Model id

query Parameters
filter
string <JSON>

Filter defining fields and include - must be a JSON-encoded string ({"something":"value"})

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this action belongs to

user_id
required
number <double>

The ID of the user who performed the action

action
required
string
Enum: "CREATED" "UPDATED" "DELETED"

The type of the action performed

entity_name
required
string
Enum: "action" "assistant_app" "audio" "bot" "bot_user" "broadcast" "button" "card" "chatbase_app" "condition" "dialogflow_app" "document" "facebook_app" "facebook_page" "form" "form_question" "function" "group" "image" "instagram_page" "openai_app" "persisted_menu" "quick_reply" "response" "response_group" "rule" "salesforce_app" "sheets_app" "skype_app" "sms_app" "step" "sticker" "story" "tag" "telegram_app" "template" "twitter_app" "video" "webchat_app" "webhook" "webhook_app" "wechat_app" "whatsapp_app" "wit_app" "zendesk_app"

The name of the model that was acted upon

entity_id
required
number <double>

The ID of the model that was acted upon

original_object
object

The original object before the action was performed

updated_object
object

The updated object after the action was performed

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audit_log was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audit_log was last updated.

Response samples

Content type
{
  • "bot_id": 3,
  • "user_id": 5,
  • "action": "CREATED",
  • "entity_name": "action",
  • "entity_id": 5,
  • "original_object": { },
  • "updated_object": { },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

group

A set of rules. Groups are tested in ascending order of their position in the bot. Groups can be treated as "Folders" to organize your rules around certain topics and functionalities in your bot. It is important to remember that the order of groups matter. As soon as a rule near the top is evaluated to be the Passing Rule, the rules below are ignored. If none of the rules are evaluated to be the Passing Rule, the fallback rule is selected, and your bot will reply with the fallback story. When a user sends your bot a message (incoming message), your bot looks at all of its rules to identify which rule satisfies all conditions of the incoming message, as well as the existing memory context, user context, and derived NLP context. When a rule is evaluated to have satisfied all the conditions for an incoming, it is selected as the Passing Rule. The story of the passing rule then determines the bot's response (outgoing response) back to the user.

Create a new group

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Request samples

Content type
{
  • "bot_id": 12,
  • "form_id": 14,
  • "name": "FAQ",
  • "description": "Auto-generated from creating a new bot",
  • "is_active": true,
  • "linear_rules_count": 12,
  • "nonlinear_rules_count": 3,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 14,
  • "name": "FAQ",
  • "description": "Auto-generated from creating a new bot",
  • "is_active": true,
  • "linear_rules_count": 12,
  • "nonlinear_rules_count": 3,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Get group by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 14,
  • "name": "FAQ",
  • "description": "Auto-generated from creating a new bot",
  • "is_active": true,
  • "linear_rules_count": 12,
  • "nonlinear_rules_count": 3,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Delete a group

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a group

path Parameters
id
required
string <JSON>

group id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Request samples

Content type
{
  • "bot_id": 12,
  • "form_id": 14,
  • "name": "FAQ",
  • "description": "Auto-generated from creating a new bot",
  • "is_active": true,
  • "linear_rules_count": 12,
  • "nonlinear_rules_count": 3,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 14,
  • "name": "FAQ",
  • "description": "Auto-generated from creating a new bot",
  • "is_active": true,
  • "linear_rules_count": 12,
  • "nonlinear_rules_count": 3,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

List bot groups

Lists all groups of a bot

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this group belongs to

name
required
string

The name of the group

position
required
number <double>
Default: 0

Position of the group relative to its siblings of the parent bot

form_id
number <double>

If this group was generated by a form, the ID of the form this group belongs to

description
string

(GENERATED) The description of the group if it a system-generated group

is_active
boolean
Default: true

Whether or not the group is active in the bot

linear_rules_count
number <double>

(GENERATED) Number of "LINEAR" rules in this group

nonlinear_rules_count
number <double>

(GENERATED) Number of "NONLINEAR" rules in this group

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the group was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Response samples

Content type
[
  • {
    }
]

rule

A set of conditions to evaluate an incoming message and to select a story to respond with. Rules are tested in ascending order of their position in a group. It is important to remember that the order of rules matter. As soon as a rule near the top is evaluated to be the Passing Rule, the rules below are ignored. If none of the rules are evaluated to be the Passing Rule, the fallback rule is selected, and your bot will reply with the fallback story. When a user sends your bot a message (incoming message), your bot looks at all of its rules to identify which rule satisfies all conditions of the incoming message, as well as the existing memory context, user context, and derived NLP context. When a rule is evaluated to have satisfied all the conditions for an incoming, it is selected as the Passing Rule. The story of the passing rule then determines the bot's response (outgoing response) back to the user.

Create a new rule

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "group_id": 16,
  • "form_id": 18,
  • "is_active": true,
  • "is_fallback": false,
  • "description": "User said hello",
  • "linearity": "LINEAR",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "group_id": 16,
  • "form_id": 18,
  • "is_active": true,
  • "is_fallback": false,
  • "description": "User said hello",
  • "linearity": "LINEAR",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Get rule by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "group_id": 16,
  • "form_id": 18,
  • "is_active": true,
  • "is_fallback": false,
  • "description": "User said hello",
  • "linearity": "LINEAR",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Delete a rule

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a rule

path Parameters
id
required
string <JSON>

rule id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "group_id": 16,
  • "form_id": 18,
  • "is_active": true,
  • "is_fallback": false,
  • "description": "User said hello",
  • "linearity": "LINEAR",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "group_id": 16,
  • "form_id": 18,
  • "is_active": true,
  • "is_fallback": false,
  • "description": "User said hello",
  • "linearity": "LINEAR",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "is_system": false,
  • "position": 3
}

List group rules

List all rules of a group

path Parameters
id
required
string <JSON>

group id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this rule belongs to

group_id
required
number <double>

The ID of the group this rule belongs to

story_id
required
number <double>

The ID of the story this rule will trigger

description
required
string

The name of the rule

position
required
number <double>
Default: 0

Position of the rule relative to its siblings of the parent group

form_id
number <double>

If this rule was generated by a form, the ID of the form this rule belongs to

is_active
boolean
Default: true

Whether or not the rule is active in the bot

is_fallback
boolean
Default: false

(GENERATED) If true, the rule will be not be tested in ascending order of its position. Rather, this rule story will be selected only when no other rules pass

linearity
string
Enum: "LINEAR" "NONLINEAR"

(GENERATED) One of "LINEAR", or "NONLINEAR"

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the rule was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the rule was last updated.

is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

Response samples

Content type
[
  • {
    }
]

condition

A condition to evaluate an incoming message against a context property and a value Conditions can check properties of the incoming message if they are of type message, or can check properties of the current memory, user attribute, or nlp context It is important to note that ALL conditions in a rule must pass before the rule can be evaluated to be the Passing Rule. If you would like to create a rule where ANY of the conditions match, rather than ALL, you may just create a different rule below, as only one rule can be selected as the Passing Rule.

Create a new condition

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "rule_id": 14,
  • "function_id": 16,
  • "context_property": "text",
  • "type": "message",
  • "value": "hi",
  • "name": "text $equals hi",
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "rule_id": 14,
  • "function_id": 16,
  • "context_property": "text",
  • "type": "message",
  • "value": "hi",
  • "name": "text $equals hi",
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get condition by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "rule_id": 14,
  • "function_id": 16,
  • "context_property": "text",
  • "type": "message",
  • "value": "hi",
  • "name": "text $equals hi",
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a condition

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a condition

path Parameters
id
required
string <JSON>

condition id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "rule_id": 14,
  • "function_id": 16,
  • "context_property": "text",
  • "type": "message",
  • "value": "hi",
  • "name": "text $equals hi",
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "rule_id": 14,
  • "function_id": 16,
  • "context_property": "text",
  • "type": "message",
  • "value": "hi",
  • "name": "text $equals hi",
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List rule conditions

List all conditions of a rule

path Parameters
id
required
string <JSON>

rule id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this condition belongs to

rule_id
required
number <double>

The ID of the rule this condition belongs to

type
required
string
Default: "message"
Enum: "message" "memory" "attribute" "nlp"

This context this condition will check

context_property
required
string

The property of the context this condition will test

function_id
required
number <double>

The ID of the function this condition is tested with

value
string

The value to test the context property against. Can be blank.

name
string

(GENERATED) The name of the condition generated by its context property, function name, and value

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the condition was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the condition was last updated.

Response samples

Content type
[
  • {
    }
]

function

A JavaScript (JS) function to modify or evaluate the context of an incoming message Your bot will already have several system functions built-in. These functions are standard condition checks and action executions to modify context properties. If you would like to write your own JavaScript functions, you may do so in the Responses > Functions page. It is not possible to create JS functions with an API call. You can read more about this in the general documentation.

List bot functions

Lists all functions of a bot

path Parameters
id
required
string <JSON>

bot id

Responses

Response Schema:
Array
name
required
string

The name of this JS function

string
required
string

The JS code of this function

bot_id
number <double>

The ID of the bot this function belongs to

is_action
boolean
Default: false

If true, this is a condition function. If false, this is an action function.

is_tag
boolean
Default: false

For actions functions only. If true, this function is only displayed for a tag type action

is_multi
boolean
Default: false

For condition functions only. If true, this will allow multiple comma-separated values to be entered into a condition

id
number <double>
is_system
boolean
Default: true

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the function was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the function was last updated.

Response samples

Content type
[
  • {
    }
]

story

A response from the bot. When an incoming message passes the tests of all conditions in a rule, the story of the rule is selected as the bot's outgoing response. A story can consists of multiple response types likes text, images, cards, and combinations of these. These responses are packaged in records called steps. A story also consists of quick replies that a user may click on to quickly interact with. A story can also be published with a broadcast or pushed as a live agent reply.

Create a new story

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "form_id": 18,
  • "name": "Our products",
  • "description": "Displayed a list of our products to the user",
  • "stats": {
    },
  • "users": 142,
  • "impressions": 2321,
  • "delay": 946,
  • "sentiment": 1,
  • "alert_emails": [
    ],
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 18,
  • "name": "Our products",
  • "description": "Displayed a list of our products to the user",
  • "stats": {
    },
  • "users": 142,
  • "impressions": 2321,
  • "delay": 946,
  • "sentiment": 1,
  • "alert_emails": [
    ],
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get story by ID

path Parameters
id
required
string <JSON>

story id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 18,
  • "name": "Our products",
  • "description": "Displayed a list of our products to the user",
  • "stats": {
    },
  • "users": 142,
  • "impressions": 2321,
  • "delay": 946,
  • "sentiment": 1,
  • "alert_emails": [
    ],
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a story

path Parameters
id
required
string <JSON>

story id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a story

path Parameters
id
required
string <JSON>

story id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "form_id": 18,
  • "name": "Our products",
  • "description": "Displayed a list of our products to the user",
  • "stats": {
    },
  • "users": 142,
  • "impressions": 2321,
  • "delay": 946,
  • "sentiment": 1,
  • "alert_emails": [
    ],
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "form_id": 18,
  • "name": "Our products",
  • "description": "Displayed a list of our products to the user",
  • "stats": {
    },
  • "users": 142,
  • "impressions": 2321,
  • "delay": 946,
  • "sentiment": 1,
  • "alert_emails": [
    ],
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List bot stories

Lists all stories of a bot

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this story belongs to

name
required
string

The name of the story

form_id
number <double>

If this story was generated by a form, the ID of the form this story belongs to

description
string

(GENERATED) The description of a system-generated story

stats
object

(GENERATED) An object of the stats of this story used for analytics purposes

users
number <double>
Default: 0

(GENERATED) The total reach of this story in terms of unique users

impressions
number <double>
Default: 0

(GENERATED) The total views of this story aggregated across all bot_users

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent viewing this story

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment of a message right after viewing this story

alert_emails
object
Default: []

A list of emails to alert when this story is triggered

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the story was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the story was last updated.

Response samples

Content type
[
  • {
    }
]

step

One response in a story. A story can have a combination of text responses, images, documents, as well as actions and webhooks. All steps are returned in order of their position. Context can be updated between steps. For example, you can create an action step with position 1 setting the user attribute first_name to {{message.text}}, and a text response step with position 2 with the name "Hi {{user.first_name}}, welcome to our store!"

Create a new step

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "form_id": 18,
  • "response_group_id": 20,
  • "image_id": 22,
  • "document_id": 24,
  • "action_id": 26,
  • "webhook_id": 28,
  • "audio_id": 30,
  • "video_id": 32,
  • "sticker_id": 34,
  • "name": "image: busuncle.png",
  • "type": "text",
  • "cards_type": "horizontal",
  • "cards_page_limit": 3,
  • "typing_length": 2,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "form_id": 18,
  • "response_group_id": 20,
  • "image_id": 22,
  • "document_id": 24,
  • "action_id": 26,
  • "webhook_id": 28,
  • "audio_id": 30,
  • "video_id": 32,
  • "sticker_id": 34,
  • "name": "image: busuncle.png",
  • "type": "text",
  • "cards_type": "horizontal",
  • "cards_page_limit": 3,
  • "typing_length": 2,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Get step by ID

path Parameters
id
required
string <JSON>

Model id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "form_id": 18,
  • "response_group_id": 20,
  • "image_id": 22,
  • "document_id": 24,
  • "action_id": 26,
  • "webhook_id": 28,
  • "audio_id": 30,
  • "video_id": 32,
  • "sticker_id": 34,
  • "name": "image: busuncle.png",
  • "type": "text",
  • "cards_type": "horizontal",
  • "cards_page_limit": 3,
  • "typing_length": 2,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Delete a step

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a step

path Parameters
id
required
string <JSON>

step id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "form_id": 18,
  • "response_group_id": 20,
  • "image_id": 22,
  • "document_id": 24,
  • "action_id": 26,
  • "webhook_id": 28,
  • "audio_id": 30,
  • "video_id": 32,
  • "sticker_id": 34,
  • "name": "image: busuncle.png",
  • "type": "text",
  • "cards_type": "horizontal",
  • "cards_page_limit": 3,
  • "typing_length": 2,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "form_id": 18,
  • "response_group_id": 20,
  • "image_id": 22,
  • "document_id": 24,
  • "action_id": 26,
  • "webhook_id": 28,
  • "audio_id": 30,
  • "video_id": 32,
  • "sticker_id": 34,
  • "name": "image: busuncle.png",
  • "type": "text",
  • "cards_type": "horizontal",
  • "cards_page_limit": 3,
  • "typing_length": 2,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

List story steps

path Parameters
id
required
string <JSON>

story id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this step belongs to

story_id
required
number <double>

The ID of the story this step belongs to

position
required
number <double>
Default: 0

Position of the step relative to its siblings of the parent story

type
required
string
Enum: "text" "image" "audio" "video" "document" "sticker" "cards" "action" "webhook" "typing"

The response type

form_id
number <double>

If this step was generated by a form, the ID of the form this step belongs to

response_group_id
number <double>

If this is a text step, the ID of the text response this step will return

image_id
number <double>

If this is an image step, the ID of the image response this step will return

document_id
number <double>

If this is a document step, the ID of the document response this step will return

action_id
number <double>

If this is an action step, the ID of the action response this step will return

webhook_id
number <double>

If this is an webhook step, the ID of the webhook response this step will return

audio_id
number <double>

If this is an audio step, the ID of the audio response this step will return

video_id
number <double>

If this is a video step, the ID of the video response this step will return

sticker_id
number <double>

If this is an sticker step, the ID of the sticker response this step will return

name
string

(DEPRECATED) The name of the step

cards_type
string
Default: "horizontal"
Enum: "horizontal" "square" "original"

For cards steps only. The image aspect ratio of cards in this step

cards_page_limit
number <double> [ 2 .. 8 ]
Default: 8

For cards steps only. The maximum number of cards to be shown per page in the step

typing_length
number <double> [ 1 .. 5 ]

For typing steps only. The number of seconds to show the typing indicator for.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the step was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the step was last updated.

Response samples

Content type
[
  • {
    }
]

quick_reply

A transient button that a user can click to respond to a story. A story can have multiple quick replies. Depending on the capabilities of a messaging app, some quick replies can be an instead way to send locations, emails, and phone numbers. For example, locations can be sent in a Telegram bot, and emails and phone numbers can be sent in a Facebook Messenger bot. Quick replies are displayed at the bottom of the chat screen from left-to-right in order of their position

Create a new quick reply

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "persisted_menu_id": 16,
  • "text": "My Orders",
  • "type": "text",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "persisted_menu_id": 16,
  • "text": "My Orders",
  • "type": "text",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Get quick reply by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "persisted_menu_id": 16,
  • "text": "My Orders",
  • "type": "text",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Delete a quick reply

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a quick reply

path Parameters
id
required
string <JSON>

quick_reply id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "persisted_menu_id": 16,
  • "text": "My Orders",
  • "type": "text",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

Response samples

Content type
{
  • "bot_id": 12,
  • "story_id": 14,
  • "persisted_menu_id": 16,
  • "text": "My Orders",
  • "type": "text",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "position": 3
}

List story quick replies

List all quick replies of a story

path Parameters
id
required
string <JSON>

story id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this quick reply belongs to

type
required
string
Enum: "text" "location" "user_email" "user_phone_number"

The type of the quick reply

text
required
string <= 20 characters

The name of the quick reply

position
required
number <double>
Default: 0

Position of the quick_reply relative to its siblings of the parent story

story_id
number <double>

The ID of the story this quick reply belongs to

persisted_menu_id
number <double>

If this is a bot profile default quick reply, the ID of the persisted menu this quick reply belongs to

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the quick_reply was last updated.

Response samples

Content type
[
  • {
    }
]

response_group

A text response from the chatbot. If this text response has variants exist, a random string from the (name of this text response + the texts of its variants) will be selected as the outgoing response

Create a new text response

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Get text response by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Delete a text response

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a text response

path Parameters
id
required
string <JSON>

response_group id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

List text response buttons

List all buttons of a text response

path Parameters
id
required
string <JSON>

response_group id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Response samples

Content type
[
  • {
    }
]

Filter text responses by tags

Internal webhook to filter text responses by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=orange,tshirt,OR(cotton,unisex)

A comma-separated list of keywords to filter text responses by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the text responses I was able to find!

A message to show before displaying the filtered text responses

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no text responses were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no text responses were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered text responses

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of text responses to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N text responses to display

Responses

Response Schema:
object

A list of filtered text responses in webhook response format

Response samples

Content type
{ }

Search text responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Response samples

Content type
[
  • {
    }
]

Get step text response

Get the text response of a step

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

name
required
string

The text of the response

last_click_at
string <date-time>

(GENERATED) If this response has URL buttons, the datetime at which the button was last clicked at by a bot_user

stats
object

An object of the stats of this text response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this text response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response_group was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response_group was last updated.

tags_string
string

A comma-separated list of tags for the response_group

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Hi there, how can I help?",
  • "last_click_at": "2023-01-07 20:55:31+08",
  • "stats": {
    },
  • "clicks": 23,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

response

A text response variant. A random string from the (name of a text response + the texts of its variants) will be selected as the outgoing response

Create a new text variant

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 14,
  • "text": "How are you today?",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 14,
  • "text": "How are you today?",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find text variant by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 14,
  • "text": "How are you today?",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a text variant

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a text variant

path Parameters
id
required
string <JSON>

response id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 14,
  • "text": "How are you today?",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 14,
  • "text": "How are you today?",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List text response variants

path Parameters
id
required
string <JSON>

response_group id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this text response belongs to

response_group_id
required
number <double>

The ID of the text response this variant belongs to

text
required
string

The text of the variant

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the response was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the response was last updated.

Response samples

Content type
[
  • {
    }
]

card

A rich element that contains an image, title, subtitle, and a set of buttons. Most messaging apps display these in a horizontal-scrolling carousel. If a messaging app does not support horizontal-scrolling carousels, cards will be shown in a vertical list of responses on the chat screen.

Create a new card

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Request samples

Content type
{}

Response samples

Content type
{}

Get card by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Response samples

Content type
{}

Delete a card

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a card

path Parameters
id
required
string <JSON>

card id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Request samples

Content type
{}

Response samples

Content type
{}

List card buttons

List all buttons of a card

path Parameters
id
required
string <JSON>

card id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Response samples

Content type
[
  • {
    }
]

Filter cards by tags

Internal webhook to filter cards by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=premium,OR(cityview,gardenview),suite

A comma-separated list of keywords to filter cards by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the cards I was able to find!

A message to show before displaying the filtered cards

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no cards were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no cards were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered cards

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of cards to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N cards to display

Responses

Response Schema:
object

A list of filtered cards in webhook response format

Response samples

Content type
{}

Search cards by text or location

Internal webhook to fuzzy search cards by text, or filter cards within a location radius

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

query
string
Example: query=stars

A text query to perform a fuzzy search of all cards with

lat_lng
string
Example: lat_lng=1.23928,103.9287373

A location query to perform a location-based search of all cards that have the "attributes.location" set

radius
string
Default: 1000
Example: radius=3000

For location queries only. The radius in metres to search cards around the provided "lat_lng"

skip
number <double>
Example: skip=8

For pagination in results. Skip N cards in results

limit
number <double>
Example: limit=8

For pagination in results. Limit to N cards in results

fallback_message
string
Default: "Sorry, I could not find anything about \"stars\""
Example: fallback_message=There were no stars available

A message to show if no cards were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no cards were found

confirmation_message
string
Example: confirmation_message=Here are the cards I was able to find!

A message to show before displaying the searched cards

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of cards to be display per page

image_aspect_ratio
string
Default: "square"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered cards

tags
string
Example: tags=premium,citiview

Tags to filter cards with before performing a fuzzy search or location search

Responses

Response Schema:
object

A list of filtered cards in webhook response format

Response samples

Content type
{}

Search card responses

List all cards of a bot

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this card belongs to

title
required
string <= 80 characters

The title of the card

image_url
required
string

URL of the card image

subtitle
string <= 80 characters

A short description of the card

last_click_at
string <date-time>

(GENERATED) If this card has URL buttons, the datetime at which the button was last clicked at by a bot_user

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

attributes
object

A JSON object of key-value pairs containing the card's attributes. Used in searching.

is_active
boolean
Default: true

Whether or not this card is active in the bot

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the card was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the card was last updated.

tags_string
string

A comma-separated list of tags for the card

position
number <double>
Default: 0

Position of the card relative to its siblings of the parent step

square_image_url
string

(GENERATED) URL of the card image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the card image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the card image resized to original aspect ratio

Response samples

Content type
[]

List step cards

List all cards of a step

path Parameters
id
required
number <double>

Responses

Response Schema:
object

Response samples

Content type
{ }

button

A button that a user can click. Unlike quick replies, buttons are attached to a text response, card, or other response types. Once they appear in a user's chat screen, they will permanently be visible and clickable in the user's chat history. Therefore, buttons should should only trigger nonlinear rules.

Create a new button

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 16,
  • "card_id": 18,
  • "audio_id": 20,
  • "video_id": 22,
  • "persisted_menu_id": 24,
  • "story_id": 26,
  • "title": "Our Website",
  • "type": "web_url",
  • "url": "https://mywebsite.com",
  • "postback": "additem_24AB",
  • "messenger_extensions": false,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 16,
  • "card_id": 18,
  • "audio_id": 20,
  • "video_id": 22,
  • "persisted_menu_id": 24,
  • "story_id": 26,
  • "title": "Our Website",
  • "type": "web_url",
  • "url": "https://mywebsite.com",
  • "postback": "additem_24AB",
  • "messenger_extensions": false,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find button by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 16,
  • "card_id": 18,
  • "audio_id": 20,
  • "video_id": 22,
  • "persisted_menu_id": 24,
  • "story_id": 26,
  • "title": "Our Website",
  • "type": "web_url",
  • "url": "https://mywebsite.com",
  • "postback": "additem_24AB",
  • "messenger_extensions": false,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a button

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a button

path Parameters
id
required
string <JSON>

button id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 16,
  • "card_id": 18,
  • "audio_id": 20,
  • "video_id": 22,
  • "persisted_menu_id": 24,
  • "story_id": 26,
  • "title": "Our Website",
  • "type": "web_url",
  • "url": "https://mywebsite.com",
  • "postback": "additem_24AB",
  • "messenger_extensions": false,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "response_group_id": 16,
  • "card_id": 18,
  • "audio_id": 20,
  • "video_id": 22,
  • "persisted_menu_id": 24,
  • "story_id": 26,
  • "title": "Our Website",
  • "type": "web_url",
  • "url": "https://mywebsite.com",
  • "postback": "additem_24AB",
  • "messenger_extensions": false,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List button clicks

Lists all the clicks of this button made by users

path Parameters
id
required
string <JSON>

button id

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this click belongs to

button_id
number <double>

The ID of the button this click belongs to

bot_user_id
number <double>

The ID of the user who clicked the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this click belongs to

card_id
number <double>

For card buttons only. The ID of the card this click belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this click belongs to

video_id
number <double>

For video buttons only. The ID of the video this click belongs to

broadcast_id
number <double>

(GENERATED) For broadcasted buttons only. The ID of the broadcast this click happened from. If you broadcast cards with buttons or text responses with buttons, or stories that contain them Clicks will show that they were created from that specific broadcast. This can be used to differeniate organic clicks from users and "pushed" clicks that were created because of a push message such as a broadcast

url
string

URL that the user was redirected to after clicking the button

ip_address
string

IP address of the user when they clicked the button

user_agent
string

User agent of the user when they clicked the button

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button_click was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button_click was last updated.

Response samples

Content type
[
  • {
    }
]

image

An image response from the chatbot. An image should be under 1000x1000 in resolution, and should be under 10MB in size. Commonly supported formats are jpg and png. Some messaging apps support gifs, but not all. It is a good idea to preview your stories in your messaging apps to test this.

Create a new image

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Request samples

Content type
{}

Response samples

Content type
{}

Find image by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Response samples

Content type
{}

Delete an image

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update an image

path Parameters
id
required
string <JSON>

image id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Request samples

Content type
{}

Response samples

Content type
{}

Filter images by tags

Internal webhook to filter images by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=orange,tshirt,OR(cotton,unisex)

A comma-separated list of keywords to filter images by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the images I was able to find!

A message to show before displaying the filtered images

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no images were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no images were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered images

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of images to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N images to display

Responses

Response Schema:
object

A list of filtered images in webhook response format

Response samples

Content type
{ }

Upload image media

Upload image to your bot storage. This will consume your account file storage space. The upload needs to be performed with FormData.

Responses

Response Schema:
object

Response samples

Content type
{}

Upload image media URL

Upload image to your bot storage from another URL. This will consume your account file storage space. The upload needs to be performed with an existing URL. The bot_id needs to be present in the request body as well.

Responses

Response Schema:
object

Response samples

Content type
{}

Search image responses

List all images of a bot

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Response samples

Content type
[]

Get step image

Get the image of a step

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this image belongs to

name
required
string

The name of the image

url
required
string

URL of the image image

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the image was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the image was last updated.

square_url
string

(GENERATED) URL of the image image resized to square aspect ratio

horizontal_url
string

(GENERATED) URL of the image image resized to horizontal aspect ratio

original_url
string

(GENERATED) URL of the image image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the image

Response samples

Content type
{}

audio

An audio response from the chatbot. An audio should be under 10MB in size. In some messaging apps, an audio can be displayed in a card format with an image, title, subtitle, and buttons. Commonly support audio formats are mp3, aac, and wav. It is a good idea to preview your stories in your messaging apps to test this.

Create a new audio

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Request samples

Content type
{}

Response samples

Content type
{}

Get audio by ID

path Parameters
id
required
string <JSON>

Model id

query Parameters
filter
string <JSON>

Filter defining fields and include - must be a JSON-encoded string ({"something":"value"})

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Response samples

Content type
{}

Delete an audio

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update an audio

path Parameters
id
required
string <JSON>

audio id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Request samples

Content type
{}

Response samples

Content type
{}

List audio buttons

List all buttons of an audio

path Parameters
id
required
string <JSON>

audio id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Response samples

Content type
[
  • {
    }
]

Filter audios by tags

Internal webhook to filter audios by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=orange,tshirt,OR(cotton,unisex)

A comma-separated list of keywords to filter audios by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the audios I was able to find!

A message to show before displaying the filtered audios

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no audios were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no audios were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered audios

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of audios to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N audios to display

Responses

Response Schema:
object

A list of filtered audios in webhook response format

Response samples

Content type
{ }

Upload audio media

Upload audio to your bot storage. This will consume your account file storage space. The upload needs to be performed with FormData.

Responses

Response Schema:
object

Response samples

Content type
{}

Upload audio media URL

Upload audio to your bot storage from another URL. This will consume your account file storage space. The upload needs to be performed with an existing URL. The bot_id needs to be present in the request body as well.

Responses

Response Schema:
object

Response samples

Content type
{}

Search audio responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Response samples

Content type
[]

Get step audio

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this audio belongs to

title
required
string <= 80 characters

The name of the audio

url
required
string

The URL of the audio

autoloop
boolean
Default: false

Whether or not playing this audio will automatically loop in the Messaging App

subtitle
string <= 80 characters

Listen to the greatest Rock song of all time

stats
object

(GENERATED) An object of the stats of this audio response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the audio was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the audio was last updated.

image_url
string

URL of the audio image

square_image_url
string

(GENERATED) URL of the audio image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the audio image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the audio image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the audio

Response samples

Content type
{}

video

A video response from the chatbot. A video should be under 20MB in size. In some messaging apps, a video can be displayed in a card format with an image, title, subtitle, and buttons. Commonly support video formats are mp4, mpeg, and mov. It is a good idea to preview your stories in your messaging apps to test this.

Create a new video

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Request samples

Content type
{}

Response samples

Content type
{}

Get video by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Response samples

Content type
{}

Delete a video

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a video

path Parameters
id
required
string <JSON>

video id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Request samples

Content type
{}

Response samples

Content type
{}

List video buttons

List all buttons of a video

path Parameters
id
required
string <JSON>

video id

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this button belongs to

type
required
string
Enum: "web_url" "postback" "phone_number" "text"

The type of the button

title
required
string

The name of the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this button belongs to

card_id
number <double>

For card buttons only. The ID of the card this button belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this button belongs to

video_id
number <double>

For video buttons only. The ID of the video this button belongs to

persisted_menu_id
number <double>

For persisted menu buttons only. The ID of the persisted menu this button belongs to

story_id
number <double>

For postback type buttons only. The ID of the story this button will trigger

url
string

For URL buttons only. The URL that the user will visit upon clicking this button

postback
string

For postback buttons only. The postback payload that will be sent to the bot upon clicking this button

messenger_extensions
boolean
Default: false

(DEPRECATED) Whether or not this button has Facebook Messenger Extension capability

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button was last updated.

Response samples

Content type
[
  • {
    }
]

Filter videos by tags

Internal webhook to filter videos by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=orange,tshirt,OR(cotton,unisex)

A comma-separated list of keywords to filter videos by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the videos I was able to find!

A message to show before displaying the filtered videos

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no videos were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no videos were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered videos

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of videos to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N videos to display

broadcast_id
number <double>
Example: broadcast_id=14

(GENERATED) The broadcast ID if this request is coming from a broadcast

Responses

Response Schema:
object

A list of filtered videos in webhook response format

Response samples

Content type
{ }

Upload video media

Upload video to your bot storage. This will consume your account file storage space. The upload needs to be performed with FormData.

Responses

Response Schema:
object

Response samples

Content type
{}

Upload video media URL

Upload video to your bot storage from another URL. This will consume your account file storage space. The upload needs to be performed with an existing URL. The bot_id needs to be present in the request body as well.

Responses

Response Schema:
object

Response samples

Content type
{}

Search video responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Response samples

Content type
[]

Get step video

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this video belongs to

title
required
string <= 80 characters

The name of the video

url
required
string

The URL of the video

autoloop
boolean
Default: false

Whether or not playing this video will automatically loop in the Messaging App

subtitle
string <= 80 characters

For video cards only. A short description of the card

stats
object

(GENERATED) An object of the stats of this video response used for analytics purposes

clicks
number <double>
Default: 0

(GENERATED) The total URL clicks of this card response aggregated across all bot_users

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the video was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the video was last updated.

image_url
string

URL of the video image

square_image_url
string

(GENERATED) URL of the video image resized to square aspect ratio

horizontal_image_url
string

(GENERATED) URL of the video image resized to horizontal aspect ratio

original_image_url
string

(GENERATED) URL of the video image resized to original aspect ratio

tags_string
string

A comma-separated list of tags for the video

Response samples

Content type
{}

sticker

A sticker response from the chatbot. In messaging apps that support this, a sticker emoji or sticker set name can be provided. These are both optional. If they are both not provided, a random sticker is selected. If a messaging app does not support sticker responses from the bot, an image that is sticker-like will be returned instead. It is a good idea to preview your stories in your messaging apps to test this.

Create a new sticker

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get sticker by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a sticker

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a sticker

path Parameters
id
required
string <JSON>

sticker id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search sticker responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Response samples

Content type
[
  • {
    }
]

Get step sticker

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this sticker belongs to

sticker_emoji
string

The emoji of the sticker

sticker_set_name
string

For Telegram stickers only. The sticker pack name. This is derived from the last part of a Sticker Pack URL. e.g. for the Sticker Pack URL https://t.me/addstickers/Animals, the Set Name is Animals

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the sticker was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the sticker was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "sticker_emoji": "😭",
  • "sticker_set_name": "Animals",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

document

A document response from the chatbot. A document should be under 10MB in size. Commonly supported formats are pdf, docx, xlsx, and pptx. It is a good idea to preview your stories in your messaging apps to test this.

Create a new document

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Get document by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Delete a document

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a document

path Parameters
id
required
string <JSON>

document id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

Filter documents by tags

Internal webhook to filter documents by the declared query parameters

query Parameters
user_id
required
string
Example: user_id=12

Must always be "{{user.id}}"

q
string
Example: q=orange,tshirt,OR(cotton,unisex)

A comma-separated list of keywords to filter documents by tags. This can also include conditional logic for more complex queries

where
string <JSON>

Pre-filter model by this loopback where filter first

order
string
Example: order=updated_at DESC

Sort results in ascending or descending order based on a property

confirmation_message
string
Example: confirmation_message=Here are the documents I was able to find!

A message to show before displaying the filtered documents

fallback_message
string
Example: fallback_message=Sorry, I could not find any results

A message to show if no documents were found

fallback_quickreplies
string
Example: fallback_quickreplies=Reset,Menu

A comma-separated list of quick replies to display if no documents were found

show_fallback
boolean
Default: true
Example: show_fallback=true

If false will not show the fallback response

image_aspect_ratio
string
Default: "horizontal"
Enum: "square" "horizontal" "original"

The aspect ratio of the image URL to use when displaying the filtered documents

page_limit
number <double> [ 2 .. 8 ]
Default: 8
Example: page_limit=3

The maximum number of documents to be display per page

sample
number <double>
Example: sample=5

A number N; get a random sample set of N documents to display

broadcast_id
number <double>
Example: broadcast_id=14

(GENERATED) The broadcast ID if this request is coming from a broadcast

Responses

Response Schema:
object

A list of filtered documents in webhook response format

Response samples

Content type
{ }

Upload document media

Upload document to your bot storage. This will consume your account file storage space. The upload needs to be performed with FormData.

Responses

Response Schema:
object

Response samples

Content type
{}

Upload document media URL

Upload document to your bot storage from another URL. This will consume your account file storage space. The upload needs to be performed with an existing URL. The bot_id needs to be present in the request body as well.

Responses

Response Schema:
object

Response samples

Content type
{}

Search document responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Response samples

Content type
[
  • {
    }
]

Get step document

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this document belongs to

name
required
string

The name of the document

url
required
string

The URL of the document

original_name
string

The file name of the documented when it is downloaded

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the document was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the document was last updated.

tags_string
string

A comma-separated list of tags for the document

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Our_NDA.pdf",
  • "url": "https://ourhosting.com/files/Our_NDA.pdf",
  • "original_name": "MYCOMPANY_NDA.pdf",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tags_string": "orange,tshirt,cotton,unisex"
}

action

A context change response from the chatbot. An action can modify memory keys, user attributes, user tags, and bot shortcuts. It can even reset memory keys, user attributes, or user tags by patterns containing strings. Use actions to modify memory and other variables in your users' chat sessions.

Create a new action

Request Body schema:

Action instance data

bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List all actions

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"bot_id":2}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Response samples

Content type
[
  • {
    }
]

Get action by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an action

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update an action

path Parameters
id
required
string <JSON>

action id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search action responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Response samples

Content type
[
  • {
    }
]

Get step action

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this step belongs to

type
required
string
Default: "memory"
Enum: "memory" "attribute" "tag" "shortcut" "reset"

The action type

context_property
required
string

The property of the context this action will change

function_id
required
number <double>

The ID of the function this action is executed with

name
string

(GENERATED) The name of the action generated by its context property, function name, and value

value
string

The value to send to the action. Can be blank

reset_group
string
Default: "memory"
Enum: "memory" "user attributes" "user tags"

For reset actions only. What context to reset

reset_type
string
Default: "all"
Enum: "all" "containing"

For reset actions only. Which parts of the context to reset

reset_containing
string

For reset-containing actions only. The word that keys should contain to be reset

lifespan
number <double> >= -1
Default: 1

an integer where -1 represents forget after this turn 0 represents remember forever 1 represents remember for 1 turn 2 represents remember for 2 turns etc

id
number <double>
is_system
boolean
Default: false

(GENERATED) Whether or not this record was generated by the system. If true, this record cannot be deleted

created_at
string <date-time>

(GENERATED) The datetime at which the action was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the action was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "function_id": 16,
  • "type": "memory",
  • "context_property": "onboarding-step",
  • "name": "onboarding-step $setTo step1",
  • "value": "step1",
  • "reset_group": "memory",
  • "reset_type": "all",
  • "reset_containing": "profile_",
  • "lifespan": 1,
  • "id": 0,
  • "is_system": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

webhook

An API call response from the chatbot. Webhooks can be used to call other technology and platform APIs as well your own internal internet-connected systems. They must however return responses in a specific format that is compatible with BotDistrikt. You can read more about this format in the general documentation.

Create a new webhook

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get webhook by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a webhook

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a webhook

path Parameters
id
required
string <JSON>

webhook id

Request Body schema:

An object of model property name/value pairs

bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search webhook responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Response samples

Content type
[
  • {
    }
]

Get step webhook

path Parameters
id
required
string <JSON>

step id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this webhook belongs to

name
required
string

The name of the webhook

method
required
string
Enum: "GET" "POST"

The method of the API call

url
required
string

The URL endpoint of the API call

query_params
object

An object of key-value pairs to call the API with. If method is GET, these are sent as query params. If method is POST, these are sent as JSON-encoded body params.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the webhook was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the webhook was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "name": "Find Order by ID",
  • "method": "GET",
  • "url": "https://myexternalapi.com/orders/{{memory.order-id}}",
  • "query_params": {
    },
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

bot_user

A user who chats with the bot. Users are the most important model in BotDistrikt because they are your contact points to real people who used your chatbot in any messaging app. Their chat sessions, history, and overall usage with all interactions and clicks are tracked throughout their time spent on the bot. They can even be contacted directly by live agents in the Inbox or User Profile page. Users are automatically created when they start a new conversation with your bot on any messaging app. However, sometimes you may want to reach out to a new user on your own by a personally identifier such as a phone number. Creating a new user and making your bot reach out to them is only possible on WhatsApp and SMS channels using the phone number identifier. Users are permanent as long as they used the same profile on the same messaging app, so you can use user attributes as a safe space to store valuable information about users that the bot will need to remember over its lifetime. Only for the Website channel however, we do not identify users by any personal profile, so each session in a website chat will have its own unique generated user. You can read more about this format in the general documentation.

Create a user

You can only create SMS or WhatsApp users with phone numbers. Users from other messaging apps are automatically generated when they start a new conversation with the bot on the respective messaging app

Request Body schema:

Model instance data

bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get user by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a user

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a user

path Parameters
id
required
string <JSON>

bot_user id

Request Body schema:

An object of model property name/value pairs

bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Upsert a user

Update or create a new bot SMS or WhatsApp user by their phone number

query Parameters
object

Criteria to match users

Request Body schema:

An object of model property name/value pairs

bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "facebook_page_id": 14,
  • "assigned_to_member_id": 16,
  • "assigned_by_member_id": 18,
  • "webchat_app_id": 20,
  • "webchat_app_placement_id": 22,
  • "email": "john_snow@gmail.com",
  • "active": true,
  • "first_name": "John",
  • "gender": "male",
  • "fb_id": "927382831237912831237091238712387",
  • "instagram_id": "3627382831237912831237091238712387",
  • "webchat_id": "webchat_x8ys6",
  • "skype_id": "asdahjidjashdasjd.987978686jasjkdasd_",
  • "telegram_id": "28762567257",
  • "whatsapp_id": "whatsappcloud://6581112222@whatsapp.com",
  • "twitter_id": "#asdasdhjasd76755asd7",
  • "assistant_id": "8787as8787asd@asdasdasd9889.google.com",
  • "wechat_id": "887as76d7678asd86ad86",
  • "skype_service_url": "https://service-8asduyasd9.skype.com",
  • "is_group": false,
  • "is_channel": false,
  • "channel": "telegram",
  • "last_message_at": "2023-01-03 23:22:19",
  • "last_click_at": "2022-01-03 23:22:19",
  • "last_push_message_at": "2021-01-03 23:22:19",
  • "last_name": "Snow",
  • "locale": "en_UK",
  • "country": "Singapore",
  • "platform": "Mac OSX",
  • "profile_pic": "https://i.imgur.com/Pl0X14G.png",
  • "timezone": "Asia/Singapore",
  • "phone": "+6581112222",
  • "notes": "This person causes a lot of trouble",
  • "attributes": {
    },
  • "stats": {
    },
  • "sessions": 12,
  • "impressions": 827,
  • "clicks": 8,
  • "delay": 232,
  • "sentiment": -0.5,
  • "tags_string": "premium,highalert",
  • "username": "_johnsnow1992",
  • "test_user": false,
  • "source": "https://rewards.mywebsite.com",
  • "provider": "uib",
  • "user_type": "individual",
  • "fb_user_ref": "112211233213123",
  • "fb_login_id": "mysite_123123sb",
  • "assigned_at": "2022-05-02 09:18:11",
  • "assignment_status": "unassigned",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get current session

Returns the user with current session fields like context_fields and session_ttl. context_fields is a representation of the user's memory context. session_ttl is the number of seconds until the chat session expires This is used to determine whether the user is currently online and how they are using the bot

path Parameters
id
required
string <JSON>

bot_user id

Responses

Response Schema:
context_fields
object

Object of key-value pairs of memory keys of the current session

object

Session details

bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Response samples

Content type
{
  • "context_fields": {
    },
  • "session_fields": {
    },
  • "first_name": "Abhilash",
  • "last_name": "Murthy",
  • "username": null,
  • "email": "abhilash@busuncle.sg",
  • "profile_pic": "https://lh3.googleusercontent.com/a/AGNmyxYhyLKjQyCwixp5yqqUXv63mZLUphAhQSxygx9-jw=s240-c",
  • "attributes": {
    },
  • "tags_string": null,
  • "created_at": "2023-03-05T07:34:48.000Z",
  • "updated_at": "2023-03-09T16:11:21.000Z",
  • "notes": null,
  • "channel": "web",
  • "timezone": null,
  • "phone": null,
  • "source": null,
  • "user_type": "individual",
  • "webchat_id": "botdistrikt.3",
  • "assignment_status": null,
  • "birthday": null,
  • "last_message_at": "2023-03-09T16:10:47.000Z",
  • "last_push_message_at": null,
  • "assigned_to_member_at": null,
  • "last_click_at": "2023-03-09T16:11:21.070Z",
  • "sessions": null,
  • "impressions": null,
  • "clicks": null,
  • "delay": null,
  • "sentiment": null,
  • "active": true,
  • "is_group": false,
  • "is_channel": false,
  • "test_user": true,
  • "stats": null,
  • "id": "372"
}

End current session

Ends the current session of the user This can be used to reset the chat session of the user and start a fresh session with the bot

path Parameters
id
required
string <JSON>

bot_user id

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Response samples

Content type
{
  • "first_name": "Abhilash",
  • "last_name": "Murthy",
  • "username": null,
  • "email": "abhilash@busuncle.sg",
  • "profile_pic": "https://lh3.googleusercontent.com/a/AGNmyxYhyLKjQyCwixp5yqqUXv63mZLUphAhQSxygx9-jw=s240-c",
  • "attributes": {
    },
  • "tags_string": null,
  • "created_at": "2023-03-05T07:34:48.000Z",
  • "updated_at": "2023-03-09T16:11:21.000Z",
  • "notes": null,
  • "channel": "web",
  • "timezone": null,
  • "phone": null,
  • "source": null,
  • "user_type": "individual",
  • "webchat_id": "botdistrikt.3",
  • "assignment_status": null,
  • "birthday": null,
  • "last_message_at": "2023-03-09T16:10:47.000Z",
  • "last_push_message_at": null,
  • "assigned_to_member_at": null,
  • "last_click_at": "2023-03-09T16:11:21.070Z",
  • "sessions": null,
  • "impressions": null,
  • "clicks": null,
  • "delay": null,
  • "sentiment": null,
  • "active": true,
  • "is_group": false,
  • "is_channel": false,
  • "test_user": true,
  • "stats": null,
  • "context_fields": null,
  • "session_fields": {
    },
  • "id": "372"
}

Send a reply

Sends to a reply to the user as a live agent. This can be used to push a text message, story, or WhatsApp Template to the user

path Parameters
id
required
string <JSON>

bot_user id

Request Body schema:
reply_type
required
string
Enum: "text" "story" "whatsapp_template"

What to reply with

text
string

If reply with text, the text to reply with

story
number

If reply with story, the ID of the story to reply with

object

If reply with WhatsApp template, the template object to reply with

Responses

Response Schema:
Array of objects (bot_message)

An array of responses sent to the user

Array of objects (quick_reply)

An array of quick replies sent to the user

object

The user that the reply was sent to

Request samples

Content type
{
  • "reply_type": "text",
  • "text": "Hi, I am Vish. How can I be of help today?"
}

Response samples

Content type
{
  • "webchat_responses": [
    ],
  • "webchat_quickreplies": [ ],
  • "user": {
    }
}

List user attributes

Lists all user attributes used in conditions and actions and stored in your user records

query Parameters
bot_id
number <double>
Example: bot_id=12

The ID of the bot

Responses

Response Schema:
Array
string

A user attribute

Response samples

Content type
[
  • "share_reason",
  • "merchbroadcastabtesting",
  • "profile_name",
  • "photo",
  • "last_shown_ad_at",
  • "admin",
  • "winner",
  • "infinite_session"
]

Add user attributes

Add attributes to bot users matching the given filters If no filter is provided, attribute will be added to all users.

Request Body schema:

An object of key-value pairs to add as attributes to the filtered users

object

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Request samples

Content type
{
  • "filter": {
    },
  • "attributes": {
    }
}

Response samples

Content type
[
  • {
    }
]

Delete user attributes

Delete attributes to bot users matching the given filters. If no filter is provided, attribute(s) will be deleted for all users. For attribute deletion, exact matches or wildcard strings are accepted as keys Example: membership_level, membership_* Request body accepts attributes in array form.

Request Body schema:

An object of array of keys (optionally with wildcards *) to delete from the users

object

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Request samples

Content type
{
  • "filter": {
    },
  • "attributes": [
    ]
}

Response samples

Content type
[
  • {
    }
]

Search users

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this user belongs to

facebook_page_id
number <double>

For Facebook users only. The ID of the Facebook Page this user belongs to

assigned_to_member_id
number <double>

The ID of the team member this user is assigned to

assigned_by_member_id
number <double>

The ID of the team member this user who assigned this user to themselves or another team member

webchat_app_id
number <double>

For Website users only. The ID of the webchat app this user belongs to

webchat_app_placement_id
number <double>

For Website users only. The ID of the webchat app placement this user belongs to

email
string

The email address of the user

active
boolean
Default: true

Whether or not the user can message the bot If a user deletes or blocks the bot, they will be deactivated on the platform within 24 hours

first_name
string
Default: "Dear User"

The first name of the user

gender
string
Enum: "male" "female" "other"

The gender of the user

fb_id
string

For Facebook users only. A unique identifier represented by the Facebook Messenger Integration's PSID

instagram_id
string

For Instagram users only. A unique identifier represented by the Instagram Integration's PSID

webchat_id
string

For Website users only. A unique identifier by the Website Chat Integration

skype_id
string

For Skype users only. A unique identifier by the Skype Integration

telegram_id
string

For Telegram users only. A unique identifier by the Telegram Integration

whatsapp_id
string

For WhatsApp users only. A unique identifier by the WhatsApp Integration. Each provider has its own format

twitter_id
string

For Twitter users only. A unique identifier by the Twitter Integration

assistant_id
string

For Assistant users only. A unique identifier by the Google Assistant Integration

wechat_id
string

For WeChat users only. A unique identifier by the Wechat Integration

skype_service_url
string

For Skype users only. A dedicated URL for this user by the Skype Integration

is_group
boolean
Default: false

Whether or not this user is a group on Messaging Apps that support bots in groups

is_channel
boolean
Default: false

Whether or not this user a channel on Messaging Apps that support bots in channels

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the user

last_message_at
string <date-time>

(GENERATED) The timestamp at which this user last sent a message to your bot

last_click_at
string <date-time>

(GENERATED) The timestamp at which this user last clicked a URL button sent by your bot

last_push_message_at
string <date-time>

(GENERATED) The timestamp at which this user last received a broadcast or live agent reply

last_name
string
Default: ""

The last name of this user

locale
string

The locale that the user set as default on their Messaging App

country
string

The country that the user set as their default on their Messaging App

platform
string

The platform that the user sends messages to the bot from based on their Messaging App

profile_pic
string

URL of the user profile picture

timezone
string

The timezone of the user This is important for calculating the user's relative timezone offset for a Timewarp broadcast. Example: "Asia/Singapore"

phone
string

The phone number of this user

notes
string

Notes written by Team Members about this user

attributes
object

a JSON object of key-value pairs containing the user's attributes. Used in rules, actions, and broadcast filters.

stats
object

(GENERATED) An object of the stats of this user used for analytics purposes

sessions
number <double>
Default: 0

(GENERATD) The total number of sessions had with the bot. A session expires based on the bot's session_ttl

impressions
number <double>
Default: 0

(GENERATED) The total number of stories seen through a bot_message

clicks
number <double>
Default: 0

(GENERATED) The total number of URL button-clicks

delay
number <double>
Default: 0

(GENERATED) The total number of seconds spent messaging the bot

sentiment
number <double>
Default: 0

(GENERATED) The average sentiment value, a floating-point number between -3 and 3 where 0 means neutral, and others represent positive and negative

tags_string
string

A comma-separated list of tags used for organization, reporting, and targeting during broadcasts

username
string

The username of this user based on their Messaging App

test_user
boolean
Default: false

Whether or not this is a test user whos activity should not be counted towards Account Usage

source
string

(GENERATED) For Website users only. The source domain of where the user used the bot from

provider
string
Enum: "uib" "twilio"

FOr WhatsApp users only. The provider of the user on WhatsApp or SMS

user_type
string
Default: "individual"
Enum: "individual" "group" "channel"

A flag to indicate whether this user is an individual, group, or channel

fb_user_ref
string

For Facebook users only. A unique identifier represented by the Facebook Chat Plugin or Checkbox Plugin's user_ref

fb_login_id
string

For Facebook users only. A unique identifier represented by the Facebook Login Connect login_id

assigned_at
string <date-time>

The timestamp at which a live agent was assigned to this user

assignment_status
string
Default: "unassigned"
Enum: "unassigned" "open" "resolving" "closed"

If this user is assigned a live agent, the status of the assignment. Can be used to track open live chat cases.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user was last updated.

Response samples

Content type
[
  • {
    }
]

bot_user_message

An incoming message from a user. This message could be a text message, an image, a button click, a location, or any other type of input. What the user can or cannot send as a message is restricted to the features of the messaging app they are using to send messages to your bot. For example, users cannot send locations on Twitter, but can do so on Telegram, WhatsApp, and Facebook Messenger. Messages cannot be created or updated from the API. You may use webchat_webhook to send messages from your own custom webchat API users instead. You can read more about this in the general documentation.

List messages from user

path Parameters
id
required
string <JSON>

bot_user id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this message belongs to

bot_user_id
number <double>

The ID of the user who sent this message

text
string

The text of the message

image_url
string

If the user sends an image, the URL of the image

video_url
string

If the user sends a video, the URL of the video

audio_url
string

If the user sends an audio, the URL of the audio

sticker_id
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker ID

sticker_emoji
string

For Telegram messages only. If the user sends a sticker, the related Telegram sticker emoji

sticker_set_name
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker set name

postback_payload
string

If the user triggers an event, the payload of the event. This is commonly used in button clicks

location
string

If the user sends a location, the geographical coordinates represented by [float],[float] (lat,long)

location_object
object

If the user sends a location, an object in the format { "lat": [float], "long": [float] }

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

correct_type
string
Default: "correct"
Enum: "correct" "wrong"

A flag to indicate whether the bot responded to this message correctly or made a wrong response

correction_status
string
Default: "acknowledged"
Enum: "acknowledged" "resolving" "resolved" "ignored"

If this message had a wrong response, the correction status of the wrong response

notes
string

If this message had a wrong response, notes written by Team Members about this message

memory_context
object

The memory context at the time this message was created

user_object
object

The user object at the time this message was created

nlp_context
object

The nlp context at the time this message was created

test_message
boolean
Default: false

Whether or not this was a test message sent by a test user whos activity should not be counted towards Account Usage

instagram_mid
string

For Instagram messages only. Message ID from the Instagram integration

story_mention_url
string

For Instagram messages only. Image URL of an Instagram Story mention

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was last updated.

tags_string
string

A comma-separated list of tags for the bot_user_message

Response samples

Content type
[]

Get message by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this message belongs to

bot_user_id
number <double>

The ID of the user who sent this message

text
string

The text of the message

image_url
string

If the user sends an image, the URL of the image

video_url
string

If the user sends a video, the URL of the video

audio_url
string

If the user sends an audio, the URL of the audio

sticker_id
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker ID

sticker_emoji
string

For Telegram messages only. If the user sends a sticker, the related Telegram sticker emoji

sticker_set_name
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker set name

postback_payload
string

If the user triggers an event, the payload of the event. This is commonly used in button clicks

location
string

If the user sends a location, the geographical coordinates represented by [float],[float] (lat,long)

location_object
object

If the user sends a location, an object in the format { "lat": [float], "long": [float] }

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

correct_type
string
Default: "correct"
Enum: "correct" "wrong"

A flag to indicate whether the bot responded to this message correctly or made a wrong response

correction_status
string
Default: "acknowledged"
Enum: "acknowledged" "resolving" "resolved" "ignored"

If this message had a wrong response, the correction status of the wrong response

notes
string

If this message had a wrong response, notes written by Team Members about this message

memory_context
object

The memory context at the time this message was created

user_object
object

The user object at the time this message was created

nlp_context
object

The nlp context at the time this message was created

test_message
boolean
Default: false

Whether or not this was a test message sent by a test user whos activity should not be counted towards Account Usage

instagram_mid
string

For Instagram messages only. Message ID from the Instagram integration

story_mention_url
string

For Instagram messages only. Image URL of an Instagram Story mention

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was last updated.

tags_string
string

A comma-separated list of tags for the bot_user_message

Response samples

Content type
{}

Search messages

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this message belongs to

bot_user_id
number <double>

The ID of the user who sent this message

text
string

The text of the message

image_url
string

If the user sends an image, the URL of the image

video_url
string

If the user sends a video, the URL of the video

audio_url
string

If the user sends an audio, the URL of the audio

sticker_id
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker ID

sticker_emoji
string

For Telegram messages only. If the user sends a sticker, the related Telegram sticker emoji

sticker_set_name
string

For Telegram messages only. If the user sends a sticker, the Telegram sticker set name

postback_payload
string

If the user triggers an event, the payload of the event. This is commonly used in button clicks

location
string

If the user sends a location, the geographical coordinates represented by [float],[float] (lat,long)

location_object
object

If the user sends a location, an object in the format { "lat": [float], "long": [float] }

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

correct_type
string
Default: "correct"
Enum: "correct" "wrong"

A flag to indicate whether the bot responded to this message correctly or made a wrong response

correction_status
string
Default: "acknowledged"
Enum: "acknowledged" "resolving" "resolved" "ignored"

If this message had a wrong response, the correction status of the wrong response

notes
string

If this message had a wrong response, notes written by Team Members about this message

memory_context
object

The memory context at the time this message was created

user_object
object

The user object at the time this message was created

nlp_context
object

The nlp context at the time this message was created

test_message
boolean
Default: false

Whether or not this was a test message sent by a test user whos activity should not be counted towards Account Usage

instagram_mid
string

For Instagram messages only. Message ID from the Instagram integration

story_mention_url
string

For Instagram messages only. Image URL of an Instagram Story mention

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_user_message was last updated.

tags_string
string

A comma-separated list of tags for the bot_user_message

Response samples

Content type
[]

Get message story stat

A message story stat is a stats record about a message sent after a user viewed a story. This can be aggregated for analytics purposes

path Parameters
id
required
string <JSON>

bot_user_message id

Responses

Response Schema:
delay
number <double>

(GENERATED) The total number of seconds the user viewed the last story for

sentiment
number <double>

(GENERATED) The sentiment value of the message

id
number <double>
bot_user_message_id
number <double>

The ID of the message this stat was generated for

story_id
number <double>

The ID of the last story the user saw before sending the message of this stat

bot_id
number <double>

The ID of the bot that this stat belongs to

bot_user_id
number <double>

The ID of the user who sent the message of this stat

Response samples

Content type
{
  • "delay": 23,
  • "sentiment": 0.5,
  • "id": 0,
  • "bot_user_message_id": 12,
  • "story_id": 14,
  • "bot_id": 16,
  • "bot_user_id": 18
}

bot_message

An outgoing response from the chatbot to the user. This response could be a text message, cards, images, or others depending on the response type in stories. What the bot can or cannot send as a response is restricted to the features of the messaging app a user is using to send messages to your bot. For example, bots cannot send locations on Twitter, but can do so on Telegram, WhatsApp, and Facebook Messenger. Responses cannot be created or updated from the API. You may use broadcasts or push live agent replies to send custom responses instead. You can read more about this in the general documentation.

List responses to message

path Parameters
id
required
string <JSON>

bot_user_message id

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this response belongs to

bot_user_id
number <double>

The ID of the user who received this response

bot_user_message_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the user message that triggered this response

step_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the step that created this response

story_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the story that created this response

human_id
number <double>

If from a human (as opposed to broadcasts and the bot itself). The ID of the team member who created this response

broadcast_id
number <double>

If from a broadcast (as opposed to live agent responses and the bot itself). The ID of the broadcast that created this response

text
string

The text of the response. If the response is a complex element like a card or image, this value will not matter

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

type
string
Enum: "text" "image" "audio" "video" "sticker" "document" "cards"

The type of the response

from_type
string
Default: "bot"
Enum: "bot" "human" "broadcast"

The sender of the response, whether it came from the bot, a live agent, or a broadcast

quickreplies_payload
object

An array of quick_reply objects for this response

response_payload
object

A complex object with all the details of the response

is_fallback
boolean
Default: false

Whether or not this was a response that came from the fallback story

twilio_whatsapp_sid
string

For Twilio WhatsApp responses only. The Twilio WhatsApp Message SID

telegram_message_id
string

For Telegram responses only. The Telegram Message ID for editing messages inline

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_message was last updated.

Response samples

Content type
[
  • {
    }
]

Get response by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this response belongs to

bot_user_id
number <double>

The ID of the user who received this response

bot_user_message_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the user message that triggered this response

step_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the step that created this response

story_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the story that created this response

human_id
number <double>

If from a human (as opposed to broadcasts and the bot itself). The ID of the team member who created this response

broadcast_id
number <double>

If from a broadcast (as opposed to live agent responses and the bot itself). The ID of the broadcast that created this response

text
string

The text of the response. If the response is a complex element like a card or image, this value will not matter

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

type
string
Enum: "text" "image" "audio" "video" "sticker" "document" "cards"

The type of the response

from_type
string
Default: "bot"
Enum: "bot" "human" "broadcast"

The sender of the response, whether it came from the bot, a live agent, or a broadcast

quickreplies_payload
object

An array of quick_reply objects for this response

response_payload
object

A complex object with all the details of the response

is_fallback
boolean
Default: false

Whether or not this was a response that came from the fallback story

twilio_whatsapp_sid
string

For Twilio WhatsApp responses only. The Twilio WhatsApp Message SID

telegram_message_id
string

For Telegram responses only. The Telegram Message ID for editing messages inline

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_message was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "bot_user_id": 14,
  • "bot_user_message_id": 16,
  • "step_id": 18,
  • "story_id": 18,
  • "human_id": 20,
  • "broadcast_id": 22,
  • "text": "Hi how can I help you?",
  • "channel": "telegram",
  • "type": "text",
  • "from_type": "bot",
  • "quickreplies_payload": [
    ],
  • "response_payload": {
    },
  • "is_fallback": false,
  • "twilio_whatsapp_sid": "982378jas98asdhdsa",
  • "telegram_message_id": 98123812781289290000,
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List responses to user

path Parameters
id
required
string <JSON>

bot_user id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this response belongs to

bot_user_id
number <double>

The ID of the user who received this response

bot_user_message_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the user message that triggered this response

step_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the step that created this response

story_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the story that created this response

human_id
number <double>

If from a human (as opposed to broadcasts and the bot itself). The ID of the team member who created this response

broadcast_id
number <double>

If from a broadcast (as opposed to live agent responses and the bot itself). The ID of the broadcast that created this response

text
string

The text of the response. If the response is a complex element like a card or image, this value will not matter

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

type
string
Enum: "text" "image" "audio" "video" "sticker" "document" "cards"

The type of the response

from_type
string
Default: "bot"
Enum: "bot" "human" "broadcast"

The sender of the response, whether it came from the bot, a live agent, or a broadcast

quickreplies_payload
object

An array of quick_reply objects for this response

response_payload
object

A complex object with all the details of the response

is_fallback
boolean
Default: false

Whether or not this was a response that came from the fallback story

twilio_whatsapp_sid
string

For Twilio WhatsApp responses only. The Twilio WhatsApp Message SID

telegram_message_id
string

For Telegram responses only. The Telegram Message ID for editing messages inline

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_message was last updated.

Response samples

Content type
[
  • {
    }
]

Search responses

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this response belongs to

bot_user_id
number <double>

The ID of the user who received this response

bot_user_message_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the user message that triggered this response

step_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the step that created this response

story_id
number <double>

If from the bot (as opposed to broadcasts and live agent responses). The ID of the story that created this response

human_id
number <double>

If from a human (as opposed to broadcasts and the bot itself). The ID of the team member who created this response

broadcast_id
number <double>

If from a broadcast (as opposed to live agent responses and the bot itself). The ID of the broadcast that created this response

text
string

The text of the response. If the response is a complex element like a card or image, this value will not matter

channel
string
Default: "fb"
Enum: "fb" "web" "skype" "whatsapp" "telegram" "assistant" "instagram" "twitter" "sms" "wechat"

The Messaging App of the incoming message

type
string
Enum: "text" "image" "audio" "video" "sticker" "document" "cards"

The type of the response

from_type
string
Default: "bot"
Enum: "bot" "human" "broadcast"

The sender of the response, whether it came from the bot, a live agent, or a broadcast

quickreplies_payload
object

An array of quick_reply objects for this response

response_payload
object

A complex object with all the details of the response

is_fallback
boolean
Default: false

Whether or not this was a response that came from the fallback story

twilio_whatsapp_sid
string

For Twilio WhatsApp responses only. The Twilio WhatsApp Message SID

telegram_message_id
string

For Telegram responses only. The Telegram Message ID for editing messages inline

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the bot_message was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the bot_message was last updated.

Response samples

Content type
[
  • {
    }
]

button_click

A click record of a URL button that was clicked by a user. These click records are created to track click activity throughout your bot experience. They can be used to determine marketing KPIs such as Click-Through Rates, as well as how well your bot answers questions instead of leading users out to get answers from other websites. Each click tracks a user's IP address, user agent, the URL they visited, and the timestamp at which they made the click. Clicks cannot be created via the API. You can read more about this in the general documentation.

List clicks from user

path Parameters
id
required
string <JSON>

bot_user id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this click belongs to

button_id
number <double>

The ID of the button this click belongs to

bot_user_id
number <double>

The ID of the user who clicked the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this click belongs to

card_id
number <double>

For card buttons only. The ID of the card this click belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this click belongs to

video_id
number <double>

For video buttons only. The ID of the video this click belongs to

broadcast_id
number <double>

(GENERATED) For broadcasted buttons only. The ID of the broadcast this click happened from. If you broadcast cards with buttons or text responses with buttons, or stories that contain them Clicks will show that they were created from that specific broadcast. This can be used to differeniate organic clicks from users and "pushed" clicks that were created because of a push message such as a broadcast

url
string

URL that the user was redirected to after clicking the button

ip_address
string

IP address of the user when they clicked the button

user_agent
string

User agent of the user when they clicked the button

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button_click was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button_click was last updated.

Response samples

Content type
[
  • {
    }
]

Search clicks

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this click belongs to

button_id
number <double>

The ID of the button this click belongs to

bot_user_id
number <double>

The ID of the user who clicked the button

response_group_id
number <double>

For text response buttons only. The ID of the text resposne this click belongs to

card_id
number <double>

For card buttons only. The ID of the card this click belongs to

audio_id
number <double>

For audio buttons only. The ID of the audio this click belongs to

video_id
number <double>

For video buttons only. The ID of the video this click belongs to

broadcast_id
number <double>

(GENERATED) For broadcasted buttons only. The ID of the broadcast this click happened from. If you broadcast cards with buttons or text responses with buttons, or stories that contain them Clicks will show that they were created from that specific broadcast. This can be used to differeniate organic clicks from users and "pushed" clicks that were created because of a push message such as a broadcast

url
string

URL that the user was redirected to after clicking the button

ip_address
string

IP address of the user when they clicked the button

user_agent
string

User agent of the user when they clicked the button

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the button_click was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the button_click was last updated.

Response samples

Content type
[
  • {
    }
]

broadcast_record

The receipt status of a broadcast for each user who it was intended to reach. This can be used to identify if users have blocked or deleted your bot, and log why some users did or did not receive a broadcast notification. Broadcast records cannot be created via the API

List broadcast records of user

path Parameters
id
required
string <JSON>

bot_user id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this broadcast record belongs to

bot_user_id
number <double>

The ID of the user who received the broadcast

broadcast_id
number <double>

The ID of the broadcast that created this receipt

story_id
number <double>

The ID of the story that was broadcasted

status
string
Enum: "completed" "error"

The status of the broadcast record

message
string

If there was an error status, the error message returned with the broadcast record

responses_count
number <double>

The number of responses sent to a user from this broadcast. This can be used to filter dynamic broadcasts where users may or may not receive messages

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was last updated.

Response samples

Content type
[
  • {
    }
]

Search broadcast records

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this broadcast record belongs to

bot_user_id
number <double>

The ID of the user who received the broadcast

broadcast_id
number <double>

The ID of the broadcast that created this receipt

story_id
number <double>

The ID of the story that was broadcasted

status
string
Enum: "completed" "error"

The status of the broadcast record

message
string

If there was an error status, the error message returned with the broadcast record

responses_count
number <double>

The number of responses sent to a user from this broadcast. This can be used to filter dynamic broadcasts where users may or may not receive messages

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was last updated.

Response samples

Content type
[
  • {
    }
]

message_story_stat

A stats record about a message sent after a user viewed a story. Message story stats are powerful for analytics purposes. A message story stat is only created when a user "sees" a response, and replies to it with another message. Therefore, another word for message story stats is "impressions". A message story has a delay - the number of seconds passed from when a user saw a resposne, and replied with the next message. Delay can also just be calculated manually by subtracting the created_at values of chronological bot_user_messages. A message story has a sentiment - the sentiment of the user's message after they saw the bot's last response. It is important to note that because message story stats are only created AFTER a bot's response, the first messages a usre sends to the bot will NOT have any message story stat. Using this logic, the number of sessions can be transitivey calculated as the the total number of bot_user_messages minus the total number of message_story_stats. Sessions can be used to calculate retention rates of users effectively.

Search message story stats

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
delay
number <double>

(GENERATED) The total number of seconds the user viewed the last story for

sentiment
number <double>

(GENERATED) The sentiment value of the message

id
number <double>
bot_user_message_id
number <double>

The ID of the message this stat was generated for

story_id
number <double>

The ID of the last story the user saw before sending the message of this stat

bot_id
number <double>

The ID of the bot that this stat belongs to

bot_user_id
number <double>

The ID of the user who sent the message of this stat

Response samples

Content type
[
  • {
    }
]

broadcast

A feature to send bulk notifications and responses to several users at the same time Broadcasts are the most important feature for push notifications and targeted messaging to users. They can be used to promote new products, services, events, and other elements of your business. They can also be used to re-engage users, provide tips to use bot, and notify users about new features and functionalities in your chatbot. You should however control how many and how often you send broadcasts as users may deem them as spam messaging and may report your bot. The consequences of too much reporting or blocking can affect the health and availability of your bot depending on the messaging app it is sent in. Some messaging apps have restrictions over how many and how often you can send broadcasts such as WhatsApp and WeChat You can read more about this in the general documentation.

Create a new broadcast

Request Body schema:

Model instance data

bot_id
required
number <double>

The ID of the bot this broadcast belongs to

broadcast_object
required
string
Default: "story"
Enum: "story" "text" "card" "image" "whatsapp_template"

What to broadcast

scheduled_time
required
string <date-time>

The timestamp when the broadcast will be published

loopback_target
required
object

Loopback filter defining the target subset of users to send the broadcast to. See https://loopback.io/doc/en/lb3/Where-filter.html for more details. You may test the list of users who will receive the broadcast with Search Users

predicted_reach
number <double>
Default: 0

(GENERATED) The total number of users predicted to receive the broadcast at the time it was created

actual_reach
number <double>
Default: 0

(GENERATED) The total number of users who actually received the broadcast at the time it was published

limit
number <double>

A ceiling to limit the number of users who will receive this broadcast

limit_type
string
Default: "default"
Enum: "default" "random"

If the limit is set, the selection strategy of the set of users who receive the broadcast

opened
number <double>
target
object

A filter that targets which subset of users will receive the broadcast. This object is optional and only used to display the target dropdown boxes on the BotDistrikt Platform UI. The required targeting object in a broadcast is called loopback_target.

progress
number <double>
publish_when
string
Default: "later"
Enum: "now" "later" "timewarp" "recurring"

The scheduling strategy of the broadcast

status
string
Default: "UNPUBLISHED"
Enum: "UNPUBLISHED" "RETRYING" "SCHEDULED" "RECURRING" "PUBLISHING" "FINISHED" "ERROR"

The current status of the broadcast

timezone
string

The timezone of the broadcast. Used to calculate the relative timezone offset of a user for Timewarp broadcasts. This will allow each user to receive the broadcast at the same time, irrespective of their timezone

is_recurring
boolean
Default: false

Whether or not the broadcast will be a recurring one

recurring_period
string
Enum: "hour" "day" "week" "month" "year"

For recurring broadcasts only. The time period interval at which recurring broadcasts are scheduled. For example, if a broadcast is scheduled for 2022-10-03 14:00:00 and set a recurring period of 1 week, as soon as the broadcast finishes publishing, it will automatically create another recurring broadcast scheduled at 2022-17-03 14:00:00. This will continuously proceed until a recurring broadcast is cancelled.

prev_broadcast_id
number <double>

For recurring broadcasts only. The ID of the next recurring broadcast that is created automatically by this one after this broadcast is FINISHED.

story_id
number <double>

For story broadcasts only. The ID of the story to broadcast to the targeted users

card_id
number <double>

For card broadcasts only. The ID of the card to broadcast to the targeted users

image_id
number <double>

For image broadcasts only. The ID of the image to broadcast to the targeted users

broadcast_text
string

For text broadcasts only. The text to broadcast to the targeted users

object

For WhatsApp Template broadcasts only. The WhatsApp Template name and parameters to broadcast.

clicked_users
object

(GENERATED) An array of unique IDs of bot users who clicked on links from this broadcast. This is used to quickly calculate the Click-Through Rate (CTR) of the broadcast

id
number <double>
next_broadcast_id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast was last updated.

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this broadcast belongs to

broadcast_object
required
string
Default: "story"
Enum: "story" "text" "card" "image" "whatsapp_template"

What to broadcast

scheduled_time
required
string <date-time>

The timestamp when the broadcast will be published

loopback_target
required
object

Loopback filter defining the target subset of users to send the broadcast to. See https://loopback.io/doc/en/lb3/Where-filter.html for more details. You may test the list of users who will receive the broadcast with Search Users

predicted_reach
number <double>
Default: 0

(GENERATED) The total number of users predicted to receive the broadcast at the time it was created

actual_reach
number <double>
Default: 0

(GENERATED) The total number of users who actually received the broadcast at the time it was published

limit
number <double>

A ceiling to limit the number of users who will receive this broadcast

limit_type
string
Default: "default"
Enum: "default" "random"

If the limit is set, the selection strategy of the set of users who receive the broadcast

opened
number <double>
target
object

A filter that targets which subset of users will receive the broadcast. This object is optional and only used to display the target dropdown boxes on the BotDistrikt Platform UI. The required targeting object in a broadcast is called loopback_target.

progress
number <double>
publish_when
string
Default: "later"
Enum: "now" "later" "timewarp" "recurring"

The scheduling strategy of the broadcast

status
string
Default: "UNPUBLISHED"
Enum: "UNPUBLISHED" "RETRYING" "SCHEDULED" "RECURRING" "PUBLISHING" "FINISHED" "ERROR"

The current status of the broadcast

timezone
string

The timezone of the broadcast. Used to calculate the relative timezone offset of a user for Timewarp broadcasts. This will allow each user to receive the broadcast at the same time, irrespective of their timezone

is_recurring
boolean
Default: false

Whether or not the broadcast will be a recurring one

recurring_period
string
Enum: "hour" "day" "week" "month" "year"

For recurring broadcasts only. The time period interval at which recurring broadcasts are scheduled. For example, if a broadcast is scheduled for 2022-10-03 14:00:00 and set a recurring period of 1 week, as soon as the broadcast finishes publishing, it will automatically create another recurring broadcast scheduled at 2022-17-03 14:00:00. This will continuously proceed until a recurring broadcast is cancelled.

prev_broadcast_id
number <double>

For recurring broadcasts only. The ID of the next recurring broadcast that is created automatically by this one after this broadcast is FINISHED.

story_id
number <double>

For story broadcasts only. The ID of the story to broadcast to the targeted users

card_id
number <double>

For card broadcasts only. The ID of the card to broadcast to the targeted users

image_id
number <double>

For image broadcasts only. The ID of the image to broadcast to the targeted users

broadcast_text
string

For text broadcasts only. The text to broadcast to the targeted users

object

For WhatsApp Template broadcasts only. The WhatsApp Template name and parameters to broadcast.

clicked_users
object

(GENERATED) An array of unique IDs of bot users who clicked on links from this broadcast. This is used to quickly calculate the Click-Through Rate (CTR) of the broadcast

id
number <double>
next_broadcast_id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast was last updated.

Request samples

Content type
{
  • "scheduled_time": "2022-10-03 12:05:00",
  • "predicted_reach": 2302,
  • "actual_reach": 2514,
  • "limit": 100,
  • "limit_type": "default",
  • "opened": 0,
  • "target": [
    ],
  • "progress": 0,
  • "publish_when": "later",
  • "status": "UNPUBLISHED",
  • "timezone": "Asia/Singapore",
  • "loopback_target": [
    ],
  • "is_recurring": false,
  • "recurring_period": "week",
  • "prev_broadcast_id": 24,
  • "broadcast_object": "story",
  • "story_id": 12,
  • "card_id": 14,
  • "image_id": 16,
  • "bot_id": 18,
  • "broadcast_text": "Hi, just wanted to wish you a Happy New Year from the World Bank",
  • "whatsapp_template": {
    },
  • "clicked_users": [
    ],
  • "id": 0,
  • "next_broadcast_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "scheduled_time": "2022-10-03 12:05:00",
  • "predicted_reach": 2302,
  • "actual_reach": 2514,
  • "limit": 100,
  • "limit_type": "default",
  • "opened": 0,
  • "target": [
    ],
  • "progress": 0,
  • "publish_when": "later",
  • "status": "UNPUBLISHED",
  • "timezone": "Asia/Singapore",
  • "loopback_target": [
    ],
  • "is_recurring": false,
  • "recurring_period": "week",
  • "prev_broadcast_id": 24,
  • "broadcast_object": "story",
  • "story_id": 12,
  • "card_id": 14,
  • "image_id": 16,
  • "bot_id": 18,
  • "broadcast_text": "Hi, just wanted to wish you a Happy New Year from the World Bank",
  • "whatsapp_template": {
    },
  • "clicked_users": [
    ],
  • "id": 0,
  • "next_broadcast_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get broadcast by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
required
number <double>

The ID of the bot this broadcast belongs to

broadcast_object
required
string
Default: "story"
Enum: "story" "text" "card" "image" "whatsapp_template"

What to broadcast

scheduled_time
required
string <date-time>

The timestamp when the broadcast will be published

loopback_target
required
object

Loopback filter defining the target subset of users to send the broadcast to. See https://loopback.io/doc/en/lb3/Where-filter.html for more details. You may test the list of users who will receive the broadcast with Search Users

predicted_reach
number <double>
Default: 0

(GENERATED) The total number of users predicted to receive the broadcast at the time it was created

actual_reach
number <double>
Default: 0

(GENERATED) The total number of users who actually received the broadcast at the time it was published

limit
number <double>

A ceiling to limit the number of users who will receive this broadcast

limit_type
string
Default: "default"
Enum: "default" "random"

If the limit is set, the selection strategy of the set of users who receive the broadcast

opened
number <double>
target
object

A filter that targets which subset of users will receive the broadcast. This object is optional and only used to display the target dropdown boxes on the BotDistrikt Platform UI. The required targeting object in a broadcast is called loopback_target.

progress
number <double>
publish_when
string
Default: "later"
Enum: "now" "later" "timewarp" "recurring"

The scheduling strategy of the broadcast

status
string
Default: "UNPUBLISHED"
Enum: "UNPUBLISHED" "RETRYING" "SCHEDULED" "RECURRING" "PUBLISHING" "FINISHED" "ERROR"

The current status of the broadcast

timezone
string

The timezone of the broadcast. Used to calculate the relative timezone offset of a user for Timewarp broadcasts. This will allow each user to receive the broadcast at the same time, irrespective of their timezone

is_recurring
boolean
Default: false

Whether or not the broadcast will be a recurring one

recurring_period
string
Enum: "hour" "day" "week" "month" "year"

For recurring broadcasts only. The time period interval at which recurring broadcasts are scheduled. For example, if a broadcast is scheduled for 2022-10-03 14:00:00 and set a recurring period of 1 week, as soon as the broadcast finishes publishing, it will automatically create another recurring broadcast scheduled at 2022-17-03 14:00:00. This will continuously proceed until a recurring broadcast is cancelled.

prev_broadcast_id
number <double>

For recurring broadcasts only. The ID of the next recurring broadcast that is created automatically by this one after this broadcast is FINISHED.

story_id
number <double>

For story broadcasts only. The ID of the story to broadcast to the targeted users

card_id
number <double>

For card broadcasts only. The ID of the card to broadcast to the targeted users

image_id
number <double>

For image broadcasts only. The ID of the image to broadcast to the targeted users

broadcast_text
string

For text broadcasts only. The text to broadcast to the targeted users

object

For WhatsApp Template broadcasts only. The WhatsApp Template name and parameters to broadcast.

clicked_users
object

(GENERATED) An array of unique IDs of bot users who clicked on links from this broadcast. This is used to quickly calculate the Click-Through Rate (CTR) of the broadcast

id
number <double>
next_broadcast_id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast was last updated.

Response samples

Content type
{
  • "scheduled_time": "2022-10-03 12:05:00",
  • "predicted_reach": 2302,
  • "actual_reach": 2514,
  • "limit": 100,
  • "limit_type": "default",
  • "opened": 0,
  • "target": [
    ],
  • "progress": 0,
  • "publish_when": "later",
  • "status": "UNPUBLISHED",
  • "timezone": "Asia/Singapore",
  • "loopback_target": [
    ],
  • "is_recurring": false,
  • "recurring_period": "week",
  • "prev_broadcast_id": 24,
  • "broadcast_object": "story",
  • "story_id": 12,
  • "card_id": 14,
  • "image_id": 16,
  • "bot_id": 18,
  • "broadcast_text": "Hi, just wanted to wish you a Happy New Year from the World Bank",
  • "whatsapp_template": {
    },
  • "clicked_users": [
    ],
  • "id": 0,
  • "next_broadcast_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel a broadcast

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

List broadcast records

path Parameters
id
required
string <JSON>

broadcast id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this broadcast record belongs to

bot_user_id
number <double>

The ID of the user who received the broadcast

broadcast_id
number <double>

The ID of the broadcast that created this receipt

story_id
number <double>

The ID of the story that was broadcasted

status
string
Enum: "completed" "error"

The status of the broadcast record

message
string

If there was an error status, the error message returned with the broadcast record

responses_count
number <double>

The number of responses sent to a user from this broadcast. This can be used to filter dynamic broadcasts where users may or may not receive messages

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast_record was last updated.

Response samples

Content type
[
  • {
    }
]

Search broadcasts

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
required
number <double>

The ID of the bot this broadcast belongs to

broadcast_object
required
string
Default: "story"
Enum: "story" "text" "card" "image" "whatsapp_template"

What to broadcast

scheduled_time
required
string <date-time>

The timestamp when the broadcast will be published

loopback_target
required
object

Loopback filter defining the target subset of users to send the broadcast to. See https://loopback.io/doc/en/lb3/Where-filter.html for more details. You may test the list of users who will receive the broadcast with Search Users

predicted_reach
number <double>
Default: 0

(GENERATED) The total number of users predicted to receive the broadcast at the time it was created

actual_reach
number <double>
Default: 0

(GENERATED) The total number of users who actually received the broadcast at the time it was published

limit
number <double>

A ceiling to limit the number of users who will receive this broadcast

limit_type
string
Default: "default"
Enum: "default" "random"

If the limit is set, the selection strategy of the set of users who receive the broadcast

opened
number <double>
target
object

A filter that targets which subset of users will receive the broadcast. This object is optional and only used to display the target dropdown boxes on the BotDistrikt Platform UI. The required targeting object in a broadcast is called loopback_target.

progress
number <double>
publish_when
string
Default: "later"
Enum: "now" "later" "timewarp" "recurring"

The scheduling strategy of the broadcast

status
string
Default: "UNPUBLISHED"
Enum: "UNPUBLISHED" "RETRYING" "SCHEDULED" "RECURRING" "PUBLISHING" "FINISHED" "ERROR"

The current status of the broadcast

timezone
string

The timezone of the broadcast. Used to calculate the relative timezone offset of a user for Timewarp broadcasts. This will allow each user to receive the broadcast at the same time, irrespective of their timezone

is_recurring
boolean
Default: false

Whether or not the broadcast will be a recurring one

recurring_period
string
Enum: "hour" "day" "week" "month" "year"

For recurring broadcasts only. The time period interval at which recurring broadcasts are scheduled. For example, if a broadcast is scheduled for 2022-10-03 14:00:00 and set a recurring period of 1 week, as soon as the broadcast finishes publishing, it will automatically create another recurring broadcast scheduled at 2022-17-03 14:00:00. This will continuously proceed until a recurring broadcast is cancelled.

prev_broadcast_id
number <double>

For recurring broadcasts only. The ID of the next recurring broadcast that is created automatically by this one after this broadcast is FINISHED.

story_id
number <double>

For story broadcasts only. The ID of the story to broadcast to the targeted users

card_id
number <double>

For card broadcasts only. The ID of the card to broadcast to the targeted users

image_id
number <double>

For image broadcasts only. The ID of the image to broadcast to the targeted users

broadcast_text
string

For text broadcasts only. The text to broadcast to the targeted users

object

For WhatsApp Template broadcasts only. The WhatsApp Template name and parameters to broadcast.

clicked_users
object

(GENERATED) An array of unique IDs of bot users who clicked on links from this broadcast. This is used to quickly calculate the Click-Through Rate (CTR) of the broadcast

id
number <double>
next_broadcast_id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the broadcast was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the broadcast was last updated.

Response samples

Content type
[
  • {
    }
]

tag

A label that can be applied to users and many other models like cards and images. Tags are most important for the filtering webhooks. Tags are also very important for the has tags function which can be used in rule conditions. The has tags function reads both tags and synonyms. Tags can also be used for targeting in rules and broadcasts with tags_string contains/has keyword (tag name). Tags can also be used by live agents to organize their users.

Create a new tag

Request Body schema:

Model instance data

bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "type": "user",
  • "name": "premium",
  • "description": "Premium content for exclusive users",
  • "synonyms_string": "string",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "type": "user",
  • "name": "premium",
  • "description": "Premium content for exclusive users",
  • "synonyms_string": "string",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get tag by ID

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Response samples

Content type
{
  • "bot_id": 12,
  • "type": "user",
  • "name": "premium",
  • "description": "Premium content for exclusive users",
  • "synonyms_string": "string",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a tag

path Parameters
id
required
string <JSON>

Model id

Responses

Response Schema:
object

Response samples

Content type
{ }

Update a tag

path Parameters
id
required
string <JSON>

tag id

Request Body schema:

An object of model property name/value pairs

bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Responses

Response Schema:
bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Request samples

Content type
{
  • "bot_id": 12,
  • "type": "user",
  • "name": "premium",
  • "description": "Premium content for exclusive users",
  • "synonyms_string": "string",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "bot_id": 12,
  • "type": "user",
  • "name": "premium",
  • "description": "Premium content for exclusive users",
  • "synonyms_string": "string",
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Search tags

path Parameters
id
required
string <JSON>

bot id

query Parameters
filter
string <JSON>

Filter defining fields, where, include, order, offset, and limit - must be a JSON-encoded string ({"where":{"something":"value"}}). See https://loopback.io/doc/en/lb3/Querying-data.html#using-stringified-json-in-rest-queries for more details.

Responses

Response Schema:
Array
bot_id
number <double>

The ID of the bot this tag belongs to

type
string
Enum: "user" "card" "document" "image" "text" "audio" "video"

The type of the tag. All types use the model name like card and image, except user which represents the model bot_user

name
string

The name of the tag

description
string

A description of the tag

synonyms_string
string

A comma-separated list of synonyms for the tags. If a synonym is picked up with a filtering webhook, the tag names are used to pick the model to respond with. For example, if we have a card tag called premium, with 2 synonym exclusive and pro, if pro is sent to the card filtering webhook, all cards tagged premium will be returned.

id
number <double>
created_at
string <date-time>

(GENERATED) The datetime at which the tag was created.

updated_at
string <date-time>

(GENERATED) The datetime at which the tag was last updated.

Response samples

Content type
[
  • {
    }
]