The Chat API allows you to send chat requests to your bot on behalf of an end user. You can send a text request, and receive the bot's response in return.
This API works synchronously by default: you will receive all of the bot's messages in one array in response to your request.
You can query the Chat API by sending a simple text message for analysis. This will either continue any previous conversation or start a new one.
# replace the x-api-key and x-api-signature values with your data
curl -X "POST" "https://clients.csml.dev/v1/api/chat" \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-api-key: ${API_KEY}' \
-d $'{
"client": {
"user_id": "some-user-id"
},
"metadata": {
"firstname": "John",
"lastname": "Doe"
},
"request_id": "random-id",
"payload": {
"content": {
"text": "Hello"
},
"content_type": "text"
}
}'The following message types are accepted (see below for payload examples): text, image, video, audio, file, url, payload, flow_trigger.
Additional properties can be added to the message's content and will be available as event.my_added_prop in the context of the CSML.
To trigger a specific flow, you can send the following event:
{
"client": {
"user_id": "some-user-id"
},
"metadata": {
"key": "value",
"otherkey": "othervalue"
},
"request_id": "random-id",
"payload": {
"content": {
"flow_id": "some-flow-id",
"close_flows": true
},
"content_type": "flow_trigger"
}
}You can also choose to force-close any previously open conversation with close_flows. If you don't close previous conversations and the flow is a recursive flow (i.e has no hold keywords), then the previous conversation will be relaunched at the last available step in that flow.
Name
Type
Description
*metadata
object
Key-value pairs of metadata to inject into the conversation
request_id
string
A random client-issued string for tracing requests. If none is provided, will be automatically generated.
*payload.content_type
string
*payload.content
object
*client
object
*client.user_id
string
the user's unique identifier
{
"client": {
"user_id": "some-user-id"
},
"metadata": {
"key": "value",
"otherkey": "othervalue"
},
"request_id": "random-id",
"payload": {
"content": {
"text": "Hello"
},
"content_type": "text"
}
}Name
Type
Description
request_id
string
A random client-issued string for tracing requests. If none is provided, will be automatically generated
conversation_end
boolean
Whether the flow ends after this message
*messages
array
All the messages to send to the client in order
*message.payload
object
See Message payloads below
*client
object
*client.bot_id
string
the bot's ID
*client.channel_id
string
the channels's ID
*client.user_id
string
the user's unique identifier
*received_at
string
UTC time at which the message was received by the CSML server
{
"request_id": "045338c4-f214-4f94-b1a7-3255b3d70f3c",
"messages": [
{
"conversation_id": "f2461d23-6069-4f78-ae81-f127e4c3d9a0",
"direction": "SEND",
"interaction_order": 0,
"payload": {
"content": {
"text": "Some message"
},
"content_type": "text"
}
}
],
"client": {
"bot_id": "b797a3b6-ad8c-446c-acfe-dfcafd787f4e",
"channel_id": "dd446008-3768-41df-9be9-f6ea0371f920",
"user_id": "some-user-id"
},
"received_at": "2019-11-16T17:48:26.519Z"
}A broadcast is a message sent proactively from the bot to a user, without the user sending a request first. It is a great way to reengage your users, for example to remind them about a conversation they didn't finish, or let them know a product they ordered has been shipped.
Send a broadcast on the requested channel (supported channels only) to the requested client. Broadcast requests are queued and usually sent within a few seconds. If a target is unavailable, no error is generated.
curl "https://clients.csml.dev/v1/api/broadcasts" \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-api-key: ${X-API-KEY}' \
-d $'{
"payload": {
"content": {
"flow_id": "myflow"
},
"content_type": "flow_trigger"
},
"client": {
"user_id": "some-user-id"
},
"metadata": {
"somekey": "somevalue"
}
}'
{
"request_id": "57d2d4ab-6994-4449-82bf-206619d9d063",
"client": {
"user_id": "some-user-id",
"bot_id": "bc5de819-e4c5-463e-9090-5648fac3a570",
"channel_id": "b1f74f8d-99b6-40b2-ad64-00ec364bae23"
},
"payload": {
"content_type": "flow_trigger",
"content": {
"flow_id": "myflow",
"close_flows": true
}
},
"metadata": {
"somekey": "somevalue"
}
}The Bot API allows you to retrieve information about your bot and its flows
GET https://clients.csml.dev/v1/api/bot
Retrieve the bot for this integration
{
"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",
"env": {
"MY_VAR": "somevalue"
},
"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 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.
env
object
key/value hash of bot environment variables
default_flow
string
ID of default flow to set (flow must exist)
description
string
name
string
{
"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 https://clients.csml.dev/v1/api/bot/flows
Retrieve all the flows in the current bot
[
{
"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 https://clients.csml.dev/v1/api/bot/flows
Add a new flow to the current bot
description
string
Description of the flow to create
commands
array
Commands that will trigger the flow. Example: ["some", "command"]
content
string
CSML Flow
name
string
Name of the flow
{
"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 https://clients/csml.dev/v1/api/bot/flows/:flow_id
flow_id
string
{
"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 https://clients/csml.dev/v1/api/bot/flows/:flow_id
flow_id
string
commands
array
content
string
description
string
{
"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 https://clients.csml.dev/v1/api/bot/usage
Get usage information about a bot
{
"currentmonth": {
"messages": 0,
"clients": 0
},
"last30d": {
"messages": 0,
"clients": 0
},
"lastmonth": {
"messages": 0,
"clients": 0
}
}POST https://clients.csml.dev/v1/api/bot/validate
Validate bot data against the CSML interpreter
object
The bot object as retrieved from the GET /bot operation
// bot is valid
{
"valid": true
}
// bot is invalid
{
"valid": false,
"errors": [
{
"flow": "someFlow",
"step": "someStep",
"line": 0,
"column": 0,
"message": "error message"
}
]
}POST https://clients.csml.dev/v1/api/bot/build
Build a new version of the bot
{
"id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"name": "test",
"default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"created_at": "2020-08-23T17:47:21.229Z",
"version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
"engine_version": "1.4.0",
"flows": [
{
"id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"name": "Default",
"commands": [
"/default"
],
"content": "start:\n say \"Hello\"\n goto end",
}
]
}GET https://clients.csml.dev/v1/api/bot/build
version_id
string
ID of version to retrieve. Defaults to `latest` if not set.
{
"id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
"name": "test",
"default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"created_at": "2020-08-23T17:47:21.229Z",
"version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
"engine_version": "1.4.0",
"flows": [
{
"id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
"name": "Default",
"commands": [
"/default"
],
"content": "start:\n say \"Hello\"\n goto end",
}
]
}With the Conversations API, you can manage your client's conversation statuses
Find out whether a user currently has an open conversation on the current channel.
curl -X "POST" "https://clients.csml.dev/v1/api/conversations/open" \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-api-key: ${X-API-KEY}' \
-H 'x-api-signature: ${X-API-SIGNATURE}' \
-d $'{
"user_id": "some-user-id"
}'{
"has_open": true,
"conversation": {
"id": "43d5939f-4afc-4953-9e53-4c28b33cedd8",
"client": {
"channel_id": "dd446008-3768-41df-9be9-f6ea0371f920",
"user_id": "some-user-id",
"bot_id": "b797a3b6-ad8c-446c-acfe-dfcafd787f4e"
},
"flow_id": "31c2c4b0-05d6-44ce-9442-e87e9ae7e8a2",
"step_id": "start",
"metadata": {
"somekey": "somevalue",
},
"status": "OPEN",
"last_interaction_at": "2019-11-16T19:57:42.219Z",
"created_at": "2019-11-16T19:57:42.219Z"
}
}