Routing & Availability Diagnostics Guide

What Is Routing Diagnostics?

Velaro logs every routing decision and availability snapshot so you can understand exactly why a chat was routed, missed, or handled by a bot. Administrators can investigate missed chats, uncoordinated coverage gaps, and after-hours issues using the Routing History page and the Live Dashboard.

Why Was a Chat Missed?

When a chat is marked Missed, Velaro stores a reason code and an availability snapshot at the moment of the miss. To see it:

1. Go to Rules > Routing History

2. Filter by Outcome Type: missed or search by conversation ID

3. Click a missed entry to see the availability snapshot: how many agents were online, how many were available, and how many were busy at capacity

Missed reason codes:

• NoAgentsOnline — nobody was logged in to the team
• AgentsNotAvailable — agents were logged in but set to Away or a non-available status
• AgentsBusy — agents were online and available-status but all at their max chat limit
• OutOfSchedule — the team's operating hours were closed at the time
• TimedOut — the visitor waited in queue longer than the configured timeout
• Abandoned — the visitor left the chat before being answered
• Rejected — an agent or admin manually rejected the conversation
• PreChatSurveyAbandoned — the visitor left during the pre-chat form or bot survey

How to Detect Uncoordinated Lunch Breaks

If chats are being missed during the same time window each day, agents may be going to lunch at the same time without coverage overlap. To investigate:

1. Go to Rules > Routing History

2. Set date range to the past 7–14 days

3. Filter by Outcome Type: missed-NoAgentsOnline or missed-AgentsBusy

4. Look for a cluster of misses in the same hour window (e.g., 12:00–1:00 PM)

5. Check the availability snapshot — "X agents online, 0 available" at that time confirms a capacity collapse

Fix: Stagger lunch breaks across agents or create an Unavailability Workflow to handle chats during that window (capture email, offer callback, etc.).

What Is the Live Dashboard?

The Dashboard page shows real-time agent and team status, refreshed every 15 seconds. It is the fastest way to see coverage gaps as they happen.

Coverage badge meanings on team cards:

• No badge (green border) — at least one agent is available and taking new chats
• "All agents busy" (amber badge) — agents are online but all are at their max chat capacity. New chats will queue or be missed.
• "No agents online" (red badge) — nobody is logged in to this team. All new chats will be missed unless a routing rule redirects them or an Unavailability Workflow runs.

Teams with coverage gaps are automatically sorted to the top of the dashboard.

When a Bot Routes to a Human and No One Is Available

If your workflow bot escalates to a human agent and no agents are available, Velaro automatically:

1. Checks if you have a Use Workflow on Unavailable rule configured for that team

2. If yes — runs that workflow (bot can collect email, offer callback, schedule appointment, etc.)

3. If no — marks the conversation Missed with reason AgentsBusy or NoAgentsOnline, sends alerts via SMS/Teams/Slack if configured, and records the availability snapshot

The availability snapshot is visible in Routing History and shows how many agents were online vs. available vs. busy at that exact moment.

How to Set Up an Unavailability Workflow

An Unavailability Workflow catches chats that would otherwise be missed and keeps the conversation going:

1. Go to Rules > Routing Rules

2. Create a new rule with trigger "Use Workflow on Unavailable"

3. Select the workflow to run (e.g., "Collect Email for Follow-Up" or "Schedule Callback")

4. Assign it to the team(s) that need coverage

The <<missedReason>> variable is available inside the workflow so the bot can say "We're currently closed" or "All agents are busy right now" in a natural way.

Chatbot Routing to Live Agents After Hours — Why It Happens

If your chatbot keeps routing visitors to live agents outside business hours (or never shows the offline/after-hours message), there are six root causes to check in priority order. You can ask Copilot to run the diagnostic automatically: "Why is my bot routing to agents after hours?"

1. No schedule configured

The most silent failure: if Settings → Scheduling has no schedules, the system has nothing to gate on. Visitors always route to agents — no error is logged, it just behaves as if it's always open.

Fix: Go to Settings → Scheduling, create a schedule, add shifts for your business hours, and assign agents to it.

---

2. After-Hours Action set to "None"

A schedule exists but After-Hours Action is left at its default value of None. The schedule will track agent adherence but will NOT gate routing or show an offline message.

After-Hours Action	What happens outside hours
None	❌ Visitors route normally — no gate
Offline Message	✅ Shows the site's offline/missed-chat flow
Bot	✅ Routes to the site's default after-hours bot

Fix: Go to Settings → Scheduling → select your schedule → set After-Hours Action to Offline Message or Bot.

---

3. Enforce Availability is off

After-Hours Action only fires when Enforce Availability is enabled on the schedule. Without it, the schedule is reporting-only — it tracks hours for adherence metrics but does not gate routing.

Fix: Go to Settings → Scheduling → select your schedule → turn on Enforce Availability.

> V10 note: In V10 this was a global site-level toggle called "Enable Scheduling." In V20 it is per-schedule.

---

4. Wrong timezone

The schedule looks correct but the after-hours window is shifted by several hours. The default timezone is GMT Standard Time (UTC). A US site with this default thinks 9am–5pm business hours are UTC — which is 2am–10am Pacific.

Fix: Go to Settings → Site Settings → Profile → Timezone and set it to the timezone where your agents are located.

Region	Timezone ID to enter
Pacific	Pacific Standard Time
Mountain	Mountain Standard Time
Central	Central Standard Time
Eastern	Eastern Standard Time

---

5. Schedule has no shifts or no agents assigned

• No shifts → no time window is defined → the schedule is always "open" (no after-hours period exists)
• No agents assigned → the schedule can't determine who is on shift → defaults to open

Fix: Go to Settings → Scheduling → add shifts for each working day → assign agents to the schedule.

---

6. Agents staying logged in after hours

If the schedule is correctly configured (Enforce Availability = on, After-Hours Action ≠ None), the schedule check runs before agent availability — so even an online agent will not receive chats outside hours. This root cause only matters if one of the above five is also present.

Fix: Confirm root causes 1–5 are all resolved first. If agents are regularly staying logged in past shift end, consider enabling automatic status-to-Away transitions in Settings → Agent Settings.

---

Smart Routing Engine

Smart Routing is an advanced routing mode that adds per-conversation escalation timers, anti-bounce protection, and capacity-weighted assignment. It runs alongside team routing settings and handles the escalation lifecycle for each conversation.

Routing & Escalation Settings

Go to Settings → Routing & Escalation to configure the Smart Routing engine.

Engine version:

• Legacy — original queue-and-assign logic with team-level idle timeouts
• Smart Routing — per-conversation escalation timers, rerouting, and terminal actions

Response timers (Smart Routing only):

• Initial Response Timeout — time before an agent gets a warning for not responding to a new conversation
• Idle After Response Timeout — time of no activity (after a response) before an idle alert fires
• Idle Alert Grace Period — extra time given after the idle alert before the conversation is rerouted
• Queue Unavailable Grace Period — wait before returning "unavailable" when all agents are transiently busy

Escalation behavior:

• Max Reroute Attempts — how many times a conversation is re-assigned before the terminal action runs
• Allow Agent Bounceback — if off (default), an agent who timed out cannot receive the same conversation again in this routing cycle
• Prefer Previous Agent — on timeout, prefer the agent from the visitor's prior session (loyalty routing)
• Terminal Action — what happens after all reroute attempts are exhausted: Survey, Create Ticket, Queue, Offline Message, or No Action

Circuit Breaker

If the Smart Routing engine encounters repeated errors (more than 5 in a 5-minute window for a site), it automatically opens the circuit breaker and reverts to Legacy routing. The Settings page shows a warning banner when the breaker is open.

To reset: go to Settings → Routing & Escalation and click Reset Circuit Breaker in the warning banner.

Routing Decision Log

Every routing step for a conversation is logged. To investigate how a conversation was handled:

1. Use Copilot: "Show me the routing decision log for conversation 12345"

2. Or use the CLI: velaro routing decision-log 12345

3. Or call the MCP tool: routing_get_decision_log with conversationId

The log shows: assignment events, reroute attempts, which agent was assigned (and from which), the rule source, and the terminal action if one was applied.

Common Copilot Questions

• "Is Smart Routing enabled?" → Copilot checks routing_get_engine
• "Why was conversation 456 rerouted three times?" → Copilot fetches the decision log
• "Set the initial response timeout to 90 seconds" → Copilot calls routing_update_policy
• "The circuit breaker is open — reset it" → Copilot calls routing_reset_circuit_breaker

What Is Routing Retrigger?

The Retrigger button in Routing History lets you re-run the routing engine against any past conversation — safely, with zero side effects. It is a pure dry-run: no agents are contacted, no workflows start, no data is changed. It simply tells you what would happen if that conversation came in right now under your current rules.

When to use it:

• A conversation wasn't routed to the expected team — use Retrigger to confirm the rule is now fixed
• You changed a routing rule and want to verify it works before the next live chat
• Support is debugging why a specific conversation went to the wrong place

How to use it:

1. Go to Rules → Routing History

2. Find the conversation you want to test

3. Click ↺ Retrigger on that row

4. The result shows: which trigger would fire, which rule would match, and what the outcome would be

The retrigger evaluates all 8 routing triggers in priority order: workflow, automation, AI, pre-chat survey, unavailable survey, post-chat survey, team routing, and priority assignment.

Why Did a Conversation Route to That Agent? (Smart Routing Decisions)

When Smart Routing is enabled, every step in a conversation's routing lifecycle is recorded — not just where it ended up, but every warning, reassignment, and timeout along the way. You can see the full timeline two ways:

In the admin UI:

1. Go to Settings → Routing & Escalation → Decision Log

2. Search by conversation ID, agent name, or team

3. Click View full timeline on any row

The timeline shows each step in plain language:

• 2:14pm — Assigned to Alex R. (least-busy: 2 active chats)
• 2:16pm — Alex warned: no response after 2 minutes
• 2:17pm — Rerouted to Sam T. (Alex did not respond)
• 2:22pm — Sam responded — conversation active

Via Copilot: Ask "What happened with conversation 8821?" and Copilot will pull the full timeline and explain each step.

Why Didn't the Chat Button Show?

The chat button can be hidden by several things working in combination. If a visitor says they couldn't find the chat button, check these in order:

1. Schedule / after-hours — the team's schedule was closed at the time. Check Settings → Scheduling and confirm the timezone is set correctly (default is UTC, which is 7–8 hours ahead of Pacific).

2. Hide button when unavailable — if this is on for the deployment and all agents were busy or offline, the button hides automatically. Check Settings → Deployments → [your deployment] → Availability.

3. Page conditions on the deployment — the chat button may only be configured to show on specific pages or URLs. Check Settings → Deployments → [your deployment] → Display Rules.

4. Workflow condition — a widget_loaded workflow may have a condition that hides the button for that visitor (by URL, contact attribute, etc.).

Ask Copilot: "Why wasn't the chat button showing for conversation 12345?" — Copilot will check the deployment settings, schedule, and availability snapshot at that exact moment and tell you which condition caused it.

Missed Chats — Understanding What Happened

Every missed conversation in Inbox → Missed shows a reason badge directly on the row so you don't need to dig:

Badge	What it means	Quick fix
No agents online	Nobody was logged in	Check schedule adherence; set up an after-hours bot
Agents away	Agents were logged in but set to Away	Review status management; use auto-status rules
All agents busy	Everyone was at their chat limit	Increase max chats per agent, or add overflow routing
Out of schedule	Team's hours were closed	Confirm schedule and timezone; add an after-hours workflow
Timed out in queue	Visitor waited past the queue timeout	Reduce timeout or add a bot fallback for long queues
Smart routing exhausted	All reassignment attempts failed	Review agent response times; consider increasing timeout or agent count
Abandoned	Visitor left before being answered	May need faster first response; check if the bot could have held them

Clicking any missed conversation shows the availability snapshot: how many agents were online, available, and at capacity at that exact moment — so you can tell the difference between "no one was here" and "everyone was slammed."

The "Smart routing exhausted" badge is new with Smart Routing. It means the conversation was reassigned multiple times (up to your configured maximum) and no agent responded within the timeout. When this badge appears, the follow-up flag was also sent to the last agent who received it. You can see the full reassignment trail in the timeline.

How to Ask Copilot About Routing Issues

You can ask the Velaro Copilot directly about routing problems. Example questions:

Specific conversation:

• "What happened with conversation 12345?"
• "Why was conversation 98765 rerouted?"
• "Why didn't the chat button show for conversation 12345?"
• "Who was online when conversation 8821 came in and why did it go to Alex?"
• "Was Smart Routing active for conversation 12345?"

Patterns and trends:

• "How many chats were missed this week and why?"
• "Which agents are timing out most often?"
• "What time of day do we exhaust all routing attempts?"
• "Are any teams consistently running out of agents?"
• "Show me conversations where Smart Routing had to reassign more than twice"

Configuration help:

• "Is my routing policy set up correctly for the Support team?"
• "Would increasing the initial response timeout to 3 minutes reduce my reroute rate?"
• "Do I have any workflows that conflict with my routing policy?"
• "Run a retrigger simulation on conversation 12345 and tell me if my rule change would have fixed it"

Copilot pulls the actual decision log, availability snapshots, and policy settings to give you a specific answer — not a generic "check your settings" response.

Routing Retrigger — Safety Guarantee

The retrigger is 100% read-only. It uses a dry-run mode of the same rule evaluator the live routing engine uses, but:

• No workflows are started
• No agents receive new chats
• No conversation state is changed
• No notifications are sent
• It is safe to run on resolved, assigned, or active conversations at any time

Routing History Filters

The Routing History page supports these filters:

• Days back (1–90 days)
• Trigger type — e.g., "auto-assign-unavailable", "route-to-team", "use-prechat-survey"
• Rule ID — filter to a specific routing rule
• Outcome type — filter to e.g. "routed_to_team", "workflow_started", or "missed-*" outcomes

Each missed entry shows: agents online, agents available, agents busy, and a plain-English miss detail line.

Routing Rule Conditions for Availability

You can build routing rules that react to team availability in real time:

• Team Availability condition — routes differently based on whether a team is Available, Busy, or Unavailable
• Queue Size condition — triggers overflow routing when a team's queue exceeds a threshold

Example: "If Sales team is Busy AND queue > 3 → route to Support team"

This lets you create automatic overflow paths so chats never pile up on a single team.

---

Smart Routing Engine — Decision Log

The Smart Routing Engine (when enabled) logs every routing step for every conversation. You can view a plain-English explanation in two ways:

Admin UI:

1. Go to Routing > Routing Settings

2. Click Decision Log (top right)

3. Enter a Conversation ID and click Explain

The explanation shows:

• Which engine handled the conversation (modern or legacy)
• A timestamped plain-English timeline of every routing event
• The policy settings that were active (timeouts, max reroutes, terminal action)
• Agent names for every assignment and reroute

Ask Moshky:

> "Why did conversation 4829301 route to Sarah instead of John?"

> "What happened with conversation 48301 — was it missed?"

> "Explain the routing for conversation 5001234"

Moshky uses the routing_explain_decision tool to answer these questions.

Smart Routing Event Types

Event	What it means
Warned	A warning message was sent to the visitor because the assigned agent hasn't responded yet
AgentAlerted	A "still there?" idle alert was sent to the agent after they went quiet post-first-response
AgentAcknowledged	The agent clicked/tapped the alert — their idle timer was reset
Rerouted	The conversation was moved from one agent to another (shows attempt number)
Exhausted	All reroute attempts were used up
TerminalApplied	The terminal action fired (Survey, Create Ticket, Queue, Offline Message, or No Action)
OverflowGranted	A solo agent was granted an overflow exception (took the chat even while at capacity)
StateRecovered	The routing state was missing and was reconstructed with safe defaults

What the Policy Settings Mean

Setting	Effect
Initial response timeout	How long to wait for the assigned agent to send a first message before warning the visitor and re-routing
Idle after response timeout	How long an agent can go silent after replying before triggering an idle alert
Idle alert grace	Extra grace seconds after the alert is sent before re-routing happens
Max reroutes	How many agents can be tried before the terminal action fires
Terminal action	What happens after all reroutes are exhausted — Survey, Create Ticket, Queue, Offline Message, or No Action
Anti-bounce (AllowBounceBack=false)	Agents who previously timed out on this conversation are excluded from future reroute attempts for it
Prefer previous agent	On a new session timeout, the engine prefers the agent who last helped this visitor

Recent Routing Events Feed

On the Decision Log page, click Load recent to see the last 7 days of routing events for your site. Clicking any Conversation ID in the feed immediately explains that conversation.

Events with type Exhausted or TerminalApplied indicate conversations where agents didn't respond in time — high counts here suggest an agent capacity or availability problem.