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 view details, start a callback, resolve the escalation, or reassign it to another team member.

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, phone icon) - callback has been started
   • Called back (green, tick icon) - escalation is resolved
   • SLA approaching (amber, warning icon) - the SLA deadline is near
   • Overdue (red, alert icon) - the SLA deadline has passed

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 note reads “View full transcript (available after Epic 26)”.

   Level 5 - Audio: A placeholder section noting “Audio playback available after Epic 26”.

   Level 6 - Call Timeline: A collapsible section (collapsed by default). Select the “Call Timeline” header to expand. Currently shows a placeholder noting “Call timeline available after Epic 26”.

Taking action on an escalation

1. Three action buttons appear in the detail panel header:

   • Call back - marks the escalation as “in_progress”. This button is disabled if the escalation is already in progress. Use this before calling the customer back.
   • Resolve - marks the escalation as “resolved”. Use this after successfully handling the customer’s request.
   • 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.

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 call back customers, resolve escalations, and reassign work from the detail panel.
• 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
”Call back” button is disabled	The escalation is already in progress	Another staff member may have started the callback. Check the status badge
”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.