CSML Studio
  • Introduction
  • 🦜Getting started
    • Create Your First Bot
    • The Dashboard
    • AI & Natural Language Processing
      • AI Rules
      • Configuring a NLU Provider
    • Apps and Integrations
      • Authoring Custom Apps
      • CSML Integrations
      • Tools and utilities
      • Preprocessing
    • Livechat
      • Chatwoot
    • Bot Configuration Options
    • Authenticating Users
    • 💻CSML Language Reference
  • 🔌Studio API
    • Getting Started
    • Authentication
    • Studio CLI
    • API Reference
      • Chat API
      • Broadcasts API
      • Bot API
      • Conversations API
  • 📱Channels
    • Introduction
    • Assistant
      • Installation
      • Configuration
      • Customization
      • Widget
      • Message Formats
    • Workplace Chat
      • Installation
      • Uninstallation
      • Configuration
      • Features and message formats
    • Microsoft Teams
      • Installation
      • Features
    • Google Chat
      • Installation
      • Features
    • WhatsApp
      • Installation
      • Features and Limitations
    • Telegram
      • Installation
      • Features
    • SMS (with Twilio)
      • Installation
      • Features and Limitations
    • Slack
      • Installation
      • Message formats
      • Features
    • Callbots (with Twilio)
      • Installation
      • Features and Limitations
    • Amazon Alexa
      • Installation
    • Google Assistant
      • Installation
    • Messenger (legacy)
      • Installation
      • Configuration
      • Features
      • Message formats
    • Instagram (legacy)
      • Installation
      • Configuration
      • Features
    • Webapp (legacy)
      • Installation
      • Configuration
      • Customization
      • Chatbox
      • Message Formats
Powered by GitBook
On this page
  • POST /chat
  • Request body
  • Response body

Was this helpful?

Export as PDF
  1. Studio API
  2. API Reference

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.

# 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"
            }
          }'

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:

{
  "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.

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

{
  "client": {
    "user_id": "some-user-id"
  },
  "metadata": {
    "key": "value",
    "otherkey": "othervalue"
  },
  "request_id": "random-id",
  "payload": {
    "content": {
      "text": "Hello"
    },
    "content_type": "text"
  }
}

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

{
  "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"
}
PreviousAPI ReferenceNextBroadcasts API

Last updated 3 years ago

Was this helpful?

see

🔌
message payload definitions