Offline Mode

What visitors experience when no agents are available, and how conversations transition to live chat.

Overview

ZapTicket automatically detects whether agents are available using real-time presence tracking. When no agents are online, the widget switches to offline mode — presenting a ticket submission form instead of a live chat interface. This ensures visitors can always reach you, even outside business hours.

Presence Tracking

Agent presence is determined by active SignalR connections to the dashboard. An agent is considered "online" when they have at least one active connection (browser tab with the dashboard open). The moment the last agent disconnects or closes their dashboard, the workspace status transitions to offline.

The widget checks presence status in two ways:

On load: The /widget/config response includes an agentsOnline boolean indicating current availability.
Real-time: The SignalR connection receives presence change events, allowing the widget to transition between online and offline modes without a page reload.

Config response with presence

{
  "primaryColor": "#6366f1",
  "greeting": "Hi there! How can we help?",
  "offlineMessage": "We're offline right now. Leave a message and we'll get back to you.",
  "agentsOnline": false
}

The Offline Experience

When the widget is in offline mode, the visitor sees:

The offline message from your branding configuration (customizable in Settings → Branding).
A ticket submission form with fields for:
- Name (optional if signed identity is provided)
- Email (optional if signed identity is provided)
- Subject (required)
- Message body (required)
A submit button that creates a ticket in your system.

💡If the visitor has a verified identity (via HMAC), the name and email fields are pre-filled and hidden — they only need to provide a subject and message.

Ticket Creation (Offline Submission)

When a visitor submits the offline form, a ticket is created via the POST /widget/tickets endpoint. The response includes a reference number that the visitor can use to track their request.

Ticket creation response

{
  "ticketId": "tkt_8f3a2b1c",
  "referenceNumber": "ZT-1042",
  "message": "Your message has been received. Reference: ZT-1042"
}

The widget displays a confirmation screen with the reference number. The visitor is informed that they'll receive a response when an agent is available. If the visitor provided an email, they'll also receive an email notification when an agent responds.

Transition to Live Chat

When an agent comes online while a visitor still has the widget open:

The widget receives a presence change event via SignalR.
The offline form is replaced with the live chat interface.
If the visitor had already submitted a ticket, they can continue the conversation in real-time — the ticket's thread becomes a live conversation.
The chat header updates to show "Online" status.

This transition is seamless. The visitor doesn't need to refresh the page or re-enter any information. Their context is preserved.

💡The reverse also happens: if the last agent goes offline while a visitor is chatting, the widget transitions to offline mode. Any in-progress conversation is preserved as a ticket, and the visitor sees the offline message with an option to add more details.

Agent Handling of Offline Tickets

Tickets created during offline mode appear in the Inbox → Unassigned tab and in the Tickets section of the dashboard. When an agent comes online, they can:

View all pending offline tickets sorted by submission time.
Assign a ticket to themselves or another agent.
Reply to the ticket — if the visitor is still on the site, the reply appears in real-time via the widget.
If the visitor has left the site, the response is sent via email (if an email was provided).

Configuration

Offline mode is automatic and cannot be disabled — it activates whenever no agents are connected. However, you can customize the experience:

Setting	Location	Description
Offline message	Settings → Branding	Text shown above the ticket form
Email notifications	Settings → Notifications	Whether to email visitors when agents reply to offline tickets

Edge Cases

Agent briefly disconnects: There's a 30-second grace period before the workspace is marked offline. Brief network interruptions don't trigger offline mode.
Multiple tabs: If an agent has multiple dashboard tabs open, the workspace stays online as long as at least one tab is connected.
Visitor refreshes during offline: The reference number is stored in local storage. On reload, the confirmation screen is shown again with the reference number.