Sending messages from the visitor to the bot with the AI Agents Chat API

You can send messages from a visitor to your bot using the Chat API. When you send a message to the Converse with a Bot endpoint, the API immediately acknowledges the request with a 200 OK status and processes the message asynchronously. The bot’s response is sent to the webhook endpoint you’ve configured in your Custom CRM settings.

Note: Every request to the Chat API must include your botId and API key in the headers, as outlined in the API specification.

Generating the platformConversationId

Each conversation is uniquely identified by the platformConversationId parameter, which must be included in every request to the Chat API. You are responsible for generating this ID; it should be unique per conversation. We recommend using a UUID generator for this purpose. Learn more about generating UUIDs in Node.js.

Supported event types

The /converse/chat endpoint accepts the following event types in the eventType field:

• startSession: Starts a new conversation and triggers the bot’s welcome message, if configured.
• message: Represents a message sent from the visitor to the bot.
• endSession: Explicitly ends the conversation.
• metadata: Adds metadata to the conversation session.

startSession event

Use the startSession event to trigger the bot’s welcome reply (if enabled) when starting a new conversation. This event is optional: if you do not send a startSession event, the conversation will begin automatically when the first message event is received.

Example request:

{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "startSession"
}

message event

The message event is the most commonly used event type. It can represent several types of user actions:

• Text message: A plain text message, e.g., “I want to make a refund of an article.”
• Clicking a button: The visitor selects a button from a set presented by the bot.
• Selecting a card from a carousel: The visitor makes a choice from a carousel of cards sent by the bot.

Text message

The text message is the most common type of message and is simply a plain text message. It is represented by the following JSON object:

{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "message",
  "text": "I want to make a refund of an article"
}

Clicking a button

When the visitor clicks a button (e.g., “Maybe”), send a message event with the button text:

{
    "botId": "BOT_ID",
    "data": {
        "type": "text",
        "replyId": "SOME_REPLY_ID",
        "buttons": [
            {
                "type": "button",
                "text": "Yes"
            },
            {
                "type": "button",
                "text": "No"
            },
            {
                "type": "button",
                "text": "Maybe"
            }
        ],
        "text": "This is a text message sent with the buttons",
        "carouselCards": [],
        "eventType": "sendMessage",
        "platformConversationId": "00000001"
    }
}

If a visitor clicks one of the buttons, such as "Maybe", the request should include the button text ("Maybe") in its text field. The request to the Chat API will look like this:

{
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "eventType": "message",
    "text": "Maybe"
}

Selecting a card from a carousel

When the visitor chooses a button from a card in a carousel, also include the card’s index:

{
    "botId": "BOT_ID",
    "data": {
        "type": "carousel",
        "replyId": "SOME_REPLY_ID",
        "buttons": [],
        "text": "",
        "carouselCards": [
            {
                "description": "description of first card",
                "imageUrl": "IMAGE_1_URL",
                "title": "title Card 1",
                "buttons": [
                    {
                        "type": "button",
                        "text": "firstCardButton"
                    }
                ]
            },
            {
                "description": "description of second card",
                "imageUrl": "IMAGE_2_URL",
                "title": "title Card 2",
                "buttons": [
                    {
                        "type": "button",
                        "text": "secondCardButton"
                    }
                ]
            }
        ],
        "eventType": "sendMessage",
        "platformConversationId": "00000001"
    }
}

For a carousel, when a visitor clicks a button on a card, such as the "secondCardButton" on the second card, the request should include the button text ("secondCardButton") in the text field and add the cardIndex parameter to indicate which card was selected. In this example, cardIndex would be 1, since indexing starts at 0. The resulting request to the Chat API looks like:

{
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "eventType": "message",
    "text": "secondCardButton",
    "cardIndex": 1
}

endSession event

Use the endSession event to explicitly end a conversation. This is optional; if not called, the session will end automatically after a timeout defined in your bot’s settings.

Example request:

{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "endSession"
}

metadata event

Use the metadata event to add details to the conversation session. This event does not interact with the bot, but stores the provided data for use in session flows or dialog personalization.

Example request:

{
  "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
  "eventType": "metadata",
  "metadata": [
    {
      "key": "user_id",
      "value": "1234"
    },
    {
      "key": "user_name",
      "value": "john"
    }
  ]
}

This saves two parameters, user_id and user_name to the conversation session, where they can be used to manage session actions or control dialogs.

The metadata field can also be included in the message and startSession events, which is the recommended approach rather than sending a separate metadata event.

Implementation help

The template project provides a simple client implementation for the Chat API. The ChatApiClient class’s converseWithBot method can be used to send any supported event:

/**
 * Sends a message to the Chat API.
 * Supported event types: 'startSession', 'message', 'endSession', 'metadata'
 */
public async converseWithBot(requestBody: ConverseWithBotRequestDto): Promise<any | null> {
  // Example only: ensure API key security in production!
  const token = 'API_KEY';
  const url = '/converse/chat';
  const headers = {
    headers: {
      Authorization: token
    }
  };
  let response = await axios.post(`${process.env.CHAT_API}${url}`, requestBody, headers);
  logger.info(`API acknowledged the message with status code: ${response.status}`);
  return response;
}

The request object, also called a Data Transfer Object (DTO), defines all the fields required for sending events to the API. The DTO ensures your requests are structured correctly and include all necessary properties for a successful API call.

enum ChatApiEventTypes {
  START_SESSION = "startSession",
  MESSAGE = "message",
  END_SESSION = "endSession",
  METADATA = "metadata"
}

export class ConverseWithBotRequestDto {
  public platformConversationId: string
  public eventType: ChatApiEventTypes
  public text?: string
  public cardIndex?: number
  public metaData?: MetaData[]
}

You can integrate this client with your application’s chat logic and customize it to fit your use case.