How to handle widget escalations

How it works

When a conversation with a customer needs an escalation to an agent, the API will send a widgetEscalate event to the defined webhook, it is now up to the custom CRM to initiate the escalation process on its side. Our chat widget will be also notified of the escalation, and start listening for updates on the escalation process.

Now the custom CRM needs to resolve the escalation and start sending the agent messages. The /agent/converse/send-message-to-widget API should receive agent events. The supported events in this webhook are:

• escalationQueueUpdate: the customer is in a queue for a free agent. Can contain queue position and/or waiting time information
• escalationSuccess: the customer is now connected with the agent, providing agent’s name and avatar
• message: send an agent’s message to the customer’s widget
• escalationFailed: the escalation process failed and the customer coulnd’t be connected with an agent
• agentDisconnect: the agent ended the escalated conversation

Escalation Queue Update

When the customer is in a queue for a free agent, the Agent can send as many 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 an agent is established, the Agent will send an escalationSuccess event to our API webhook. It will mark the conversation as escalated and messages can be exchanged between customer and 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 agent will send messages to the customer. 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 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"
}