Build your bot using ChatBot API

API Version

Object definitions

Available responses

Text response

Returns a normal text response

Property Type Description
type String text
elements Array.<String> The array of objects. The maximum size of the response array is 99 objects.

Array (1, 20).String(1, 1024)
filters Array.<Object> Optional. Filters for response.

Array (1, 10)

Example JSON

{
    "responses": [
        {
            "type": "text",
            "elements": ["Hi, how are you", "Hello!"],
            "filters": []
        }
    ]
}

Image response

Returns an image response

Property Type Description
type String image
imageUrl String Image url, must be valid URL.

String(1, 1024)
filters Array.<Object> Optional. Filters for response.

Array (1, 10)

Example JSON

{
    "responses": [
        {
            "type": "image",
            "imageUrl": "your-image-url",
            "filters": []
        }
    ]
}

Quick replies

Returns a quick replies response

Property Type Description
type String quickReplies
title String Title for quick reply response.

String(1, 640)
buttons Array.<Object> An array of element objects that suggests possible responses.

Type(postback, goto)
Array(1, 11)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "quickReplies",
            "title": "Lorem ipsum dolor sit amet.",
            "filters": [],
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

Card response

Returns single card response

Property Type Description
type String card
title String Title for card response.

String(1, 80)
subtitle String Optional. Title for card response.

String(0, 80)
imageUrl String Optional. Image for card response.

String(0, 2048)
buttons Array.<Object> An array of element objects.

Array(1, 3)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "card",
            "filters": [],
            "title": "Lorem ipsum dolor sit amet.",
            "subtitle": "qui dolorem ipsum quia dolor sit amet,",
            "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

Returns multiple cards response

Property Type Description
type String Card
elements String Array of Card elements.

Array(1, 10)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Card

Property Type Description
title String Title for card response.

String(1, 80)
subtitle String Optional. Title for card response.

String(0, 80)
imageUrl String Optional. Image for card response.

String(0, 2048)
buttons Array.<Object> An array of element objects.

Array(1, 3)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "cards",
            "filters": [],
            "elements": [
                {
                    "title": "Lorem ipsum dolor sit amet.",
                    "subtitle": "qui dolorem ipsum quia dolor sit amet,",
                    "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
                    "buttons": [
                        {
                            "type": "postback",
                            "title": "Lorem ipsum dolor sit.",
                            "value": "first_message"
                        }
                    ]
                },
                {
                    "title": "Qui dolorem ipsum quia dolor sit amet.",
                    "subtitle": "lorem ipsum dolor sit amet.",
                    "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
                    "buttons": [
                        {
                            "type": "postback",
                            "title": "Ipsum quia dolor.",
                            "value": "second_message"
                        }
                    ]
                }
            ]
        }
    ]
}

Button response

Returns button response

Property Type Description
type String button
title String Title for button response.

String(1, 640)
buttons Array.<Object> An array of element objects.

Array(1, 3)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "button",
            "title": "Lorem ipsum dolor sit amet.",
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

End response

This response is visible only in debug mode

Property Type Description
type String end
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "end",
            "filters": []
        }
    ]
}

Reset response

Triggers the “reset context” action as a response

Property Type Description
type String reset
filters Filter[0,10] Optional. Filters for response.

Array(1, 10)

Example JSON

{
  "responses": [
    {
      "type": "reset",
      "filters": []
    }
  ]
}

Webhook response

Triggers a webhook as a response

Property Type Description
type String webhook
webhookId String Must be valid webhook id.

String(24)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "webhook",
            "webhookId": "507f1f77bcf86cd799439011",
            "filters": []
        }
    ]
}

Go to response

Redirects the customer to the target interaction

Property Type Description
type String goto
interactionId String Must be valid interaction id.

String(24)
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
    "responses": [
        {
            "type": "goto",
            "interactionId": "507f191e810c19729de860ea",
            "filters": []
        }
    ]
}

Ask a question (attributes) response

Triggers “Ask a question” action

Property Type Description
type String attributes
filters Array.<Object> Optional. Filters for response.

Array(1, 10)
delay Number(100,5000) Delay in milliseconds
elements <Attribute>(1,10) Array(1,10)

Example JSON

{
  "responses": [
    {
      "type": "attributes",
      "filters": [],
      "delay": 2000,
      "elements": [
        {
          "entity": "foo",
          "alias": "bar",
          "lifespan": 2,
          "required": true,
          "actionOnFailure": "fallback",
          "askWhenFilled": true,
          "prompts": [
            "what is foo?"
          ]
        }
      ]
    }
  ]
}

Set Attributes response

Set a new value to the attribute

Property Type Description
type String setAttributes
filters Array.<Object> Optional. Filters for response.

Array(1, 10)
elements <Parameter>(1,10)\ Array(1,10)

Example JSON

{
  "responses": [
    {
      "type": "setAttributes",
      "filters": [],
      "elements": [
        {
          "name": "foo",
          "action": "set",
          "value": "bar"
        },
        {
          "name": "empty",
          "action": "set",
          "value": ""
        },
        {
          "name": "name-with-dash",
          "action": "set",
          "value": "value"
        },
        {
          "name": "bar",
          "action": "remove"
        }
      ]
    }
  ]
}

Backtracking response

Enables/disables backtracking as a response

Property Type Description
type String backtracking
filters Array.<Object> Optional. Filters for response.

Array(1, 10)

Example JSON

{
  "responses": [
    {
      "type": "backtracking",
      "filters": []
    }
  ]
}

Buttons

Postback button

Returns a postback when clicked

Property Type Description
type String postback
title String Button title.

String(1, 20)
value String Postback value.

String(1, 1000)

Hint: If you want all buttons to have the same name, use the postback field to give each of them a unique name. It will help ChatBot to distinguish which button has been clicked.

GoTo button

Triggers “Go to…” interaction when clicked

Property Type Description
type String goto
title String Button title.

String(1, 20)
value String Interaction ID.

String(1, 24)

URL button

Opens up the URL when clicked

Property Type Description
type String url
title String Button title.

String(1, 20)
value String Valid URL.

String(1, 2048)

Phone button

Dials a number when clicked

Property Type Description
type String phone
title String Button title.

String(1, 20)
value String Valid phone number. Remember to put + at the beginning of the phone number.

String(3, 16)

Fulfillment

Text fulfillment

Returns text fulfillment

Property Type Description
type String text
message String Response

String(1, 1024)

Example JSON

{
    "fulfillment": [
        {
            "type": "text",
            "message": "Hi, how are you"
        }
    ]
}

Image fulfillment

Returns image fulfillment

Property Type Description
type String image
imageUrl String Image url

String(1, 1024)

Example JSON

{
    "fulfillment": [
        {
            "type": "image",
            "imageUrl": "https://i.imgur.com/3yPwOLC.jpg"
        }
    ]
}

Quick replies fulfillment

Returns Quick Replies fulfillment

Property Type Description
type String quickReplies
title String Title for quick reply.

String(1, 640)
buttons Array.<Object> Quick replies buttons.

Example JSON

{
    "fulfillment": [
        {
            "type": "quickReplies",
            "title": "Lorem ipsum dolor sit amet.",
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

Card fulfillment

Returns a single card fulfillment

Property Type Description
type String card
title String Title for card response.

String(1, 80)
subtitle String Optional. Title for card response.

String(0, 80)
imageUrl String Optional. Image for card response.

String(0, 2048)
buttons Array.<Object> An array of element objects.

Array(1, 3)

Example JSON

{
    "fulfillment": [
        {
            "type": "card",
            "title": "Lorem ipsum dolor sit amet.",
            "subtitle": "qui dolorem ipsum quia dolor sit amet,",
            "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

Returns multiple cards fulfillment

Property Type Description
type String Card
elements String Array of Card elements.

Array(1, 10)

Card

Property Type Description
title String Title for card response.

String(1, 80)
subtitle String Optional. Title for card response.

String(0, 80)
imageUrl String Optional. Image for card response.

String(0, 2048)
buttons Array.<Object> An array of element objects.

Array(1, 3)

Example JSON

{
    "fulfillment": [
        {
            "type": "cards",
            "filters": [],
            "elements": [
                {
                    "title": "Lorem ipsum dolor sit amet.",
                    "subtitle": "qui dolorem ipsum quia dolor sit amet,",
                    "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
                    "buttons": [
                        {
                            "type": "postback",
                            "title": "Lorem ipsum dolor sit.",
                            "value": "first_message"
                        }
                    ]
                },
                {
                    "title": "Qui dolorem ipsum quia dolor sit amet.",
                    "subtitle": "lorem ipsum dolor sit amet.",
                    "imageUrl": "https://i.imgur.com/3yPwOLC.jpg",
                    "buttons": [
                        {
                            "type": "postback",
                            "title": "Ipsum quia dolor.",
                            "value": "second_message"
                        }
                    ]
                }
            ]
        }
    ]
}

Button fulfillment

Returns a single button fulfillment

Property Type Description
type String button
title String Title for button response.

String(1, 640)
buttons Array.<Object> An array of element objects.

Array(1, 3)

Example JSON

{
    "fulfillment": [
        {
            "type": "button",
            "title": "Lorem ipsum dolor sit amet.",
            "buttons": [
                {
                    "type": "postback",
                    "title": "Lorem ipsum dolor sit.",
                    "value": "developer_message"
                }
            ]
        }
    ]
}

End fulfillment

This response is visible only in debug mode

Property Type Description
type String end
used Boolean Set to true if the response was used

Example JSON

{
    "fulfillment": [
        {
            "type": "end",
            "used": true
        }
    ]
}

Reset fulfillment

This response is visible only in debug mode

Property Type Description
type String reset
debug Boolean Set to true if debug mode is on
used Boolean Set to true if the response was used

Example JSON

{
    "fulfillment": [
        {
        "reset": "end",
        "used": true,
        "debug": true
        }
    ]
}

Webhook fulfillment

This response is visible only in debug mode

Property Type Description
type String webhook
webhookId String Webhook id.

String(24)
error String Error message
used Boolean Set to true if the webhook was triggered correctly

Example JSON

{
    "fulfillment": [
        {
            "type": "webhook",
            "webhookId": "507f1f77bcf86cd799439011",
            "used": false,
            "error": "foo.example.com’s server DNS address could not be found."
        }
    ]
}

Go to fulfillment

This response is visible only in debug mode

Property Type Description
type String goto
interactionId String Interaction id.

String(24)
used Boolean Set to true if response was used

Example JSON

{
  "fulfillment": [
    {
      "type": "goto",
      "interactionId": "507f191e810c19729de860ea",
      "used": true,
      "debug": true
    }
  ]
}

Set Attributes fulfillment

This response is visible only in debug mode

Property Type Description
type String setAttributes
debug Boolean Set to true if debug mode is on
elements <Parameter>(1,10) Array(1,10)

Example JSON

{
  "fulfillment": [
    {
      "type": "setAttributes",
      "debug": true,
      "elements": [
        {
          "name": "foo",
          "action": "set",
          "value": "bar"
        },
        {
          "name": "empty",
          "action": "set",
          "value": ""
        },
        {
          "name": "name-with-dash",
          "action": "set",
          "value": "value"
        },
        {
          "name": "bar",
          "action": "remove"
        }
      ]
    }
  ]
}

Backtracking fulfillment

This response is visible only in debug mode

Property Type Description
type String backtracking
searchInRoot Boolean True/False
debug Boolean Set to true if debug mode is on

Example JSON

{
  "fulfillment": [
    {
      "type": "backtracking",
      "debug": true
    }
  ]
}

Filters

Attribute filter

parameter type
type String(attribute)
alias String(1, 128)
rule StringRule, NumericRule
value String(1,1024), Number, Boolean

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "is",
          "value": "my-value"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Lifespan filter

parameter type
type String(lifespan)
rule NumericRule
value Number(0,10)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "lifespan",
          "rule": "is",
          "value": 0
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Score filter

parameter type
type String(score)
rule NumericRule
value Float(0,1) (up to 2 precision)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "score",
          "rule": "is",
          "value": 0.2
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Incomplete filter

parameter type
type String(incomplete)
rule IsRule
value Boolean

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "incomplete",
          "rule": "is",
          "value": false
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Resolved Query filter

parameter type
type String(resolvedQuery)
rule StringRule
value String(1,1024), Boolean

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "resolvedQuery",
          "rule": "is",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Trigger filter

parameter type
type String(trigger)
rule StringRule
value String(1,1024), Boolean

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "is",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Rules

Numeric rules

String rules

Is rule

parameter type
rule String(is)
value String(1,1024)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "is",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Is not rule

parameter type
rule String(isNot)
value String(1,1024)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "isNot",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Empty rule

parameter type
rule String(empty)
value Boolean

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "empty",
          "value": false
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Contains rule

parameter type
rule String(contains)
value String(1,1024)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "contains",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Not contains rule

parameter type
rule String(notContains)
value String(1,1024)

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "trigger",
          "rule": "notContains",
          "value": "welcome"
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Greater rule

parameter type
rule String(greater)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "greater",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Less rule

parameter type
rule String(less)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "less",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Greater or equal rule

parameter type
rule String(greaterOrEqual)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "greaterOrEqual",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Less or equal rule

parameter type
rule String(lessOrEqual)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "lessOrEqual",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Longer rule

parameter type
rule String(longer)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "longer",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Shorter rule

parameter type
rule String(shorter)
value Number

Example JSON

{
  "responses": [
    {
      "type": "text",
      "filters": [
        {
          "type": "attribute",
          "alias": "my-param",
          "rule": "shorter",
          "value": 1337
        }
      ],
      "elements": ["hi", "hello"]
    }
  ]
}

Result

Property Type Description
source String Source of your conversation.

Possible values: custom, livechat, slack, messenger
resolvedQuery String Your message.
trigger String Name of executed trigger.
status String Status object for your request.
confidence Number Current confidence for your conversation session.
lifespan Number Current lifespan for your conversation session.
score Number Accuracy of matching.
incomplete Boolean It is true if any of the required parameters are not filled.
storyId String Your bot story id.
interaction Object The interaction object that was called.
parameters Object Parameters object which showing all the attributes collected in the current conversation.
contexts Array.<Object> Array of objects which contains the entire conversation path in the form of successively triggered interactions.
fulfillment Array.<Object> Array of objects which includes all of bot responses.

Start a free ChatBot trial
and build your first chatbot today!

Free 14-day trial No credit card required

Discover our other products