Webhooks

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

Why use Webhooks

Ultimate Widget Escalation API leverages webhooks to connect the clients using Ultimate Chat Widget with your human agents.

Widget Escalation API Webhook events

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

  1. widgetEscalate - An escalation request from a widget customer to the CRM.
  2. widgetMessage - A message from the customer to the human agent in the scope of an escalated conversation. For Widget Bots only.
  3. widgetEndSession - A request to end an escalated session. For Widget Bots only.

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);
        }
    };
}

widgetEscalate event

This event happens when the bot triggers an escalation to a human agent and the bot is using Ultimate Chat Widget. When this event is received, the bot stops sending messages to the visitor. At this point conversations have to be handled in your application. See this article for more information on Widget escalations

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.WIDGET_ESCALATE:
                /**
                 * This event represents an escalation request from the bot for customers who are using Ultimate Chat Widget
                 *
                 * The payload of this event is represented in the BotWidgetMessageEvent class.
                 *
                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_ESCALATE} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }
}

The widgetEscalate message structure:

FieldTypeRequiredDescription
botIdstringtrueThe ID of the bot that is sending the event.
dataObjecttrueObject containing the payload of the event. Depending on the event type, it will contain different values
FieldTypeDescription
eventTypestring
Set to widgetEscalate		Event of type escalate.
platformConversationIdstringThe ID of the conversation
conversationIdstringULTIMATE internal ID (can be ignored)
escalateTo?stringThe ID of the escalation team within the CRM system (OPTIONAL)

Example in JSON format:

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

The response structure:

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

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

widgetMessage event

This event is used when customers using an Ultimate Chat Widget want to send messages to an agent within the scope of an escalated conversation. When this event is received the message should be shown to the agent. See this article for more information on Widget escalations

In our template project, this type of event can be processed in ConverseWebhookService. From here, it’s up to your application to execute logic on the message that it has received from the bot like directly forwarding it to a human agent.

/**
     * This method processes the Converse Webhook event.
     * @param converseWebhookDto
     */
    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.WIDGET_MESSAGE:
                /**
                 * This event represents a message request from the user to an agent in an escalated conversation for customers that are using Ultimate Chat Widget
                 *
                 * The payload of this event is represented in the BotWidgetEscalateEvent class.
                 *
                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_MESSAGE} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }
}

The widgetMessage message structure:

FieldTypeRequiredDescription
botIdstringtrueThe ID of the bot that is sending the event.
dataObjecttrueObject containing the payload of the event. Depending on the event type, it will contain different values
FieldTypeDescription
eventTypestring
Set to widgetMessage		Event of type sendMessage.
platformConversationIdstringThe ID of the conversation
conversationIdstringULTIMATE internal ID (Can be ignored)
textstringThe text of the message.

Example in JSON format:

{
  "botId": "BOT_ID",
  "data": {
    "eventType": "widgetMessage",
    "platformConversationId": "13427e90-f76a-47c2-a26d-ea0b4f1836c5",
    "conversationId": "CONVERSATION_ID",
    "text": "Hello, this is a customer message in an escalated conversation"
  }
}

The response structure:

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

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

widgetEndSession event

This event happens when a customer using a Ultimate Chat Widget explicitly finishes an escalated conversation. When this event is received, the ongoing connection with the agent should be stopped, and the conversation should be closed. See this article for more information on Widget escalations

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 like disconnecting with the human agent.

/**
     * This method processes the Converse Webhook event.
     * @param converseWebhookDto
     */
    public processConverseWebhookEvent(converseWebhookDto: ConverseWebhookDto): void {
        switch (converseWebhookDto.data.eventType) {
            case ConverseWebhookEventTypes.WIDGET_END_SESSION:
                /**
                 * This event represents an end escalated session request from the user to an agent in an escalated conversation
                 * for customers that are using Ultimate Chat Widget
                 *
                 * The payload of this event is represented in the BotWidgetEndSessionEvent class.
                 *
                 * The request will be acknowledged and then processed ASYNCHRONOUSLY.
                 */
                logger.info(
                    `Received ${ConverseWebhookEventTypes.WIDGET_END_SESSION} event: \n ${JSON.stringify(
                        converseWebhookDto
                    )}`
                );
                break;
            default:
                break;
        }
    }
}

The escalate message structure:

FieldTypeRequiredDescription
botIdstringtrueThe ID of the bot that is sending the event.
dataObjecttrueObject containing the payload of the event. Depending on the event type, it will contain different values
FieldTypeDescription
eventTypestring
Set to widgetEndSession		Event of type escalate.
platformConversationIdstringThe ID of the conversation
conversationIdstringULTIMATE internal ID (can be ignored)

Example in JSON format:

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

The response structure:

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

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