How to send messages from the visitor to the bot

Sending messages from the visitor to the bot

This is done by calling the Chat API endpoint. The Chat API will acknowledge the message with a 200 OK and will process it asynchronously. Any response from the bot will be sent to the webhook that has been configured in the bot Custom CRM settings.

This tutorial assumes that calls to Ultimate Chat API include the botId and the API key in the headers of the request as defined in its specification.

Generate the platformConversationId

The clients of Ultimate’s Chat API are responsible for generating the ID that will identify the conversation. This is a parameter called platformConversationId and it needs to be part of the payload of every request to the Chat API. The platformConversationId is a unique identifier of the conversation between the visitor and the bot.

Type of events

The chat converse endpoint accepts following types of events:

  1. startSession - Starts a new conversation triggering first the welcome message of the bot if it exists.
  2. message - Represents a text message from the visitor to the bot. Will start a new conversation if it is the first message of it.
  3. endSession - Explicitly ends conversation.
  4. metadata - Adds metadata to the conversation session.

Start Session Event

The purpose of this event is to trigger the Bot welcome reply (if it exists and is active) when starting a new conversation. Is an optional operation

If no startSession event is sent, the conversation will be created when the first visitor message is received.

The startSession event is represented by the following JSON object:

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

Message Event

The message event is the most commonly used event type, it represents a message from the visitor to the bot. The supported types of messages that can be sent to the bot are:

  1. Text message - A simple text message from the visitor to the bot. (i.e. ‘I want to make a refund of an article’)
  2. Clicking a button - When the bot sends to the visitor a list of buttons, the visitor can click on one of them and the bot will receive it.
  3. Selecting a card from a carousel - When the bot sends to the visitor a carousel of cards, the visitor can click on one of them and the bot will receive it.
Text message

The text message is the most common type of message as it’s just 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 bot sends to the visitor a list of buttons, like in this example:

{
  "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 the visitor clicks one of the buttons (i.e., last button ‘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"
}

When the bot sends to the visitor a carousel of cards, like in this example:

{
  "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 the visitor clicks the button of card (ie the button ‘secondCardButton’ of the second card), the text field of the request needs to include the button text (‘secondCardButton’), and the parameter cardIndex must also be included in the request (in this case with value 1, as card indexes start in 0). The request to the Chat API will be:

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

End Session Event

The purpose of this event is to explicitly end a conversation. It Is an optional operation, as there is a timeout (defined in the bot settings) that will automatically end it.

The endSession event is represented by the following JSON object:

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

Metadata Event

The purpose of this event is to add metadata to the conversation session. It doesn’t interact with the bot. A request example is:

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

It will save two parameters to the conversation session (user_id and user_name). The parameters can be used to drive actions or dialogs.

Metadata field can also be sent in the message and starSession events, and it is recommended to be used with these events instead of the metadata event.

Implementation help

The template project has a simple client of Ultimate Chat API in the class ChatApiClient and DTO definition for it:

Client:

/**
 * This method is used to send a message to the Chat API.
 * The event types that can be sent are: 'startSession', 'message', 'endSession' or 'metadata'.
 * @param requestBody
 */
public async converseWithBot(requestBody: ConverseWithBotRequestDto): Promise<any | null> {
    /**
     * This code has to be used as an example to implement the Chat API client
     * API key security has to be implemented to protect the API
     * To get the API key, please contact the Ultimate team
     */
    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;
}

DTO:

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


export class ConverseWithBotRequestDto {
    @IsNotEmpty()
    @IsString()
    public platformConversationId: string;


    @IsEnum(ChatApiEventTypes)
    public eventType: ChatApiEventTypes;


    @IsOptional()
    @IsNotEmpty()
    @IsString()
    public text?: string;


    @IsOptional()
    @IsNumber()
    public cardIndex?: number;


    @IsOptional()
    @IsArray()
    @ValidateNested({ each: true })
    @Type(() => MetaData)
    public metaData?: MetaData[];
}

Depending on the needs, this client can be injected in the custom CRM chat logic, and used to send to the bot the messages that are received from the visitor. The logic of the application can be personalised to suit individual needs.