Docs/Configuration

Post-Install Configuration

After the installer finishes, the application still needs runtime configuration before it is production-ready. This page covers workspace setup, settings, mail, queues, storage, AI provider configuration, and the operational checks that should be completed before embedding the widget on a public site.

Default runtime
The application is shipped as a shared Laravel 12 installation with database queue support, workspace-aware settings, and OpenAI-only AI provider support.

Recommended order
Complete settings, verify SMTP, start queue workers, create departments, configure the primary widget, and then enable AI.

1) Workspace and Access Model

The system uses a platform/workspace split. Platform administrators can create workspaces and switch context between them. Workspace admins and agents are scoped to a single workspace and only see that tenant's settings, inbox, knowledge, leads, and reports.

Role scope	Typical use	Primary screens
Platform Admin	Create workspaces, verify license, check updates, import demo data.	Platform > Workspaces, Platform Ops
Workspace Admin	Manage settings, widget builder, AI, automations, reports, leads, and integrations.	Dashboard, Settings, Chat menu
Agent	Work the inbox, update status, notes, tags, replies, tickets, and follow-ups.	Chat > Inbox, Tickets, Leads

2) Settings You Should Complete

The Settings module remains the main runtime configuration area for each workspace. Most buyers can finish the first production setup from there without editing `.env` again after installation.

Section	What to configure	Why it matters
General	App name, app URL, timezone, locale.	Used by dashboard copy, generated links, and workspace defaults.
Company	Business name, email, website, legal/public identity.	Appears in widget messages, notification emails, and help center branding.
Branding	Logo, brand colors, sidebar look, login assets.	Makes the admin and widget feel productized for buyers or end clients.
Channels	SMTP plus optional Twilio-related channel settings.	Required for password reset, alerts, and reply-by-email.
Widget	Primary widget defaults, greeting text, AI toggle, and front-end behavior.	Controls the default deployment path for the first chat widget.
OpenAI	API key, model defaults, persona, token and prompt settings.	Required for AI replies, summaries, training, retrieval, and suggestions.

3) Queue, Storage, and Mail

This build relies on queues for background work. File processing, attachments, AI generation, knowledge ingestion, and training are all safer when the queue worker is running.

If attachments upload but AI replies, document training, or lead workflows feel delayed or inconsistent, check the queue worker first.

Recommended runtime commands

php artisan storage:link
php artisan migrate --force
php artisan optimize:clear
php artisan queue:work --queue=default --tries=1

Run php artisan storage:link so chat attachments and uploaded knowledge files are publicly reachable when needed.
Keep QUEUE_CONNECTION=database unless you intentionally switch to another supported Laravel queue backend.
Verify SMTP before enabling password reset, OTP by email, notification alerts, or reply-by-email.
Use a real APP_URL in production so embed code, emails, and help-center links resolve correctly.

4) OpenAI and AI Defaults

OpenAI is the only built-in AI provider in this release. The provider is still wrapped behind service classes so the codebase stays extensible, but the admin UI assumes OpenAI credentials and models.

What to set

API key
System instruction
Model or persona defaults
Max token budget
Debug logging posture

What it affects

AI widget replies
Conversation summaries
Agent suggestions
Embedding generation
Knowledge retrieval prompts

5) Operational Baseline Before Go-Live

Before adding the widget to a real website, create a baseline support desk shape. This reduces the amount of "empty state" configuration buyers have to discover later.

Create at least one department and one reply template.
Review roles and permissions so agents only see what they need.
Create the first widget and whitelist the real customer domain.
Upload at least one FAQ or document source if AI is enabled.
Create one webhook endpoint or API token if the buyer needs external automations.
Import demo data from Platform Ops if you need screenshot-ready sample content.

Production sign-off check

Check	Expected result
Queue worker	No stuck training or AI jobs.
SMTP	Password reset and notification emails deliver successfully.
Widget domain	Bootstrap succeeds from the intended public site only.
OpenAI	Replies and embeddings process without provider errors.
Storage	Chat attachments and uploaded documents are accessible.