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",
  • "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",
  • "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",
  • "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