Live Agent Escalation

When a bot flow reaches a handoff node or the visitor requests a live agent, the widget escalates the conversation to a human agent through the configured CCaaS integration (Genesys, 8x8, Amazon Connect, or Google CCAI). This page covers the escalation UI components, the multi-agent hub selector, and the disconnect flow.

Escalation Banner

The EscalationBanner is a status bar that appears above the message list during escalation. It uses the theme's primary_color as its background with white text and transitions between three states.

States

Connecting

Displayed immediately when the escalation is initiated.

Element	Description
Spinner	Animated circular spinner (white on primary color background)
Text	"Connecting you with an agent..."

Waiting

Displayed when the visitor is in a queue waiting for an available agent.

Element	Description
Clock icon	SVG clock icon
Text	"Waiting for an agent..." followed by queue position (e.g., "(3 in queue)")
Cancel button	X icon button to cancel the agent request

Queue position updates arrive via queue_update WebSocket messages. If an estimated wait time is available, it is displayed as a system message (e.g., "You are #3 in queue. Estimated wait: 2 minutes.").

Connected

Displayed when a live agent has joined the conversation.

Element	Description
Checkmark icon	SVG checkmark icon
Text	"Connected to [Agent Name]"
Disconnect button	Text button labeled "Disconnect"

Agent Name

The agent's name is provided by the CCaaS integration when the agent joins. If no name is available, "an agent" is displayed.

imageThree escalation banner states: Connecting (spinner with 'Connecting you with an agent'), Waiting (clock icon with queue position), and Connected (checkmark with agent name and Disconnect button)

Escalation banner state transitions

Banner Behavior

The banner uses role="status" and aria-live="polite" with aria-atomic="true", ensuring screen readers announce state changes without interrupting the user.

Agent Indicator

The AgentIndicator is a small badge displayed in the header area that shows the currently connected agent. It includes the agent's name and, if available, their avatar image. The indicator is visible only while the conversation is escalated.

When an agent joins the conversation, the widget receives an agent_joined event containing:

Field	Description
agent_id	Unique agent identifier
agent_name	Agent display name
agent_avatar_url	Optional URL to the agent's avatar image

Agent messages appear in the chat with the agent's name and avatar. The avatar fallback is the letter "A" on a colored circle.

Escalation Flow

1. Bot flow triggers escalation -- The handoff node in the flow initiates the escalation via the CCaaS service
2. Widget shows "Connecting" banner -- A system message appears: "Connecting you with [Agent Name]..." or "Connecting you with a live agent..."
3. Queue updates arrive -- If agents are busy, the widget shows queue position and estimated wait time
4. Agent joins -- The agent_joined event updates the banner to "Connected" state and a system message announces the agent's arrival
5. Chat continues -- User and agent messages are exchanged in real time. Agent typing indicators are shown
6. Escalation ends -- Either the agent ends the session, the visitor disconnects, or the connection times out. A system message announces the end

Escalation Failure

If the escalation fails to connect (e.g., all agents offline, timeout exceeded), the widget:

• Displays a system message with the error or configured timeout message
• Removes the escalation banner
• Returns the conversation to the bot flow

Disconnect

The visitor can end the live agent session at any time by clicking the "Disconnect" button on the escalation banner. When disconnected:

1. The escalation banner is removed
2. A system message appears: "The live agent session has ended. You can continue chatting with the bot."
3. The conversation returns to the bot flow
4. If the flow has a node after the handoff, the bot continues from that point
5. If the backend sends a message with the disconnect event, it is displayed as a bot message

Continue After Escalation

When the bot flow is designed with nodes after the handoff node, the conversation continues from where it left off. This allows post-escalation surveys, follow-up questions, or routing to other bot capabilities.

Multi-Agent Hub

In hub mode, the widget presents an AgentSelector that lets the visitor choose which department or specialist bot to interact with. Hub mode is activated when the backend sends a hub_config message containing the list of available agents and UI configuration.

Hub Configuration

interface HubConfig {
  hub_id: string;
  hub_name: string;
  agents: HubAgentInfo[];
  ui_config: HubUIConfig;
  widget_config: Record<string, unknown>;
}

interface HubAgentInfo {
  id: string;
  name: string;
  description?: string;
  icon?: string;           // Emoji or icon identifier
  name_i18n?: Record<string, string>;        // Translated names
  description_i18n?: Record<string, string>; // Translated descriptions
}

interface HubUIConfig {
  show_agent_selector?: boolean;
  selector_style?: 'grid' | 'list' | 'dropdown';
  show_agent_indicator?: boolean;
  allow_manual_switch?: boolean;
  agent_labels?: Record<string, Record<string, string>>;
}

Agent Selector Layouts

The AgentSelector supports three display layouts:

Grid

Agents are displayed as compact cards in a centered flex-wrap layout. Each card shows the agent's icon (or a default robot icon) and name. Active agent is highlighted with a border and background color.

List

Agents are displayed as full-width rows with icon, name, and description. The active agent shows a checkmark icon on the right side. This layout provides more room for agent descriptions.

Dropdown

A native <select> element with all agents as options. The agent's icon (if emoji) is prepended to the name. This is the most compact layout.

imageThree agent selector layout variations: grid layout with icon cards, list layout with icon-name-description rows, and compact dropdown selector

Multi-agent hub selector layouts: grid, list, and dropdown

Multi-Language Support

Agent names and descriptions support internationalization through name_i18n and description_i18n fields. The widget displays the translated version based on the visitor's current language, falling back to the default name and description if no translation is available.

The selector title also supports translation through ui_config.agent_labels, which maps language codes to UI string overrides including selector_title.

Agent Switching

Trigger	Behavior
User selection	Visitor clicks an agent in the selector. Widget sends select_agent message.
Router switch	Bot flow routes to a different agent automatically. A system message appears: "Routing to [Agent Name]..."

When allow_manual_switch is true, the visitor can switch agents at any time during the conversation. The agent_switch event includes a triggered_by field ('user' or 'router') to distinguish manual from automatic switches.

Accessibility

The AgentSelector uses proper ARIA roles:

• Grid and list layouts use role="listbox" with individual items as role="option"
• Each option has aria-selected to indicate the active agent
• The dropdown uses a native <select> element for built-in accessibility
• All interactive elements have aria-label attributes with the agent's name
• Focus indicators are visible on keyboard navigation