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
*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
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
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.