Log in
Automate your customer service. Sign up free
API Version

You're browsing the legacy version of the API documentation. Switch to the latest stable version →

Interactions

Interactions are the key components of every story. They anticipate the user input and determine the bot’s behavior. You decide what happens in each interaction and how your bot is going to act.

List all story interactions

Returns list of all interactions created in a provided story.

GET https://api.chatbot.com/stories/:storyID/interactions

Request URL

curl --request GET \
	--url https://api.chatbot.com/stories/:storyID/interactions \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

Response example

[
    {
        "id": "5a5f552a698d030007483263",
        "name": "Name of your interaction",
        "action": "",
        "classifier": "ml",
        "userSays": [
            "Hello"
        ],
        "triggers": [],
        "parameters": [],
        "responses": [
            {
                "type": "text",
                "elements": [
                    "Hi! 😃 How are you?"
                ],
                "filters": []
            }
        ]
    }
]

Properties

Property Type Description
id String Interaction id.
name String Interaction name.
action String Action name.
classifier String Type of matching classifier.
userSays Array.<String> Array of messages which are used to recognize the interaction.
triggers Array.<String> Array of strings which allows you to invoke the interaction instead of a user query.
parameters Array.<Object> An array of parameters objects.
responses Array.<Object> An array of responses objects.

Get a single interaction

Returns single interaction object for the given id.

GET https://api.chatbot.com/stories/:storyID/interactions/:ID

Request URL

curl --request GET \
	--url https://api.chatbot.com/stories/:storyID/interactions/:ID \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'

Response example

{
    "id": "5a5f552a698d030007483263",
    "name": "Interaction name",
    "action": "",
    "classifier": "ml",
    "userSays": [
        "Hello",
        "Hi",
        "Welcome"
    ],
    "triggers": [],
    "parameters": [],
    "responses": [
        {
            "type": "text",
            "elements": [
                "Hi! How are you?"
            ],
            "filters": []
        }
    ]
}

Properties

Property Type Description
id String Interaction id.
name String Interaction name.
action String Action name.
classifier String Type of matching classifier.

Check supported values.
userSays Array.<String> Array of messages which are used to recognize the interaction
triggers Array.<String> Array of strings which allows you to invoke the interaction instead of a user query.
parameters Array.<Object> An array of parameters objects.
responses Array.<Object> An array of responses objects.

Add a root interaction

Creates a new root interaction.

POST https://api.chatbot.com/stories/:storyID/interactions

Request URL

curl --request POST \
	--url https://api.chatbot.com/stories/:storyID/interactions \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    {
        name: "Interaction",
        userSays: [
            "Hello",
            "Hi"
        ],
        responses: [
            {
                type: "text",
                elements: ["Hi, how are you", "Hello! What can I do for you?"]
            }
        ]
    }
'

Response example

{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

Properties

Property Type Description
name String Interaction name.

String(1, 1024)
action String Optional. Action name.

String(1, 1024)
classifier String Optional. Type of matching classifier.

Check supported values.
userSays Array.<String> Optional. Array of messages which are used to recognize the interaction.

Array(1, 256).String(1, 256)
triggers Array.<String> Optional. Array of strings which allows you to invoke the interaction by a trigger name instead of a user query.

Array(1, 1024).String(1, 50)
parameters Array.<Object> Optional. An array of parameters objects.

Array(1, 99)
responses Array.<Object> Optional. An array of responses objects.

Array(1, 10)

Add a child interaction

Creates a new child interaction.

POST https://api.chatbot.com/stories/:storyID/interactions/:ID

Request URL

curl --request POST \
	--url https://api.chatbot.com/stories/:storyID/interactions/:ID \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    {
        name: "Interaction",
        userSays: [
            "Hello",
            "Hi"
        ],
        responses: [
            {
                type: "text",
                elements: ["Hi, how are you", "Hello! What can I do for you?"]
            }
        ]
    }
'

Response example

{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

Properties

Property Type Description
name String Interaction name.

String(1, 1024)
action String Optional. Action name.

String(1, 1024)
classifier String Optional. Type of matching classifier.

Check supported values.
userSays Array.<String> Optional. Array of messages which are used to recognize the interaction.

Array(1, 256).String(1, 256)
triggers Array.<String> Optional. Array of strings which allows you to invoke the interaction by a trigger name instead of a user query.

Array(1, 1024).String(1, 50)
parameters Array.<Object> Optional. An array of parameters objects.

Array(1, 99)
responses Array.<Object> Optional. An array of responses objects.

Array(1, 10)

Update a interaction

Updates the specified interaction.

PUT https://api.chatbot.com/stories/:storyID/interactions/:ID

Request URL

curl --request PUT \
	--url https://api.chatbot.com/stories/:storyID/interactions/:ID \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    {
        name: "Interaction",
        userSays: [
            "Hello",
            "Hi"
        ],
        responses: [
            {
                type: "text",
                elements: ["Hi, how are you", "Hello! What can I do for you?"]
            }
        ]
    }
'

Properties

Property Type Description
name String Interaction name.

String(1, 1024)
action String Optional. Action name.

String(1, 1024)
classifier String Optional. Type of matching classifier.

Check supported values.
userSays Array.<String> Optional. Array of messages which are used to recognize the interaction.

Array(1, 256).String(1, 256)
triggers Array.<String> Optional. Array of strings which allows you to invoke the interaction by a trigger name instead of a user query.

Array(1, 1024).String(1, 50)
parameters Array.<Object> Optional. An array of parameters objects.

Array(1, 99)
responses Array.<Object> Optional. An array of responses objects.

Array(1, 10)

Delete a interaction

Removes a provided interactions.

DELETE https://api.chatbot.com/stories/:storyID/interactions

Request URL

curl --request DELETE \
	--url https://api.chatbot.com/stories/:storyID/interactions \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    [
        "585bbaf5ecea28f52a899f3b",
        "585bbafaecea28f52a899f3c"
    ]
'

Response example

{
    "timestamp": "2018-01-12T13:40:40.260Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

Common object definitions

classifier

Matching system for interaction. Check supported values here.

parameters

Property Type Description
entity String Name of system or user entity.

String(1, 128)
alias String Name of attribute.

String(1, 128)
prompts Array.<String> Optional. Questions for attribute.

Array (1, 99).String(1, 128)

responses

Go to object definition.

Possible response definitions:

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

Free 14-day trial No credit card required

Discover our text| products

LiveChat
Connect with customers

HelpDesk
Support customers with tickets

KnowledgeBase
Guide and educate customers

OpenWidget
Enhance websites with widgets