Chat API
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.

POST /chat

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.
1
# replace the x-api-key and x-api-signature values with your data
2
curl -X "POST" "https://clients.csml.dev/v1/api/chat" \
3
-H 'content-type: application/json' \
4
-H 'accept: application/json' \
5
-H 'x-api-key: ${API_KEY}' \
6
-d #x27;{
7
"client": {
8
"user_id": "some-user-id"
9
},
10
"metadata": {
11
"firstname": "John",
12
"lastname": "Doe"
13
},
14
"request_id": "random-id",
15
"payload": {
16
"content": {
17
"text": "Hello"
18
},
19
"content_type": "text"
20
}
21
}'
Copied!

Valid request message payloads

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.

Triggering a specific flow

To trigger a specific flow, you can send the following event:
1
{
2
"client": {
3
"user_id": "some-user-id"
4
},
5
"metadata": {
6
"key": "value",
7
"otherkey": "othervalue"
8
},
9
"request_id": "random-id",
10
"payload": {
11
"content": {
12
"flow_id": "some-flow-id",
13
"close_flows": true
14
},
15
"content_type": "flow_trigger"
16
}
17
}
Copied!
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.

Request body

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
object
*payload.content_type
string
*payload.content
object
*client
object
*client.user_id
string
the user's unique identifier
1
{
2
"client": {
3
"user_id": "some-user-id"
4
},
5
"metadata": {
6
"key": "value",
7
"otherkey": "othervalue"
8
},
9
"request_id": "random-id",
10
"payload": {
11
"content": {
12
"text": "Hello"
13
},
14
"content_type": "text"
15
}
16
}
Copied!

Response body

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
1
{
2
"request_id": "045338c4-f214-4f94-b1a7-3255b3d70f3c",
3
"messages": [
4
{
5
"conversation_id": "f2461d23-6069-4f78-ae81-f127e4c3d9a0",
6
"direction": "SEND",
7
"interaction_order": 0,
8
"payload": {
9
"content": {
10
"text": "Some message"
11
},
12
"content_type": "text"
13
}
14
}
15
],
16
"client": {
17
"bot_id": "b797a3b6-ad8c-446c-acfe-dfcafd787f4e",
18
"channel_id": "dd446008-3768-41df-9be9-f6ea0371f920",
19
"user_id": "some-user-id"
20
},
21
"received_at": "2019-11-16T17:48:26.519Z"
22
}
Copied!
Export as PDF
Copy link