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 →

Stories

A story is a conversation scenario between customers and the bot. You can design the bot to do things like receiving pizza orders or scheduling doctor appointments or whatever you want.

List all stories

Returns list of all stories.

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

Request URL

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

Response Example

[
    {
        "id": "58ee11d75fb5580005cb8199",
        "name": "Example name",
        "description": "Example description",
        "integrations": [],
        "metrics": [
            {
                date: "2018-01-16",
                conversations: 15
            },
            [...]
        ]
    }
]

Properties

Property Type Description
id String Story id.
name String Story name.
description String Story description.
integrations Array.<String> An array of element strings that describes which integrations story is connected with.
metrics Array.<object> An array of element objects that includes weekly metrics for the story.

integrations

A string array that describes which integrations story is connected with. Possible values: livechat, messenger, slack, widget.

metrics

Property Type Description
date String Day.
conversations Number The number of conversations.

Get a single story

Returns single story for the given id.

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

Request URL

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

Response Example

{
    "id": "58ee11d75fb5580005cb8199",
    "name": "Example story name",
    "description": "Example story description",
    "order": [
        "58ee2d045d033800059a3f7e"
    ],
    "interactions": {
        "58ee2d045d033800059a3f7e": {
            "name": "parent",
            "root": true,
            "references": [],
            "contextOut": [
                "58ee2d105fb5580005cb81aa"
            ],
            "webhook": "",
            "id": "58ee2d045d033800059a3f7e"
        },
        "58ee2d105fb5580005cb81aa": {
            "name": "child",
            "root": false,
            "references": [],
            "contextOut": [],
            "webhook": "",
            "id": "58ee2d105fb5580005cb81aa"
        }
    }
}

Properties

Property Type Description
id String Story id.
name String Story name.
description String Story description.
order Array.<String> A string array that states the interactions order at the first story tree level. This order is considered while searching and matching interactions.
interactions Object An object includes all interactions created in the story.

Add a new story

Create a new story:

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

Request URL

curl --request POST \
	--url https://api.chatbot.com/stories \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    {
      "name": "Story name",
      "description": "Story description"
    }
'

Response Example

{
    "id": "58ee2e085d033800059a3f7f",
    "timestamp": "2017-04-12T13:39:20.721Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

Properties

Property Type Description
name String Story name.

String(1, 1024)
description String Optional. Story description.

String(0, 2048)

Update a story

Update story with the given id.

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

Request URL

curl --request PUT \
	--url https://api.chatbot.com/stories/:ID \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json' \
	--data '
    {
      "name": "Story name",
      "description": "Story description"
    }
'

Response Example

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

Properties

Property Type Description
name String Story name.

String(1, 1024)
description String Optional. Story description.

String(0, 2048)

Delete a story

Removes a story with the given id.

DELETE https://api.chatbot.com/stories/:ID

Request URL

curl --request DELETE \
	--url https://api.chatbot.com/stories/:ID \
	--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
	--header 'content-type: application/json'

Response Example

{
    "timestamp": "2017-04-12T13:41:47.020Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

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

Free 14-day trial No credit card required

Discover our text| products