Handling widget escalations with the Widget Escalation API

This article explains how to manage agent escalations in your custom application using the Widget Escalations API.

How escalation works

When a conversation with a customer requires escalation to a human agent, the API sends a widgetEscalate event to your configured webhook. At this point, your application must initiate the escalation process and manage the connection with an agent. The chat widget will also be notified and will begin listening for status updates during the escalation flow.

Sending escalation event updates

After escalation is triggered, your application is responsible for resolving the escalation and sending updates or agent messages to the visitor. Use the Send Escalation Events to a Widget endpoint to send agent events to the widget. The following event types are supported:

• escalationQueueUpdate: The visitor is waiting in a queue for an available human agent. Use this event to share queue position and/or estimated wait time information.
• escalationSuccess: The visitor is successfully connected to a human agent. Use this event to share details such as the agent’s name and avatar. Two-way messaging is enabled from this point.
• message: Send a text message from the agent to the visitor via the widget. Only supported after an escalationSuccess event.
• escalationFailed: The escalation attempt was unsuccessful and no agent could be connected.
• agentDisconnect: The agent has ended the escalated conversation.

Event payload examples

Escalation queue update

When a visitor is waiting in a queue for a human agent, send an escalationQueueUpdate event to the API webhook. This event provides status updates about the visitor's place in the queue.

The request body should include:

• eventType: Set to "escalationQueueUpdate"
• platformConversationId: The unique ID of the conversation
• queuePosition: (optional) The visitor’s current position in the queue
• waitingTime: (optional) The estimated wait time, in minutes, before the visitor will be connected with an agent

{
  "eventType": "escalationQueueUpdate",
  "platformConversationId": "123456789",
  "queuePosition": "3",
  "waitingTime": "12"
}

Escalation success

When a human agent connects with the visitor, the agent sends an escalationSuccess event to the API webhook. This event marks the conversation as escalated, allowing messages to be exchanged between the visitor and the human agent.

The request body should include:

• eventType: Set to "escalationSuccess"
• platformConversationId: The unique ID of the conversation
• agent: (optional) The agent’s name to display in the chat widget

{
  "eventType": "escalationSuccess",
  "platformConversationId": "123456789",
  "agent": "John Smith"
}

Message

Once an escalation is active, send messages to the visitor by triggering a message event to the API webhook. The request body should include:

• eventType: Set to "message"
• platformConversationId: The unique ID of the conversation
• text: The message content to send to the customer

{
  "eventType": "message",
  "platformConversationId": "123456789",
  "text": "Hello, I'm John, your agent. Let me help you with your issue."
}

Escalation failed

If the escalation process fails, send an escalationFailed event to the API webhook. The request body should include:

• eventType: Set to "escalationFailed"
• platformConversationId: The unique ID of the conversation

{
  "eventType": "escalationFailed",
  "platformConversationId": "123456789"
}

Agent disconnect

When the agent ends the escalated conversation, send an agentDisconnect event to the API webhook. The request body should include:

• eventType: Set to "agentDisconnect"
• platformConversationId: The unique ID of the conversation

{
  "eventType": "agentDisconnect",
  "platformConversationId": "123456789"
}