Managing the Voice Escalation Queue

Summary

When the Voice AI cannot fully resolve a caller’s request, it creates an escalation. The Escalation Queue at /voice/escalations shows all escalations requiring staff action. Each escalation card displays the customer name, intent summary, status, priority, and an SLA countdown timer. Staff can take ownership of an escalation, record that the customer was contacted, resolve it, or reassign it to another team member. The detail panel includes the call recording, transcript, and timeline.

The Escalation Queue navigation item shows a count badge: red when any escalation has breached its SLA, yellow when escalations are pending.

Prerequisites

• You must have the voice.escalations.view capability assigned to your role.

Steps

Accessing the escalation queue

1. Navigate to Voice then select Escalation Queue from the navigation. The page opens at /voice/escalations.
2. The page header reads “Escalation Queue” with the subtitle “Voice call escalations requiring staff action”.

Searching and filtering

1. At the top of the list panel, a search box labelled “Search escalations…” lets you search by customer name or intent. Search applies after a short delay (300ms debounce).
2. To clear the search, select the X button inside the search box.
3. Next to the search box, a Status dropdown filter offers four options: All, Pending, In Progress, and Resolved.
4. Changing filters resets pagination to page 1.

Reading escalation cards

1. Escalations appear as cards in a list. The list uses a split-panel layout: cards on the left (40% width on desktop), detail panel on the right (60%). On mobile, selecting a card opens the detail panel full-screen.
2. Each card displays:
   • Status badge - a coloured pill showing the current status (see status badges below)
   • Customer name - the caller’s name
   • Priority indicator - a small red dot appears if the escalation is marked as priority
   • Intent summary - a one-line description of what the caller needed, truncated if long
   • Call time - relative timestamp (e.g. “5m ago”, “2h ago”, “1d ago”)
   • SLA timer - countdown showing time remaining or overdue duration

Understanding status badges

1. Escalation status badges use colour-coded icons:

   • Pending (grey, info icon) - awaiting staff action
   • In progress (blue, dashed-circle icon) - a staff member has taken ownership
   • Resolved (green, tick icon) - the escalation has been handled
   • SLA approaching (amber, warning icon) - the SLA deadline is near
   • Overdue (red, alert icon) - the SLA deadline has passed

2. A still-open escalation that has passed its SLA with no contact recorded also shows a muted No contact recorded pill. Resolved escalations without a recorded contact show nothing - resolving without a callback is a valid outcome.

Understanding SLA timers

1. Each pending escalation has an SLA deadline. The card shows how much time remains.
2. As the deadline approaches, the SLA label turns amber and the card gets an amber left border.
3. When the SLA expires, the label turns red, the card gets a red left border with a red-tinted background, and the status badge changes to “Overdue”.
4. Overdue pending items are sorted to the top of the list automatically.

Sort order

1. The list sorts by three tiers:
   • Overdue pending items first
   • Priority items next (priority descending)
   • Then by creation date (oldest first)

Viewing escalation details

1. Select any card to open its detail panel. On mobile, select the Back button (left arrow) to return to the list.

2. The detail panel header shows the customer name, status badge, and the date and time the escalation was created.

3. The detail panel displays information in six levels:

   Level 1 - AI Summary: A highlighted box labelled “AI Summary” containing the AI’s context brief about the call. If no summary is available, it reads “No AI summary available”.

   Level 2 - Caller Details: The customer’s name, phone number (as a clickable tel: link), and any registered vehicles showing registration, make, and model.

   Level 3 - Linked Work Order (shown only if one exists): A link to the work order (opens at /work-orders/{id}) with the reference code, status badge, and vehicle details.

   Level 4 - Transcript Excerpt: The last 4-6 lines of the call transcript, displayed as speech bubbles. AI messages align left with a label of “AI”, caller messages align right with a label of “Caller”. A View full transcript link opens the call in the Call Log in a new tab.

   Level 5 - Audio: The call recording with an audio player. The player is collapsed by default and loads the recording when you expand it. If no recording exists, the section does not appear.

   Level 6 - Call Timeline: A collapsible section (collapsed by default), the same timeline shown in the Call Log. Select the “Call Timeline” header to expand. If the call produced no meaningful events, the timeline section is hidden.

Taking action on an escalation

1. Four action buttons appear in the detail panel, in this order:

   • Take ownership - assigns the escalation to you and marks it “in progress”, so colleagues do not double-handle it. It does not place a call. To ring the customer, tap their phone number (a tap-to-dial link in the caller details) and dial from your own device.
   • Mark contacted - records that you reached the customer, by whatever means (call, email, SMS, in person). Optional. Once marked, the button is replaced by a line reading “Contacted {time} · {name}”.
   • Resolve - marks the escalation as “resolved”. Use this after handling the customer’s request. You can resolve without recording a contact - not every escalation needs a callback.
   • Reassign - opens the reassignment panel (see below).

2. All action buttons are disabled while an action is processing. A success or error toast notification appears after each action.

3. If a colleague takes ownership at the same moment, your click reports that the escalation is already being handled. Actions cannot race each other.

Reassigning an escalation

1. Select Reassign to expand the reassignment panel.
2. The panel shows the current assignment (or “Currently unassigned”) and a list of staff members.
3. Select a staff member’s name. A confirmation prompt appears asking “Assign to {name}?” with Cancel and Confirm buttons.
4. To remove an existing assignment, select Remove assignment. A confirmation prompt asks “Remove assignment from this escalation?” with Cancel and Confirm buttons.
5. After confirming, the assignment updates and a success toast appears.

Pagination

1. The list displays 20 escalations per page.
2. If there are more, pagination controls appear at the bottom showing the total count, current page, and Prev / Next buttons.

Automatic refreshing

1. The escalation list refreshes automatically every 30 seconds via polling.
2. Switching away from and back to the browser tab also triggers a refresh.
3. After performing an action (callback, resolve, reassign), polling pauses briefly (5 seconds) to avoid overwriting the change you just made.

Expected Outcome

• You see all voice escalations requiring attention, sorted with the most urgent first.
• SLA timers count down in real time, making overdue items clearly visible.
• You can take ownership, record customer contact, resolve escalations, and reassign work from the detail panel.
• You can hear the recording and read the transcript without leaving the queue.
• The list stays current through automatic polling and tab-focus refresh.

Troubleshooting

Problem	Cause	Fix
Page redirects to the dashboard	Your role does not have the voice.escalations.view capability	Ask an admin to update your role permissions
No escalations appear	No voice calls have been escalated	This is normal. Escalations appear when the Voice AI determines it cannot resolve a caller’s request
Empty state message shows	The current filter or search excludes all escalations	Clear the search box and set the status filter to All
”Take ownership” button is disabled	The escalation is already in progress	Another staff member has taken ownership. Check the status badge and assignment
Audio section is missing on an escalation	The call has no recording (recording disabled, or it was deleted)	The transcript is still available. Check recording settings under Settings > Voice AI > Recording
”Failed to load escalation details” shows in the detail panel	Network error or the escalation was deleted	Refresh the page. If the issue persists, the escalation may have been removed
”Failed to load staff list” in reassign panel	Network error fetching the organisation’s staff	Close and reopen the reassign panel to retry
SLA timer is not updating	The timer refreshes every 60 seconds	Wait up to 60 seconds. If it still does not update, refresh the page
Overdue items are not at the top	Overdue sorting only applies within the current page	If you have many escalations across multiple pages, an overdue item on a later page will not move to page 1. Use the status filter set to Pending to find them

Permissions

Capability	What it controls
voice.escalations.view	Access to the Escalation Queue page

Notes

• The keyboard supports navigating the escalation list with Arrow Up, Arrow Down, Home, End, and Enter keys. Tab moves focus from the list to the detail panel.
• Screen readers announce each card with the customer name, status, intent summary, and call time.
• Resolved escalations appear with reduced opacity (dimmed) in the list.