Widget Escalation API
Connects agents with customers when an escalation is triggered using the Widget Escalation API.
All requests should be made to your API base URL: https://api.ultimate.ai
JSON format
Escalation API requests are represented as JSON objects with the following properties:
| Name | Type | Required | Description |
|---|---|---|---|
| platformConversationId | string | Yes | Unique identifier for the conversation, generated by the custom CRM application. |
| eventType | string | Yes | The type of escalation event. Possible values: "escalationQueueUpdate", "escalationSuccess", "message", "escalationFailed", "agentDisconnect" |
| text | string | No | Text content of the agent’s message (required if eventType is "message" |
| agent | string | No | Name of the agent if eventType is "escalationSuccess" |
| agentAvatar | string | No | URL for the agent’s avatar if eventType is "escalationSuccess" |
| queuePosition | string | No | Visitor’s position in the queue if eventType is "escalationSuccess" |
| waitingTime | string | No | Estimated wait time for the visitor in minutes if eventType is "escalationSuccess". |
Send escalation events to a widget
POST /agent/converse/send-message-to-widget
Use this endpoint to send escalation updates or agent messages to an active widget session. The API acknowledges your request with a 200 OK and processes it asynchronously. The customer-facing widget is updated in real time as events are received.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| Authorization | string | header | Yes | API key for the bot. Generate the key from the Custom CRM integration page in the Ultimate.ai dashboard. See the Authentication article for details. |
| botid | string | header | Yes | The ID of the bot sending or receiving the event. |
Example body
{"platformConversationId": "123456789","eventType": "escalationSuccess","agent": "John Smith","agentAvatar": "https://example.com/avatar/john-smith.png"}