How to handle widget escalations

This article goes through agent escalations for our Widget Escalations API when using a custom application.

How does it work

When a conversation with a customer needs an escalation to a human agent, the API sends a widgetEscalate event to the defined webhook. From there, the escalation process has to be initiated in your application. Our chat widget will be also notified of the escalation, and start listening for updates on the escalation process.

Escalation is triggered
Escalation is triggered

Your application then needs to resolve the escalation and start sending the human agent’s messages. The /agent/converse/send-message-to-widget API should receive agent events. The supported events in this webhook are:

  • escalationQueueUpdate: in the event of the visitor being in a queue for an available human agent, you can share a queue position and/or waiting time information.
  • escalationSuccess: in the event the visitor is connected with a human agent, you can provide the agent’s name and avatar. From this moment on, the visitor will be able to send messages to the agent and vice-versa.
  • message: If there is the need to send an agent’s message to the visitor’s widget. This can only be sent after the escalationSuccess event.
  • escalationFailed: In the event the escalation process failed, and the visitor couldn’t be connected with an agent.
  • agentDisconnect: In the event the agent ended the escalated conversation.

Escalation Queue Update

When the visitor is in a queue for an available human agent, the Agent can send escalationQueueUpdate event to our API webhook. This event can contain the following information:

The request body should contain the following information:

  • eventType: with the value escalationQueueUpdate
  • platformConversationId: the ID of the conversation
  • queuePosition: (OPTIONAL) the customer’s position in the queue
  • waitingTime: (OPTIONAL) the estimated waiting time for the customer to be connected with an agent, in minutes
{
  "eventType": "escalationQueueUpdate",
  "platformConversationId": "123456789",
  "queuePosition": "3",
  "waitingTime": "12"
}

Escalation Success

When the connection with a human agent is established, the Agent will send an escalationSuccess event to our API webhook. It marks the conversation as escalated and messages can be exchanged between the visitor and the human agent. This event should contain the following information:

  • eventType: with the value escalationSuccess
  • platformConversationId: the ID of the conversation
  • agent: (OPTIONAL) the agent’s name to show in the chat widget
{
  "eventType": "escalationSuccess",
  "platformConversationId": "123456789",
  "agent": "John Smith"
}

Message

When an escalation is established, the human agent will send messages to the visitor. For that, the agent will send a message event to our API webhook. This event should contain the following information:

  • eventType: with the value message
  • platformConversationId: the ID of the conversation
  • text: the text to be sent to the customer
{
  "eventType": "message",
  "platformConversationId": "123456789",
  "text": "Hello, I'm John, your agent, let me help you with your issue"
}

Escalation Failed

When the escalation process fails, the human agent can send an escalationFailed event to our API webhook. This event should contain the following information:

  • eventType: with the value escalationFailed
  • platformConversationId: the ID of the conversation
{
  "eventType": "escalationFailed",
  "platformConversationId": "123456789"
}

Agent Disconnect

When the agent ends the escalated conversation, the agent can send an agentDisconnect event to our API webhook. This event should contain the following information:

  • eventType: with the value agentDisconnect
  • platformConversationId: the ID of the conversation
{
  "eventType": "agentDisconnect",
  "platformConversationId": "123456789"
}