Bot API

The Bot API allows you to retrieve information about your bot and its flows

get
Get bot

https://clients.csml.dev/v1/api/bot
Retrieve the bot for this integration
Request
Response
Request
Response
200: OK
{
"id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "MyBot",
"description": "This is my bot",
"default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
"created_at": "2019-12-11T18:59:39.391Z",
"updated_at": "2019-12-13T01:27:38.653Z",
"flows": [
{
"id": "fd2e74e5-1305-4650-a300-8097d71df01f",
"bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n\tsay \"hello!\"\n\tgoto end",
"created_at": "2019-12-11T18:59:39.610Z",
"updated_at": "2019-12-13T01:31:51.507Z",
},
...
]
}

put
Update bot

https://clients.csml.dev/v1/api/bot
Update a bot's name, default_flow and/or description. Parameters that are not set will not be changed.
Request
Response
Request
Body Parameters
default_flow
optional
string
ID of default flow to set (flow must exist)
description
optional
string
name
optional
string
Response
200: OK
{
"id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "MyBot",
"description": "This is my bot",
"default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
"created_at": "2019-12-11T18:59:39.391Z",
"updated_at": "2019-12-13T01:27:38.653Z",
"flows": [
{
"id": "fd2e74e5-1305-4650-a300-8097d71df01f",
"bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n\tsay \"hello!\"\n\tgoto end",
"created_at": "2019-12-11T18:59:39.610Z",
"updated_at": "2019-12-13T01:31:51.507Z",
},
...
]
}

get
Get bot flows

https://clients.csml.dev/v1/api/bot/flows
Retrieve all the flows in the current bot
Request
Response
Request
Response
200: OK
[
{
"id": "fd2e74e5-1305-4650-a300-8097d71df01f",
"bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n\tsay \"hello!\"\n\tgoto end",
"created_at": "2019-12-11T18:59:39.610Z",
"updated_at": "2019-12-13T01:31:51.507Z",
},
...
]

post
Create Flow

https://clients.csml.dev/v1/api/bot/flows
Add a new flow to the current bot
Request
Response
Request
Body Parameters
description
optional
string
Description of the flow to create
commands
optional
array
Commands that will trigger the flow. Example: ["some", "command"]
content
required
string
CSML Flow
name
required
string
Name of the flow
Response
200: OK
{
"id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "SomeFlow",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"commands": [
"/someflow",
"some command"
],
"content": "start:\n say \"Hi!\"\n goto end",
"created_at": "2020-08-23T17:54:39.461Z",
"updated_at": "2020-08-23T17:54:39.461Z"
}

get
Get flow

https://clients/csml.dev/v1/api/bot/flows/:flow_id
Request
Response
Request
Path Parameters
flow_id
required
string
Response
200: OK
{
"id": "fd2e74e5-1305-4650-a300-8097d71df01f",
"bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n\tsay \"hello!\"\n\tgoto end",
"created_at": "2019-12-11T18:59:39.610Z",
"updated_at": "2019-12-13T01:31:51.507Z",
}

put
Update flow

https://clients/csml.dev/v1/api/bot/flows/:flow_id
Request
Response
Request
Path Parameters
flow_id
required
string
Body Parameters
commands
optional
array
content
required
string
description
optional
string
Response
204: No Content
{
"id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "SomeFlow",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"commands": [
"/someflow",
"some command"
],
"content": "start:\n say \"Hi!\"\n goto end",
"created_at": "2020-08-23T17:54:39.461Z",
"updated_at": "2020-08-23T17:54:39.461Z"
}

get
Bot usage

https://clients.csml.dev/v1/api/bot/usage
Get usage information about a bot
Request
Response
Request
Response
200: OK
{
"currentmonth": {
"messages": 0,
"clients": 0
},
"last30d": {
"messages": 0,
"clients": 0
},
"lastmonth": {
"messages": 0,
"clients": 0
}
}

post
Validate bot

https://clients.csml.dev/v1/api/bot/validate
Validate bot data against the CSML interpreter
Request
Response
Request
Path Parameters
bot
optional
object
a bot object as returned from the GET /bot operation
Response
200: OK
// bot is valid
{
"valid": true
}
// bot is invalid
{
"valid": false,
"errors": [
{
"flow": "someFlow",
"step": "someStep",
"line": 0,
"column": 0,
"message": "error message"
}
]
}

post
Build bot

https://clients.csml.dev/v1/api/bot/build
Build a new version of the bot
Request
Response
Request
Response
200: OK
{
"id": "38f0cde0-20ed-4082-b42b-e79b164394d9",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"data": {
"id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "test",
"default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"flows": [
{
"id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n say \"Hello\"\n goto end",
"created_at": "2020-08-23T14:05:27.011Z",
"updated_at": "2020-08-23T14:05:27.011Z"
}
]
},
"created_at": "2020-08-23T17:47:21.229Z"
}

get
Get bot build version

https://clients.csml.dev/v1/api/bot/build
Request
Response
Request
Query Parameters
version_id
optional
string
ID of version to retrieve. Defaults to `latest` if not set.
Response
200: OK
{
"id": "38f0cde0-20ed-4082-b42b-e79b164394d9",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"data": {
"id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "test",
"default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"flows": [
{
"id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
"name": "Default",
"description": "Default custom flow",
"commands": [
"/default"
],
"content": "start:\n say \"Hello\"\n goto end",
"created_at": "2020-08-23T14:05:27.011Z",
"updated_at": "2020-08-23T14:05:27.011Z"
}
]
},
"created_at": "2020-08-23T17:47:21.229Z"
}