Tiqora
Docs Live Chat

Live Chat

Tiqora's live chat system lets you embed a real-time chat widget on your website. Customers interact with an AI chatbot first, which can escalate to a live agent when needed. If no agent is available, the conversation is automatically converted into a support ticket.

How It Works

  1. You embed the chat widget on your website using a single script tag
  2. A customer opens the widget and fills in their name and email
  3. The AI chatbot handles the conversation using your knowledge base
  4. If the chatbot can't help, the conversation escalates to your agent queue
  5. An available agent claims the chat and continues the conversation in real-time
  6. If no agent is available within 10 minutes, the chat becomes a ticket with the full transcript

Embedding the Widget

Add a single script tag to your website:

<script src="https://tiqora.ai/widget.js" data-tenant="your-slug" async></script>

Replace your-slug with your tenant slug (found in Settings). The widget will appear as a floating button in the bottom-right corner of your page.

How the Widget Loads

  • widget.js (~8KB gzipped) injects a floating chat button on your page
  • When clicked, it opens an iframe pointing to chat.tiqora.ai for XSS isolation
  • Sessions persist via localStorage so returning visitors resume their conversation
  • On mobile devices (< 480px), the widget opens full-screen

Widget Configuration

Configure the chat widget from the Tiqora dashboard under Settings > Chat Widget:

Setting Description
Chatbot Name The display name for the AI bot (e.g., "Tiq")
Greeting Message First message shown when a customer opens the widget
Offline Message Shown when no agents are available
Primary Color Widget accent color (buttons, header)
Position Widget button position (bottom-right or bottom-left)
Avatar URL Custom avatar image for the chatbot
Pre-Chat Fields Form fields to collect before starting (name, email)
Max AI Turns Maximum bot messages before forced handoff (default: 10)

Domain Restrictions

Control where your widget can be embedded:

  • Strict mode (default): Widget only works on domains you whitelist. Returns 403 for unlisted origins. Best for production.
  • Permissive mode: Widget works on any website. Useful during development or for maximum reach.

Manage allowed domains in Settings > Chat Widget > Allowed Domains. Wildcard subdomains are supported (e.g., *.example.com). Changes propagate within 5 minutes.

Chat Widget API

Initialize a Chat Session

POST /api/v1/chat/init

Request:

{
  "tenant_slug": "acme",
  "name": "Jane Smith",
  "email": "jane@example.com"
}

Response (201):

{
  "data": {
    "session_id": "01912345-6789-7abc-def0-123456789abc",
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "greeting": "Hi! How can I help you today?",
    "chatbot_name": "Tiq"
  }
}

The token is an ephemeral JWT (24-hour expiry) used to authenticate subsequent requests for this session.

Send a Message

POST /api/v1/chat/sessions/{session_id}/customer-messages

Headers:

Content-Type: application/json

Request:

{
  "body": "How do I reset my password?",
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

Response (201):

{
  "data": {
    "id": "01912345-aaaa-7abc-def0-123456789abc",
    "chat_session_id": "01912345-6789-7abc-def0-123456789abc",
    "sender_type": "customer",
    "body": "How do I reset my password?",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

If the session is in the AI chatbot phase, the bot processes the message asynchronously and responds via WebSocket.

Get Messages (Polling Fallback)

GET /api/v1/chat/sessions/{session_id}/messages?after={timestamp}
Authorization: Bearer {token}

Pass the widget JWT via the Authorization: Bearer header. Use the after query parameter to only fetch messages newer than a given timestamp. This is a fallback for environments where WebSocket isn't available.

Get Widget Configuration

GET /api/v1/chat/widget-config/{tenant_slug}

Returns public widget configuration. Response includes a Content-Security-Policy header with frame-ancestors set based on the domain restriction mode.

Real-Time Communication

Live chat uses WebSocket channels (Pusher-compatible protocol) for real-time message delivery:

Channel Type Purpose
private-chat.{session_id} Private Messages and typing indicators for a specific session
private-chat.queue.{tenant_id} Private New chat alerts for agents
presence-chat.agents.{tenant_id} Presence Agent online status

Widget Authentication

Widget clients authenticate to WebSocket channels using the ephemeral JWT from the /chat/init response. The token is passed via the X-Widget-Token header when subscribing to channels.

Agent Authentication

Dashboard agents authenticate using their standard JWT Bearer token. Channel access is authorized based on tenant membership and role.

AI Chatbot

The AI chatbot uses your knowledge base (articles and documents) to answer customer questions. It operates with these behaviors:

  • RAG-powered: Retrieves relevant knowledge base content for each question
  • Configurable persona: Set the chatbot's tone and personality via widget config
  • Credit metering: Each bot response costs 2 AI credits (1 RAG retrieval + 1 generation)

Escalation Triggers

The chatbot escalates to a human agent when:

  1. The customer explicitly requests a human ("talk to a real person")
  2. A blocked topic is detected (configured in AI settings)
  3. Maximum AI turns reached (default: 10)
  4. Low confidence on 2+ consecutive responses

Average Session Cost

A typical chat session with 6 bot responses costs approximately 12 AI credits (2 per response: 1 RAG retrieval + 1 generation).

Agent Dashboard

Agents manage live chats from the Live Chat section in the Tiqora dashboard:

Session Lifecycle

Bot → Queued → Active → Resolved
                  ↓
              To Ticket
Status Description
bot AI chatbot is handling the conversation
queued Waiting for an agent to claim
active Agent is actively chatting
resolved Conversation completed
abandoned Customer left without resolution

Agent Actions

  • Claim: Pick up a queued chat session
  • Transfer: Transfer to another agent or department
  • Resolve: Close the conversation
  • Convert to Ticket: Create a support ticket with the full chat transcript

Agent Availability

Agents set their status to Online, Away, or Offline:

  • Online agents appear in the routing queue
  • Max concurrent chats can be configured per agent (default: 3)
  • Routing uses least-busy-first algorithm

Rate Limiting

Action Limit
Chat sessions (per IP) 5 per hour
Messages (per session) 20 per minute
Widget config requests 60 per minute

Security

  • All messages are sanitized (plain text only, HTML stripped)
  • Widget tokens are ephemeral (24-hour expiry) and scoped to a single session
  • CORS domain whitelist enforced in strict mode
  • CSP frame-ancestors header prevents unauthorized embedding
  • Rate limiting on all public endpoints
Previous
Error Handling
Next
API Keys