README

A complete, plug-and-play real-time live chat package for Laravel 8+.

Install it, add four .env keys, and a floating chat widget appears on every page of your Laravel application — no manual coding required.

Features

Floating chat widget auto-injected on every HTML page
Real-time messaging (Pusher / Laravel Reverb / Soketi)
Guest support (name + email pre-chat form)
Authenticated user support (no form required)
Typing indicators (both directions)
Online / offline agent status
Read / unread tracking
Sound notification toggle
Minimize / maximize widget
Agent admin dashboard (conversations, replies, assign, close, reopen)
Rate-limited message sending
XSS-safe rendering
Fully configurable via .env
Publishable config, migrations, views, and assets

Requirements

PHP 8.0+
Laravel 8, 9, 10, or 11
A Pusher-compatible broadcasting server (Pusher.com, Laravel Reverb, or Soketi)

Installation

1. Install via Composer

composer require hexalogicdev/live-chat-module

Package auto-discovery registers the service provider automatically.

2. Run the install command

php artisan live-chat:install

This will:

Publish the config file to config/live-chat.php
Publish the migrations to database/migrations/
Publish the public assets to public/vendor/live-chat/
Optionally publish views for customisation
Optionally run migrations

3. Add environment variables

Add the following to your .env file:

LIVE_CHAT_ENABLED=true
LIVE_CHAT_ROUTE_PREFIX=live-chat
LIVE_CHAT_ADMIN_MIDDLEWARE=web,auth

# Broadcasting driver: pusher | reverb | soketi
LIVE_CHAT_BROADCAST_DRIVER=pusher

# Pusher.com credentials
LIVE_CHAT_PUSHER_APP_ID=your-app-id
LIVE_CHAT_PUSHER_APP_KEY=your-app-key
LIVE_CHAT_PUSHER_APP_SECRET=your-app-secret
LIVE_CHAT_PUSHER_CLUSTER=mt1

# Self-hosted (Reverb / Soketi) — leave empty for Pusher.com
LIVE_CHAT_PUSHER_HOST=
LIVE_CHAT_PUSHER_PORT=443
LIVE_CHAT_PUSHER_SCHEME=https

4. Done!

Visit your app — the chat widget appears in the bottom-right corner. Visit /live-chat/admin to access the agent panel (requires authenticated user).

Broadcasting Server Setup

Option A — Pusher.com (easiest)

Create a free account at pusher.com
Create a Channels app
Copy App ID, Key, Secret, and Cluster into your .env

LIVE_CHAT_BROADCAST_DRIVER=pusher
LIVE_CHAT_PUSHER_APP_ID=123456
LIVE_CHAT_PUSHER_APP_KEY=abcdef123456
LIVE_CHAT_PUSHER_APP_SECRET=secretsecret
LIVE_CHAT_PUSHER_CLUSTER=mt1

Option B — Laravel Reverb (self-hosted, free)

composer require laravel/reverb
php artisan reverb:install
php artisan reverb:start

LIVE_CHAT_BROADCAST_DRIVER=reverb
LIVE_CHAT_PUSHER_APP_ID=live-chat
LIVE_CHAT_PUSHER_APP_KEY=live-chat-key
LIVE_CHAT_PUSHER_APP_SECRET=live-chat-secret
LIVE_CHAT_PUSHER_HOST=127.0.0.1
LIVE_CHAT_PUSHER_PORT=8080
LIVE_CHAT_PUSHER_SCHEME=http

Option C — Soketi (self-hosted, free)

npm install -g @soketi/soketi
soketi start

LIVE_CHAT_BROADCAST_DRIVER=pusher
LIVE_CHAT_PUSHER_APP_ID=app-id
LIVE_CHAT_PUSHER_APP_KEY=app-key
LIVE_CHAT_PUSHER_APP_SECRET=app-secret
LIVE_CHAT_PUSHER_HOST=127.0.0.1
LIVE_CHAT_PUSHER_PORT=6001
LIVE_CHAT_PUSHER_SCHEME=http

Admin / Agent Panel

Navigate to:

https://yourapp.com/live-chat/admin

You must be authenticated (uses the middleware defined by LIVE_CHAT_ADMIN_MIDDLEWARE, default: web,auth).

Agent features

See all pending, open, and closed conversations
Reply to conversations in real time
Assign conversation to a specific agent
Close and reopen conversations
Toggle online / offline status
Search conversations by guest name or email

Configuration Reference

After publishing (php artisan live-chat:publish --tag=config), see config/live-chat.php for all options:

Key	Default	Description
`enabled`	`true`	Enable or disable the entire package
`route_prefix`	`live-chat`	URL prefix for all routes
`admin_middleware`	`web,auth`	Middleware for agent panel routes
`auto_inject`	`true`	Auto-inject widget into HTML responses
`broadcast_driver`	`pusher`	Broadcasting driver
`widget.title`	`Live Support`	Widget header title
`widget.welcome_message`	`Hi there! How can we help you?`	Pre-chat welcome text
`widget.primary_color`	`#4f46e5`	Brand colour (hex)
`widget.position`	`bottom-right`	`bottom-right` or `bottom-left`
`widget.sound_enabled`	`true`	Default sound notification state
`max_message_length`	`2000`	Maximum characters per message
`typing_timeout`	`3`	Seconds before typing indicator clears
`history_limit`	`50`	Messages loaded on conversation open
`table_prefix`	`chat_`	Database table prefix
`user_model`	`App\Models\User`	The Eloquent user model

Manual Widget Placement

By default the widget is auto-injected before </body>. To place it manually:

Set LIVE_CHAT_AUTO_INJECT=false in .env
Add @livechat to your layout where you want the widget:

<!DOCTYPE html>
<html>
<head>
    <meta name="csrf-token" content="{{ csrf_token() }}">
</head>
<body>
    ...
    @livechat
</body>
</html>

Note: Ensure your layout includes <meta name="csrf-token"> — the widget requires it for API calls.

Publishing Resources

Publish individual groups as needed:

# Config only
php artisan live-chat:publish --tag=config

# Migrations only
php artisan live-chat:publish --tag=migrations

# Blade views (for customisation)
php artisan live-chat:publish --tag=views

# Public JS/CSS assets
php artisan live-chat:publish --tag=assets

# Everything at once
php artisan live-chat:publish --tag=all

# Force overwrite existing files
php artisan live-chat:publish --tag=views --force

Database Tables

Table	Description
`chat_conversations`	Each chat session (guest or authenticated user)
`chat_messages`	Individual messages within a conversation
`chat_agents`	Tracks which users are agents and their online status
`chat_settings`	Key/value store for dynamic settings

All tables use the prefix defined by LIVE_CHAT_TABLE_PREFIX (default: chat_).

Security

All routes are protected by CSRF
Guest conversations are authenticated via a per-session X-Chat-Token header
Agent routes require the configured middleware (default: auth)
Messages are XSS-sanitised with Laravel's e() helper before broadcast and rendering
Message sending is rate-limited (default: 30 per minute per conversation)
Pusher private channel authorisation is required to join any conversation channel
SQL inputs are parameterised via Eloquent

Troubleshooting

Widget not showing

Check LIVE_CHAT_ENABLED=true in .env
Ensure your layout has a </body> closing tag (auto-inject requires it)
If using a custom layout without </body>, use @livechat directive and set LIVE_CHAT_AUTO_INJECT=false

Real-time not working

Confirm .env broadcasting credentials are correct
Run php artisan config:clear after changing .env
For Reverb: ensure php artisan reverb:start is running
Check browser console for WebSocket errors (usually auth failures or wrong credentials)
Ensure meta[name="csrf-token"] is present in your layout's <head>

403 on private channels

For authenticated users: ensure Laravel's default /broadcasting/auth route is accessible
For guests: the package provides its own /live-chat/broadcasting/auth endpoint — verify the route prefix matches

Migrations fail

If you changed LIVE_CHAT_TABLE_PREFIX, edit the published migration files to use your prefix before running migrate
Run php artisan migrate:fresh in development to reset

Agent panel shows 404

Run php artisan route:clear
Ensure the user is authenticated and the admin middleware is satisfied

Changelog

v1.0.0

Initial release

License

MIT — see LICENSE

hexalogicdev / live-chat-module

Maintainers

Package info

Statistics

Security

README

Features

Requirements

Installation

1. Install via Composer

2. Run the install command

3. Add environment variables

4. Done!

Broadcasting Server Setup

Option A — Pusher.com (easiest)

Option B — Laravel Reverb (self-hosted, free)

Option C — Soketi (self-hosted, free)

Admin / Agent Panel

Agent features

Configuration Reference

Manual Widget Placement

Publishing Resources

Database Tables

Security

Troubleshooting

Widget not showing

Real-time not working

403 on private channels

Migrations fail

Agent panel shows 404

Changelog

v1.0.0

License