Webhooks

This article covers webhooks, their expected body request and responses.

Why use Webhooks

Ultimate Chat API leverages webhooks to enhance performance and make conversations more responsive.

Our Chat API responds with an empty 200 response to indicate that the request has been acknowledged and will be handled. The actual bot response will be sent as a separate webhook request.

The main reason behind using this approach is to allow the bot to be proactive in sending messages without needing a visitor message as a first input. A use case can be the following: in the event of a conversation started without any first message from the user after a certain time, the bot sends a message asking if the conversation can be closed.

Another reason is that we can send consecutive bot messages as they happen without needing to group them together.

Chat API Webhook events

The Chat API webhook will receive events related to bot conversations. The events that will be received are:

sendMessage - A message from the bot to the visitor.
escalate - An escalation request from the bot to your application.
isTeamOnline - An escalation dependent on the availability of human agents.

In our template project, This webhook is documented in our template project under the url /converse-webhook. Please note that the implementation in your application can be different.

Here is an example implementation using Typescript:

/**
     * This method processes the Converse Webhook. Receives a DTO of type ConverseWebhookDto with the event details
     *
     * It will process the request differently depending on the eventType field of the payload.
     *
     * @param req
     * @param res
     * @param next
     */
    public processEvent = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
        const requestBody: ConverseWebhookDto = req.body;

        try {
            this.converseWebhookService.processConverseWebhookEvent(requestBody);
            res.status(200).send();
        } catch (error: any) {
            next(error);
        }
    };
}

sendMessage event

This is the most common event that would be sent to your application. It is a message from the bot to the visitor. It can be a simple text message but also a carousel of cards or a list of buttons. The event should be acknowledged and processed ASYNCHRONOUSLY.

In our template project, the ConverseWebhookService is where we can process this type of event. From here, it’s up to your application to execute logic on the message that it has received from the bot. It can directly forward it to the customer or process it beforehand, if needed.

/**
     * This method processes the Converse Webhook event.
     * @param converseWebhookDto
     */
    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.SEND_MESSAGE:
                /**
                 * This event represents a message sent from the bot.
                 * It can represent a text message, a list of buttons or a carousel.
                 *
                 * The payload of this event is represented in the BotMessageEvent class.
                 *
                 * The request needs to be acknowledged and processed ASYNCHRONOUSLY.
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.SEND_MESSAGE} event: \n ${JSON.stringify(converseWebhookDto)}`
                );
                break;
            default:
                break;
        }
    }
}

Text message

The text message structure:

Field	Type	Required	Description
botId	string	true	The ID of the bot that is sending the event.
data	Object	true	Object containing the payload of the event. Depending on the event type, it will contain different values

The data object will contain the following fields:

Field	Type	Description
eventType	string Set to `sendMessage`	Event of type sendMessage.
platformConversationId	string	The ID of the conversation
conversationId	string	ULTIMATE internal ID (Can be ignored)
type	string Set to `text`	Simple text message type.
replyId	string	The ID of the reply in Ultimate system that triggered this text message.
text	string	The text of the message.
predictedIntents	PredictedIntent[]	Predicted intents for visitor message. Each object of type `PredictedIntent` in the array needs to contain the following fields: value `string` - the ID of the intent in Ultimate system name `string` - name of the intent confidence `number` - confidence in the intent

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [],
    "text": "Hello, this is a bot text message",
    "carouselCards": [],
    "predictedIntents": [{"value": "1234", "name": "intent name", "confidence": 1}]
  }
}

List of buttons message

The list of buttons message structure:

Field	Type	Required	Description
botId	string	true	The ID of the bot that is sending the event.
data	Object	true	Object containing the payload of the event. Depending on the event type, it will contain different values

The data object will contain the following fields:

Field	Type	Description
eventType	string Set to `sendMessage`	Event of type sendMessage.
platformConversationId	string	The ID of the conversation
conversationId	string	ULTIMATE internal ID (can be ignored)
type	string Set to `text`	Simple text message type.
replyId	string	The ID of the reply in Ultimate system that triggered this text message.
buttons	Button[]	The buttons array will be empty for a simple text message. Each object of type `Button` in the array needs to contain the following fields: type `string` - set to the value `button` text `string` - text of the button
text	string	The text of the message with buttons. Not mandatory to exist.
predictedIntents	PredictedIntent[]	Predicted intents for visitor message. Each object of type `PredictedIntent` in the array needs to contain the following fields: value `string` - the ID of the intent in Ultimate system name `string` - name of the intent confidence `number` - confidence in the intent

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "text",
    "replyId": "REPLY_ID",
    "buttons": [
      {
        "type": "button",
        "text": "YES"
      },
      {
        "type": "button",
        "text": "NO"
      }
    ],
    "text": "its a bot text message with 2 buttons",
    "carouselCards": [],
    "predictedIntents": [{"value": "1234", "name": "intent name", "confidence": 1}]
  }
}

Carousel message

The carousel message structure:

Field	Type	Required	Description
botId	string	true	The ID of the bot that is sending the event.
data	Object	true	Object containing the payload of the event. Depending on the event type, it will contain different values

The data object will contain the following fields:

Field	Type	Description
eventType	string Set to `sendMessage`	Event of type sendMessage.
platformConversationId	string	The ID of the conversation
conversationId	string	ULTIMATE internal ID (can be ignored)
type	string Set to `carousel`	Carousel message type.
replyId	string	The ID of the reply in Ultimate system that triggered this text message.
text	string	The text of the message with buttons. Not mandatory to exist.
carouselCards	CarouselCard[]	The carousel cards array will contain a list of cards. See table below with the fields of `CarouselCards`
predictedIntents	PredictedIntent[]	Predicted intents for visitor message. Each object of type `PredictedIntent` in the array needs to contain the following fields: value `string` - the intent id name `string` - name of the intent confidence `number` - confidence in the intent

Each object of type CarouselCard in the array needs to contain the following fields:

Field	Type	Description
title	string	Title of the carousel.
description	string	Event of type sendMessage
imageUrl	string	Url of the card image.
buttons	Button[]	Each object of type `Button` in the array needs to contain the following fields: type `string` - set to the value `button` text `string` - text of the button

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "sendMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "type": "carousel",
    "replyId": "REPLY_ID",
    "buttons": [],
    "text": "",
    "carouselCards": [
      {
        "title": "card 1",
        "description": "card 1 description",
        "imageUrl": "URL",
        "buttons": [
          {
            "text": "button 1",
            "type": "button"
          },
          {
            "text": "button 2",
            "type": "button"
          }
        ]
      },
      {
        "title": "card 2",
        "description": "card 2 description",
        "imageUrl": "URL",
        "buttons": [
          {
            "text": "button 1",
            "type": "button"
          },
          {
            "text": "button 2",
            "type": "button"
          }
        ]
      }
    ],
    "predictedIntents": [{"value": "1234", "name": "intent name", "confidence": 1}]
  }
}

The response structure:

A successful sendMessage will return a 200 response to the webhook request and no response body.

A failed sendMessage will return a 4XX - 5XX range response to the webhook request.

escalate event

This event happens when the bot triggers an escalation to a human agent. When this event is received, the bot stops sending messages to the visitor, At this point conversations have to be handled in your application.

The ConverseWebhookService in our template project is where we process this type of event. From there, any other action has to happen in your application whether it is about checking for agents availability, adding the customer to a queue or any other logic that is relevant to your application.

/**
     * This method processes the Converse Webhook event.
     * @param converseWebhookDto
     */
    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.ESCALATE:
                /**
                 * This event represents an escalation request from the bot.
                 *
                 * The payload of this event is represented in the BotEscalationEvent class.
                 *
                 * The request will be processed SYNCHRONOUSLY and respond if the escalation was successful (200) or not (4xx-5xx).
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.ESCALATE} event: \n ${JSON.stringify(converseWebhookDto)}`
                );
                break;
            default:
                break;
        }
    }
}

The escalate message structure:

Field	Type	Required	Description
botId	string	true	The ID of the bot that is sending the event.
data	Object	true	Object containing the payload of the event. Depending on the event type, it will contain different values

The data object will contain the following fields:

Field	Type	Description
eventType	string Set to `escalate`	Event of type escalate.
platformConversationId	string	The ID of the conversation
conversationId	string	ULTIMATE internal ID (can be ignored)
escalateTo?	string	The ID of the escalation team within the CRM system (OPTIONAL)

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "escalate",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "escalateTo": "string"
  }
}

The response structure:

A successful escalation returns a 200 response to the webhook request and no response body.

A failed escalation returns a 4XX - 5XX range response to the webhook request.

isTeamOnline event

This event will happen when the bot needs to know if there is an agent team available. When this event is received, the request needs to be handled SYNCHRONOUSLY and respond if the team is available with boolean field isOnline set to true or false.

The ConverseWebhookService in our template project is where this event is processed. From here, it’s up to your application to implement its logic internally, like checking specific agent or group of agents availability

/**
     * This method processes the Converse Webhook event.
     * @param converseWebhookDto
     */
    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.IS_TEAM_ONLINE:
                /**
                 * This event happens when the bot needs to make decisions that are dependent on the availability of human agents
                 *
                 * The payload of this event is represented in the BotIsTeamOnlineEvent class.
                 *
                 * The user will process the request and respond if there is availability or not using the class BotIsTeamOnlineEventResponse.
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.IS_TEAM_ONLINE} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }
}

The escalate message structure:

Field	Type	Required	Description
botId	string	true	The ID of the bot that is sending the event.
data	Object	true	Object containing the payload of the event. Depending on the event type, it will contain different values

The data object will contain the following fields:

Field	Type	Description
eventType	string Set to `isTeamOnline`	Event of type isTeamOnline.
conversationId	string	ULTIMATE internal ID (can be ignored)
teamId?	string	The ID of the team to check (OPTIONAL)

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "isTeamOnline",
    "teamId": "string"
  }
}

The response structure:

Field	Type	Required	Description
isOnline	boolean	true	Returns true if the team is online and false in other case

{
  "isOnline": true
}

Action Webhook

For action webhook, refer to this article