# Overview.Admin ## What it does for you Live Chat gives your site a chat widget so visitors can start a conversation. In the admin, you create the chat installation, add staffed hours, define escalation rules and knowledge-source metadata, then review and route conversation records. ## Your screens - **Chat sites**: the active site installations used by the widget. - **Availability windows**: the hours your team is available. - **Escalation rules**: conditions that assign a priority and route for a chat. - **Knowledge sources**: a site-scoped catalogue of potential source records. - **Conversations**: conversation status, visitor details, routing, and generated operator metadata. The current resource does not display the message transcript. ## What you can do - Create the active chat site that the widget uses. - Set the hours your team is available. - Route chats that meet an escalation condition. - Record knowledge-source metadata and choose whether an installation may also use Knowledge Base content. - Update conversation status, intent, priority, and route; generate an operator summary or suggested reply; sync a Contact; request handoff; or close a conversation. ## Where to find it Go to **Live Chat** in the admin to manage chat sites, availability, and conversations. ## Set up the widget 1. Create one active **Chat site** for the Capell site, choose its source policy and timezone, and save it. A public key is generated automatically. 2. The package auto-injects its widget into the frontend body by default, except on configured ignored paths such as `/admin*` and `/live-chat*`. If it does not appear, check that the package is installed, the site has an active installation, auto-injection is enabled, and the theme renders the body-end hook. 3. For an external embed, add every permitted host to **Allowed domains** and give the generated public key to the integrator. External widget and API requests require that key and a matching `Origin` or `Referer`; `*` is rejected in production. Same-site writes require a matching request origin and an active installation. External and same-site conversations also require the browser's visitor token, and later message and handoff requests must present the same token. The public write routes are CSRF-exempt because they use these checks, are rate-limited by IP, and return private `no-store` responses. If a site has more than one active installation, same-site chat uses the oldest one. Keep only the intended installation active so its source policy and conversation ownership are predictable. ## Permissions and site access The five resources are scoped to sites assigned to the operator; non-global operators cannot save a record for another site or create a shared record without a site. Grant the corresponding `View`, `Create`, `Update`, and `Delete` permissions for `LiveChatInstallation`, `LiveChatAvailabilityWindow`, `LiveChatEscalationRule`, and `LiveChatKnowledgeSource` as required. Conversations cannot be created or deleted through the admin. `View:LiveChatConversation` opens the list, and `Update:LiveChatConversation` controls the edit page. However, the custom row actions for summary, suggested reply, Contact sync, handoff, and close currently have no separate update authorisation. A user who can view the conversation list can trigger them, so grant the view permission only to operators trusted with those state changes and the decrypted visitor data. ## Availability and escalation - Availability is evaluated in the conversation timezone supplied by the browser, or the package default when none is supplied. The timezone saved on an availability window is not currently used to convert the comparison clock. Keep the configured default, installation, and window timezones consistent. - Active admin windows are additive. When no window matches, the runtime still checks the developer-configured weekly business hours, which default to Monday-Friday 09:00-17:00. Disabling all admin windows therefore does not necessarily make chat unavailable. - Date-specific availability exceptions take precedence, but there is no admin screen for them in the current package. A developer must manage those records or configuration for holidays and exceptional closures. - After hours, the visitor receives the configured offline message and the conversation moves to **Waiting for human** on the default queue. The offline wording is not editable in the admin. - Stored escalation rules currently evaluate only **Keyword**, **Intent**, and **Low confidence** triggers. **After hours** and **Manual** options in the rule form are handled by built-in flows and never match as stored rules. - A site-specific rule is considered before shared rules. Priority is the priority assigned to the conversation, not rule ordering; avoid overlapping rules at the same scope. An assignment queue is only a routing label. Handoff changes status, priority, timestamps, and Contact activity, but the package does not send an email, alert an agent, or provide a live operator reply channel. Monitor **Conversations** or connect an external support workflow. ## Conversations, Contacts, and suggested replies The admin edit screen shows conversation fields and stored operator summary/suggestion metadata, not the underlying message transcript. **Suggest reply** saves a draft into encrypted conversation metadata; it does not send anything. Follow up through your normal support channel. Once a visitor supplies a name, email address, or phone number, Live Chat automatically syncs the person to Contacts after message processing; handoff and close also sync. The Contact activity includes the transcript and may create a lead for sales or escalated chats. This is based on the presence of identity details, not the processing- or marketing-consent flags, so make sure the widget's consent wording and your lawful basis cover this processing. Closing a conversation makes it eligible for retention cleanup. It does not delete the linked Contact, lead, or copied Contact activity. ## Knowledge and responder behavior - Creating a **Knowledge source** in the admin saves type, key, title, URL, status, and scope only. The form has no content field and does not call the indexing action, so the record alone cannot ground a chat answer and **Last synced** will not advance. - The default public responder is the package's local intent and keyword logic plus already indexed knowledge documents. Installing AI Orchestrator registers Live Chat capabilities but does not replace that responder or turn public replies into provider calls. - With an installation set to **Manual and Knowledge Base**, installed Knowledge Base articles from its AI-readable output are indexed lazily during knowledge lookup. There is no operator sync button; source freshness follows that lookup path. - Summary and suggested-reply actions derive their result from stored conversation state and record encrypted AI-run audit rows. Treat every suggestion as a draft. ## Data retention and privacy - Message bodies, visitor identity fields, conversation metadata, attachment metadata, knowledge-source content, knowledge-gap questions, and AI-run payloads are encrypted in the database. Indexed knowledge-document content, page and referrer URLs, routing/status fields, and timestamps are not encrypted. Only index content that is safe for administrators with database access to read. - Uploaded attachments are MIME-checked and default to at most five files of 10 MB each. Their metadata is encrypted, but the files themselves are written as ordinary objects on the configured filesystem disk. Keep that disk private, backed up, and access-controlled. - The daily `capell:live-chat:prune` schedule deletes only conversations closed longer than the configured period, which defaults to 365 days, together with their message rows and stored attachments. Active and **Waiting for human** conversations are never age-pruned, so close completed work and keep Laravel's scheduler running. - When Privacy Center is installed, erasure matches a subject by email and deletes matching Live Chat conversations and attachments. It deliberately leaves the shared Contact and any independently retained Contact activity in place; handle those under the Contacts retention process. ## Good to know - If the responder throws an exception, the visitor receives the assistant-unavailable fallback and the conversation is routed to the default queue at high priority. The failure is logged; no automatic retry is scheduled. - Contact-sync failure after a message is logged and does not roll back the saved conversation. Use **Sync contact** after resolving the Contacts failure. - A handoff records a system message and routing state even though it does not notify a human. Agree an operational queue-monitoring process before launch.