Live Chat Widget Module

The Live Chat Widget module provides an embeddable chat widget that enables real-time customer engagement directly on your website. Connect with visitors instantly, route conversations to human agents or AI bots, and manage all conversations from a unified dashboard.

Overview

Key Features:

Embeddable Widget: Easy-to-install JavaScript widget for any website
Real-time Messaging: Instant communication with website visitors
Agent Dashboard: Manage conversations, assign agents, track metrics
AI Bot Integration: Route to AI bots for automated responses
Customizable Appearance: Match your brand colors and style
Business Hours: Configure online/offline behavior
Pre-chat Forms: Collect visitor information before chat starts

Quick Start

1. Enable the Module

Go to Integrations > Modules
Find Live Chat Widget in the Channels category
Click Enable

2. Create a Widget

Navigate to Live Chat > Widgets
Click Create Widget
Configure appearance and behavior
Save the widget

3. Install on Your Website

Copy the embed code and add it to your website:

<script src="https://your-domain.com/api/widget/{token}/script.js" async></script>

The widget will automatically appear on your pages.

Widget Configuration

Basic Settings

Setting	Description	Default
Name	Internal name for the widget	Required
Handler Type	Who handles chats: `agent`, `ai_bot`, or `workflow`	`agent`
Active	Enable/disable the widget	`true`

Appearance

Setting	Description	Default
Primary Color	Main widget color (hex)	`#000000`
Text Color	Text color on primary background	`#ffffff`
Position	Widget placement: `bottom-right`, `bottom-left`, `top-right`, `top-left`	`bottom-right`
Border Radius	Roundness of corners (px)	`12`
Launcher Size	Size of the chat button (px)	`60`
Logo URL	Custom logo image URL	None

Messages

Setting	Description	Default
Welcome Title	Header text in chat window	"Hi there!"
Welcome Message	Greeting message to visitors	"How can we help you today?"
Input Placeholder	Placeholder in message input	"Type a message..."
Offline Message	Message when agents are offline	Custom message

Behavior

Setting	Description	Default
Collect Name	Ask for visitor's name before chat	`true`
Collect Email	Ask for visitor's email before chat	`true`
Sound Enabled	Play notification sounds	`true`
Show Branding	Display "Powered by AutoCom"	`true`
Allowed Domains	Restrict widget to specific domains	All domains

Business Hours

Configure when your team is available:

{
  "timezone": "Asia/Kolkata",
  "monday": { "enabled": true, "start": "09:00", "end": "18:00" },
  "tuesday": { "enabled": true, "start": "09:00", "end": "18:00" },
  "wednesday": { "enabled": true, "start": "09:00", "end": "18:00" },
  "thursday": { "enabled": true, "start": "09:00", "end": "18:00" },
  "friday": { "enabled": true, "start": "09:00", "end": "17:00" },
  "saturday": { "enabled": false },
  "sunday": { "enabled": false }
}

Agent Management

Setting Up Agents

Agents are team members who can respond to live chat conversations.

Go to Live Chat > Agents
Click Add Agent
Select a team member from the dropdown
Set their maximum concurrent chats
Click Save

Agent Status

Status	Description
Online	Available to receive new chats
Away	Temporarily unavailable
Busy	Handling maximum chats
Offline	Not accepting new chats

Automatic Assignment

When a new conversation starts:

System finds available online agents
Considers agent workload (current chat count vs max)
Assigns to agent with lowest workload
If no agents available, chat stays in queue

Conversation Management

Conversation States

pending → active → resolved/closed
          ↓
        waiting (agent awaiting response)

Status	Description
Pending	New conversation, not yet assigned
Active	Agent actively chatting
Waiting	Waiting for visitor response
Resolved	Issue solved, awaiting confirmation
Closed	Conversation ended

Working with Conversations

From the Live Chat > Conversations page:

View all conversations with status filters
Search by visitor name, email, or message content
Assign/reassign to different agents
Set priority (low, normal, high, urgent)
Add internal notes (not visible to visitor)
Rate and provide feedback after resolution

Quick Actions

Action	Description
Resolve	Mark issue as solved
Close	End the conversation
Reopen	Resume a closed conversation
Transfer	Assign to another agent

Dashboard & Analytics

Dashboard Overview

The Live Chat dashboard shows:

Active Chats: Currently ongoing conversations
Pending Chats: Waiting for agent assignment
Today's Stats: Conversations started, resolved today
Average Response Time: Time to first agent response
Online Agents: Currently available team members

Key Metrics

Metric	Description
Response Time	Average time to first response
Resolution Time	Average time to resolve
Customer Satisfaction	Average rating (1-5 stars)
Chat Volume	Number of conversations over time
Agent Performance	Chats handled, ratings per agent

API Reference

Dashboard

GET /api/v1/live-chat/dashboard

Returns stats, recent conversations, and active widgets.

Widgets

GET /api/v1/live-chat/widgets
POST /api/v1/live-chat/widgets
GET /api/v1/live-chat/widgets/{id}
PUT /api/v1/live-chat/widgets/{id}
DELETE /api/v1/live-chat/widgets/{id}
POST /api/v1/live-chat/widgets/{id}/toggle-active
POST /api/v1/live-chat/widgets/{id}/regenerate-token
GET /api/v1/live-chat/widgets/{id}/embed-code

Conversations

GET /api/v1/live-chat/conversations
GET /api/v1/live-chat/conversations/{id}
GET /api/v1/live-chat/conversations/{id}/messages
POST /api/v1/live-chat/conversations/{id}/messages
POST /api/v1/live-chat/conversations/{id}/assign
POST /api/v1/live-chat/conversations/{id}/resolve
POST /api/v1/live-chat/conversations/{id}/close
POST /api/v1/live-chat/conversations/{id}/reopen
PUT /api/v1/live-chat/conversations/{id}/priority

Agents

GET /api/v1/live-chat/agents
POST /api/v1/live-chat/agents
GET /api/v1/live-chat/agents/{id}
PUT /api/v1/live-chat/agents/{id}
DELETE /api/v1/live-chat/agents/{id}
GET /api/v1/live-chat/agents/me
PUT /api/v1/live-chat/agents/me/status

Public Widget Endpoints

These endpoints don't require authentication and are used by the embedded widget:

GET /api/widget/{token}/script.js
GET /api/widget/{token}/config
POST /api/widget/{token}/session
POST /api/widget/{token}/conversations
GET /api/widget/{token}/conversations/{id}/messages
POST /api/widget/{token}/conversations/{id}/messages
POST /api/widget/{token}/conversations/{id}/rate

Data Model

Widget

id: integer
name: string
token: string (unique, 32 chars)
is_active: boolean
primary_color: string (hex)
text_color: string (hex)
position: string
border_radius: integer
launcher_size: integer
launcher_icon: string
logo_url: string (nullable)
welcome_title: string
welcome_message: text
input_placeholder: string
offline_message: text
handler_type: 'agent' | 'ai_bot' | 'workflow'
handler_id: integer (nullable)
collect_email: boolean
collect_name: boolean
show_branding: boolean
sound_enabled: boolean
allowed_domains: array
business_hours: object

Visitor

id: integer
session_id: string (unique)
name: string (nullable)
email: string (nullable)
phone: string (nullable)
ip_address: string
user_agent: string
referrer: string (nullable)
current_page: string (nullable)
first_seen_at: timestamp
last_seen_at: timestamp

Conversation

id: integer
widget_id: integer
visitor_id: integer
agent_id: integer (nullable)
status: 'pending' | 'active' | 'waiting' | 'resolved' | 'closed'
priority: 'low' | 'normal' | 'high' | 'urgent'
source_url: string (nullable)
source_page_title: string (nullable)
last_message: text (nullable)
last_message_at: timestamp (nullable)
first_response_at: timestamp (nullable)
resolved_at: timestamp (nullable)
closed_at: timestamp (nullable)
rating: integer (1-5, nullable)
feedback: text (nullable)

Message

id: integer
conversation_id: integer
sender_type: 'visitor' | 'agent' | 'bot' | 'system'
sender_id: integer (nullable)
content: text
metadata: object (nullable)
is_read: boolean
read_at: timestamp (nullable)

Agent

id: integer
user_id: integer
status: 'online' | 'away' | 'busy' | 'offline'
max_concurrent_chats: integer (default: 5)
current_chats_count: integer
total_chats_count: integer
total_rating: integer
ratings_count: integer
last_active_at: timestamp (nullable)

Integration with AI

AI Bot Handler

When a widget uses handler_type: 'ai_bot':

Visitor message is sent to configured AI service
AI generates response based on context
Response is sent back to visitor
If AI can't handle, escalates to human agent

Workflow Handler

When a widget uses handler_type: 'workflow':

Visitor is guided through predefined flow
Collects structured information
Routes to appropriate department/agent
Creates support ticket if needed

Best Practices

Widget Placement

Place widget on all customer-facing pages
Avoid placing on checkout pages (distracting)
Use different widgets for different sections (sales vs support)

Response Time

Aim for < 1 minute first response during business hours
Set clear offline expectations
Use quick replies for common questions

Agent Training

Train agents on product knowledge
Use canned responses for FAQs
Escalation procedures for complex issues

Visitor Experience

Don't require too much info upfront
Be proactive with greeting messages
Follow up on unresolved conversations

Troubleshooting

Widget Not Appearing

Verify embed code is correct
Check browser console for JavaScript errors
Ensure widget is active
Check allowed domains configuration

Messages Not Sending

Check network connectivity
Verify API URL is accessible
Check browser console for CORS errors
Ensure widget token is valid

Agents Not Receiving Chats

Verify agent status is "online"
Check max concurrent chats limit
Ensure agent is assigned to widget's scope
Check conversation assignment settings

Next Steps

Modules Overview - Understanding the module system
Team Management - Managing users and permissions
API Reference - Complete API documentation