AI Agents Widget Escalation API Webhook

The Widget Escalation webhook receives the following event types related to escalated conversations:

• widgetEscalate: An escalation request from a widget customer to your CRM.
• widgetMessage: A message from the customer to the human agent during an escalated conversation. (widget bots only.)
• widgetEndSession: A request to end an escalated session. (widget bots only.)

Note: In the template project, the webhook endpoint is /converse-webhook, but this can be customized in your implementation.

Example webhook handler (TypeScript)

/**
 * Processes incoming webhook events from the Widget Escalation API.
 * @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);
  }
};

Event details and payloads

widgetEscalate event

This event occurs when the bot triggers an escalation to a human agent and the bot is using AI Agents 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. For more information, see Handling widget escalations.

The ConverseWebhookService in the template project is where you process this type of event. After receiving the event, your application is responsible for handling the rest of the workflow, such as checking agent availability, adding the customer to a queue, or performing any other necessary actions.

/**
     * 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;
        }
    }
}

Payload

Field	Type	Required	Description
botId	string	Yes	The ID of the bot sending the event
data.eventType	string	Yes	Set to widgetEscalate
data.platformConversationId	string	Yes	The conversation id (external)
data.conversationId	string	Yes	Ultimate internal conversation id (can be ignored)
data.escalateTo	string	No	CRM escalation team id (optional)

Example:

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

Response

• 200 OK (success, no response body)
• 4XX–5XX (failure)

widgetMessage event

This event occurs when a customer using the Ultimate Chat Widget sends a message to an agent during an escalated conversation. When your application receives this event, it should display the message to the agent. For more details, see the article on Widget escalations.

In the template project, this event is handled by ConverseWebhookService. After receiving the event, your application should process the message as needed, such as forwarding it directly 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;
        }
    }
}

Payload

Field	Type	Required	Description
botId	string	Yes	The id of the bot sending the event
data.eventType	string	Yes	"widgetMessage"
data.platformConversationId	string	Yes	The conversation id (external)
data.conversationId	string	Yes	Ultimate internal conversation id (can be ignored)
data.text	string	Yes	The message text

Example:

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

Response

• 200 OK (success, no response body)
• 4XX–5XX (failure)

widgetEndSession event

This event is triggered when a customer using the Ultimate Chat Widget explicitly ends an escalated conversation. When your application receives this event, it should end the connection with the agent and close the conversation. For more information, see the article on Widget escalations.

In the template project, this event is handled by ConverseWebhookService. After receiving the event, your application should perform any necessary follow-up actions, such as disconnecting 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;
        }
    }
}

Payload

Field	Type	Required	Description
botId	string	Yes	The id of the bot sending the event
data.eventType	string	Yes	"widgetEndSession"
data.platformConversationId	string	Yes	The conversation id (external)
data.conversationId	string	Yes	Ultimate internal conversation id (can be ignored)

Example:

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

Response

• 200 OK (success, no response body)
• 4XX–5XX (failure)