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.
Broadcasts are only available on the PRO plan. More information on the CSML Studio plans: https://www.csml.dev/studio/pricing
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.
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.
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:
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.
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
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.
GET
https://clients.csml.dev/v1/api/bot/flows
Retrieve all the flows in the current bot
POST
https://clients.csml.dev/v1/api/bot/flows
Add a new flow to the current bot
GET
https://clients/csml.dev/v1/api/bot/flows/:flow_id
PUT
https://clients/csml.dev/v1/api/bot/flows/:flow_id
GET
https://clients.csml.dev/v1/api/bot/usage
Get usage information about a bot
POST
https://clients.csml.dev/v1/api/bot/validate
Validate bot data against the CSML interpreter
POST
https://clients.csml.dev/v1/api/bot/build
Build a new version of the bot
GET
https://clients.csml.dev/v1/api/bot/build
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
request_id |
| A random client-issued string for tracing requests. If none is provided, will be automatically generated |
conversation_end |
| Whether the flow ends after this message |
*messages |
| All the messages to send to the client in order |
*message.payload |
| See |
*client |
|
*client.bot_id |
| the bot's ID |
*client.channel_id |
| the channels's ID |
*client.user_id |
| the user's unique identifier |
*received_at |
| UTC time at which the message was received by the CSML server |
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 |
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 |
flow_id | string |
flow_id | string |
commands | array |
content | string |
description | string |
object | The bot object as retrieved from the GET /bot operation |
version_id | string | ID of version to retrieve. Defaults to `latest` if not set. |
Name | Type | Description |
*metadata |
| Key-value pairs of metadata to inject into the conversation |
request_id |
| A random client-issued string for tracing requests. If none is provided, will be automatically generated. |
*payload |
|
*payload.content_type |
|
*payload.content |
|
*client |
|
*client.user_id |
| the user's unique identifier |
see