Console and admin reference
This chapter is a map of the KasaDESK web console: every Admin Settings section with its exact labels, the main staff screens, who can open each one, and which chapter has the step-by-step procedure. Use it to find a setting, then follow the link for the full task.
Addresses are shown as paths on your installation, for example /inbox on https://support.example.com.
Who can open whatLink to this section
KasaDESK has four staff roles: owner, admin, supervisor and agent. The console hides screens a role cannot use, and the server checks every request on its own. See Roles and inbox access.
| Screen | Address | Owner and admin | Supervisor | Agent |
|---|---|---|---|---|
| Admin Overview | /admin |
Yes. Their landing page. | Sent to /inbox |
Sent to /inbox |
| Admin Settings | /admin/settings/<section> |
Yes | Sent to /inbox |
Sent to /inbox |
| Inbox | /inbox |
Yes, for the workgroups they belong to | Yes. Their landing page. Every conversation in the workspaces of their workgroups. | Yes. Their landing page. Their own workgroups only. |
| Reports | /reports |
Yes, every workspace | Yes, their workspaces | Sent to /inbox |
Owner-only actions in Agents & Roles: changing an admin’s role and deleting an admin’s account. No one can change the owner’s role or their own role from the table.
Sign-in and first-run screensLink to this section
| Address | Screen | What happens |
|---|---|---|
/ |
Start | A new installation goes to /setup. Otherwise you go to your landing page if signed in, or to /login. |
/setup |
Set up KasaDESK | One-time owner setup with a setup code, owner account, authenticator, organization name and time zone. See Create the owner account. |
/login |
Sign in | Email, Password and Continue, then the authenticator step. Includes Forgot your password? |
/accept-invite |
Invitation | The invitee sets a password from a single-use link. See Invite staff. |
/forgot-password and /reset-password |
Password reset | Sends a single-use reset link by email, only if Security → Account emails has a mailbox. An authenticator code is still required after a reset. |
/session-expired |
Session expired | Shown when your session has ended. Sign in again. |
Two-factor authentication. Owners, admins and supervisors always use an authenticator app. Agents use one when Security → Require authenticator for agents (recommended) is on. A staff member who has not enrolled sees Set up two-factor authentication after entering their password. Recovery codes are managed in the account drawer. See Account menu.
The admin areaLink to this section
The admin header reads KasaDESK Admin and offers Overview, Settings, Inbox and Reports, a light and dark mode switch, your name and Sign out. The footer links to the product site, the documentation and support.
OverviewLink to this section
Overview (/admin) shows a Setup checklist read from the server. Each item is marked Done, Required or Optional and has a Configure link to its settings section.
| Item | Done when |
|---|---|
| Owner security | Your account has an authenticator enrolled. |
| Organization profile | The organization profile exists. The item shows its name. |
| Workspace and workgroup | At least one workspace has a workgroup. |
| Support channel tested and active | At least one channel is enabled and healthy. |
| Invite agents | More than one staff account exists. Optional. |
| Staff login branding | A sign-in theme is published. Optional. |
| AI provider and knowledge | Optional. Done when every workspace with AI switched on uses a connection that passed its test and has at least one published Knowledge article. |
Admin SettingsLink to this section
Open Settings in the admin header. The menu on the left (a Settings sections button on small screens) lists the sections below in this order. /admin/settings opens General.
| Section | Address | Use it to | Procedure |
|---|---|---|---|
| General | /admin/settings/general |
Organization name, support email, default time zone | General |
| Workspaces & Teams | /admin/settings/workspaces |
Brands, workgroups, brand icon, badge colour, callbacks | Configure a workspace |
| Agents & Roles | /admin/settings/staff |
Staff, roles, workgroup membership, MFA resets, call history, invitations | Invite staff |
| Channels & Integrations | /admin/settings/channels |
Connect, verify, route and activate channels | Channels and provider setup |
| Support Hours & SLA | /admin/settings/hours |
Schedules, closures, SLA targets, AI coverage | Support hours and SLA |
| Tags & Canned replies | /admin/settings/productivity |
Shared canned replies and conversation tags | Shared canned replies and conversation tags |
| AI & Models | /admin/settings/ai |
AI provider connections, model routing, workspace AI mode | Connect an AI provider |
| Knowledge | /admin/settings/knowledge |
Articles, unanswered questions, reference files | Knowledge and AI |
| Branding | /admin/settings/branding |
Staff sign-in screen look, logo and favicon | Branding |
| Appearance | /admin/settings/appearance |
Agent console theme and per-brand customer chat theme | Per-brand widget appearance |
| Security | /admin/settings/security |
Agent MFA policy and the mailbox for account emails | Security |
| Developer | /admin/settings/developer |
API keys, webhooks, customer records, developer docs | Developer API, webhooks and customer records |
| Storage | /admin/settings/storage |
S3-compatible storage for new attachments and off-site backups | Storage |
| Retention | /admin/settings/retention |
Deletion rules, legal holds, operational clean-up | Retention |
| Audit log | /admin/settings/audit |
Security and configuration events | Audit log |
Most panels show a short confirmation, such as Saved or Policy updated, after each action, and an error message in the same place when the server refuses.
GeneralLink to this section
Panel Organization: One organization per installation. Brands are managed as workspaces.
- Name, Support contact email and Default time zone (IANA), for example
Africa/Accra. - Save changes.
Workspaces & TeamsLink to this section
Panel Workspaces (brands) lists each workspace with Upload icon (or Replace icon and Remove icon), Inbox badge colour, Allow callback requests in web chat, Save workspace settings, Widget appearance, its workgroup chips with member counts, New workgroup name with Add, and Delete workspace.
Panel Add workspace: Brand name, Inbox badge colour, Create workspace.
- Delete workspace asks for confirmation and archives the brand: its channels and workgroups close and conversation history is kept. API keys lose access to it.
- Widget appearance opens Appearance → Customer chat with that workspace selected.
Full procedure: Configure a workspace.
Agents & RolesLink to this section
Panel Staff, a table with Name, Role, MFA, Workgroups and Actions:
- Role: Agent, Supervisor or Admin. Changing a role signs that person out. The notice reads … is now Supervisor. Their sessions were signed out.
- MFA: Enrolled or Not enrolled.
- Workgroups: one chip per Workspace › Workgroup. Select a chip to add or remove membership.
- Actions: Disable or Enable, Reset MFA (confirm with your own password in Confirm with your password to reset MFA), and Delete account once the account is disabled.
Panel Call history: choose a Staff member, or Unassigned incoming calls, to review Twilio calls on voice routes you can access.
Panel Invite staff: Name, Email, Role, Workgroups, Create invitation. The Invitation link (shown once) is valid for 72 hours. Share it privately.
Full procedure: Invite staff.
Channels & IntegrationsLink to this section
- Channel catalog: one card per channel type, such as Web chat, Email, Messenger & Instagram and each provider in your release, with Connect or Connect another. A provider that cannot be connected in your build shows Why is … not available? with the reason.
- Connected channels: each saved channel with its workspace, address, Active, Inactive or Needs workspace assignment, last inbound time, health and Manage.
Connecting opens a guided setup at /admin/settings/channels?connect=<type>. Manage opens the channel at /admin/settings/channels?channel=<channel ID>. Depending on the channel type, the channel page has panels such as Health and activity, Test and status, Webhook, Credentials and settings, Install and secrets, Brands on this channel, Live check, Message templates, WhatsApp calling and Remove channel. Secrets are write-only: leave a secret blank to keep it.
Full procedure: The channel lifecycle.
Support Hours & SLALink to this section
- Schedules: one schedule per scope. The most specific schedule wins: channel, then workgroup, then workspace, then organization. The organization schedule is the fallback.
- Add an override: Scope (Workspace, Workgroup or Channel), the target and Create override. The override starts as a copy of the selected schedule.
- The schedule editor: Time zone (IANA), Weekly hours (24-hour times, up to six intervals a day, Add hours, Copy Monday to Tue–Fri), Holidays and closures (From, Until (optional), Label, Add closure), AI coverage, First response target (business minutes), Next response target (business minutes, optional) and SLA at-risk warning (minutes before due, 0 = off). Then Save schedule, Discard changes, or Delete override.
- Preview: choose a scope and an optional Check at time to see which schedule applies, whether it is open, whether AI coverage is active, the next opening and the due times a new conversation would get.
Saving hours or targets recalculates the due time of open conversations whose clock is still running. The assignee and the workgroup are alerted when a conversation is at risk and when it breaches. AI coverage applies only to workspaces in Autopilot mode.
Tags & Canned repliesLink to this section
Two tabs:
- Shared canned replies (shown first): workspace snippets that agents insert with
/or the canned-reply button. Inserting never sends. - Conversation tags: workspace tags with a colour. Agents add and remove them on conversations. Only admins create, rename or delete them. Deleting a tag removes it from every conversation.
Full procedure: Shared canned replies and conversation tags.
AI & ModelsLink to this section
Server encryption must be configured to save provider keys.
- Provider connections: Add connection with Name, Provider type, Base URL, Model name and API key, plus an optional Voice dictation (speech-to-text) model and, for OpenRouter, OpenRouter app attribution (optional). Each saved connection offers Test connection, Edit (with Load models from provider), Add another and Delete. Delete is unavailable while the connection is in use.
- Shared model routing: one chain each for Copilot, Autopilot, Voice dictation and Dictation cleanup. Choose a tested primary model and up to three fallbacks.
- Workspace AI: per workspace, AI mode (Off, Copilot (drafts for agents to review) or Autopilot (replies to customers)), Keep original dictation transcript, Allow voice dictation when AI is Off, and Save.
- Recent autopilot runs: queued time, workspace, result, models tried, number of articles used and an Open link to the conversation. Message text is never shown.
Changing a connection’s type, base URL, model or key clears its test result, and Autopilot pauses for the workspaces using it until a new test succeeds. Full procedure: Connect an AI provider and AI modes per workspace.
KnowledgeLink to this section
Four tabs:
| Tab | Contents |
|---|---|
| Articles | Filter by Workspace, Status (Published or Draft) and Search. Each row has Edit and Delete. Deleting an article also deletes its linked reference file. |
| New article | Article workspace, Publication (Draft (admins only) or Published (agents can read)), Title, Tags (comma-separated), Body (Markdown), Preview and Create article. |
| Unanswered questions | Choose the Question workspace and Question status (Open or Answered). Each question has Open conversation, Write answer or Edit answer, and Review and publish for a draft answer. The answer editor offers Generate draft and Save answer draft. |
| Reference files | Turn documents into Knowledge articles. See below. |
What Reference files do:
- Choose the Reference workspace. Files and the articles made from them belong to that workspace only.
- Choose up to 10 files at a time, up to 5 MiB each, in text-based PDF, TXT, DOCX or Markdown, and select Upload files. Uploading only queues them as Pending. No article exists yet, and nothing is available to agents or AI.
- Select Convert and publish. KasaDESK extracts each file’s text on the server and creates one published article per converted file. Those articles, not the files, are what agents and AI replies use.
- Each file row shows its Conversion status (Pending, Converted or Failed with the reason), the linked article, and Retry conversion, Edit article, Download .md and Remove. Removing a converted file also deletes its article.
Full procedure: Convert reference files into articles and Unanswered questions.
BrandingLink to this section
Panel Staff authentication screens styles the login, two-factor, invitation and recovery screens for the whole organization. It never changes security behaviour.
- Display name, Tagline, Primary colour, Mode (Follow device, Light or Dark), Layout (Centered or Split panel) and Background (Soft glow, Solid or Grid).
- Logo: PNG, JPEG or WebP, up to 1 MB, at least 32×32 pixels.
- Favicon: square PNG or ICO, up to 256 KB, at least 16×16 pixels. It is also the organization icon at the top left of the inbox.
- Save draft keeps changes private. Publish applies them. Reset to default restores the KasaDESK look.
Panel Preview shows the sign-in screen with your draft, in light or dark.
AppearanceLink to this section
Two tabs. A link at the top points to Branding for the sign-in screens.
| Tab | Address | Contents |
|---|---|---|
| Agent console | /admin/settings/appearance |
Agent console theme: Default mode for staff who have not chosen one, then colour fields for the Light theme and Dark theme. Preview shows a miniature inbox. Staff can still switch light or dark for themselves. |
| Customer chat | /admin/settings/appearance?tab=chat |
Choose the Workspace, then edit Customer chat theme: workspace: Bubble and button colour, Text on bubbles and buttons, Header colour, Header text, Launcher position (Bottom left or Bottom right), Support display name, Greeting and Chat mode. Light and dark previews. |
Both tabs use Save draft, Publish, Revert (the previous published version) and Reset to original. Every text colour must reach the WCAG AA contrast minimum of 4.5:1 against its background. When a pair falls short, the box Some text would be hard to read lists it with one-click fixes, such as a darker or lighter shade of the background or white or black text. Save draft and Publish stay disabled until every pair passes, and the server refuses a failing theme. A customer chat theme applies to one workspace only. A Web Chat channel’s own primary colour overrides it for that channel.
SecurityLink to this section
- Panel Multi-factor authentication: Owner, admin and supervisor accounts always require an authenticator app. The switch Require authenticator for agents (recommended) sets the policy for agents.
- Panel Account emails: Send account emails from lists email channels that have outbound sending enabled and a passed outbound test. Password reset links are sent from the chosen mailbox. With Not configured (no account emails), Forgot your password? sends nothing.
To offer password resets, connect a mailbox first. See Email.
DeveloperLink to this section
Two tabs:
- API & integrations (
/admin/settings/developer): panels Public API (this installation’s base URL and OpenAPI document), API keys, Webhooks (with Send test, Disable or Enable, Rotate secret, Delivery log and Delete) and Customer records. - Developer docs (
/admin/settings/developer?tab=docs): in-product documentation with the sections 1. Public API, 2. API keys, 3. Webhooks and 4. Customer records, under a contents box that stays in view while you scroll.
API keys and signing secrets are shown once. Full reference: Developer API, webhooks and customer records.
StorageLink to this section
- Panel Storage shows where New chat attachments go (local storage or a bucket) and whether Settings-managed off-site backups are on, with Use local storage for new attachments and Turn off settings-managed backups when they apply.
- Panel S3-compatible destination: Saved destination, Provider (Cloudflare R2, Amazon S3, Contabo S3-compatible or Other S3-compatible), Bucket, then S3 API endpoint, AWS region, Signing region, Contabo location or Use path-style addressing as the provider requires, Access key ID, Secret access key, Store new chat attachments here and Send scheduled off-site backups here. Actions: Verify and save, Test connection and Update credentials only.
Use a private bucket. Existing chat files stay where they were stored. Off-site backups also need the backup scheduler running, and an explicit deployment backup setting takes precedence. See Keep a copy off the host.
RetentionLink to this section
The page opens with Deletion is permanent: data removed by a retention run cannot be restored from KasaDESK, older backups keep it until they age out, and nothing is deleted until you turn a rule on.
| Panel | Contents |
|---|---|
| Workspace policies | Each workspace’s rules and legal hold, with Edit. New workspaces start with every rule off. |
| Policy: workspace | Resolved conversations (delete with messages, email records and attachments after Days after resolution) and Attachments only (delete files after Days after upload), Save policy and Preview these settings. Turning on or shortening a rule asks you to review the counts and confirm. The panel also holds Workspace legal hold (Hold reason, Place workspace hold, Release workspace hold). |
| Dry-run preview | Run preview counts what a run would delete now with the saved policies. It never deletes anything. |
| Conversation legal holds | Held conversations with Release. Place a hold with Conversation ID, Reason and Place conversation hold. |
| Operational clean-up | Purge expired operational records: old widget and sign-in sessions, login attempts, delivered outbox jobs, finished webhook deliveries and finished autopilot run records, on fixed age limits. It never touches conversations, messages, attachments or the audit log. |
| Retention runs | The last run and recent runs with their trigger, status and counts. |
See Data retention.
Audit logLink to this section
Panel Audit log: the 200 most recent security and configuration events, with When, Action, Actor, Target and IP. Secrets and codes are never recorded. The log is append-only and retention never deletes it. Examples of actions include api_key.created, webhook.secret_rotated and customer_context.lookup.
The staff inboxLink to this section
The inbox is at /inbox. A link to one conversation has the form /inbox?c=<conversation ID>. It opens only for staff who may see that conversation. The full guide is Staff inbox and notifications.
Navigation and viewsLink to this section
The left column shows the organization icon and name, then:
- Inbox: Unassigned, Mine, Needs human, Unread and All open, each with a count.
- Views: Urgent, Waiting on customer, Snoozed, Resolved, SLA at risk, SLA breached, and SLA report for supervisors and admins.
- Workspaces: each workspace and its workgroups, with open counts. Staff who belong to no workgroup see You are not a member of any workgroup yet.
- Channels (collapsed by default): each channel you can see, with its open count.
- At the bottom: your name, your availability, a Connecting… or Reconnecting… note when the live connection is down, and the Account menu.
ConversationsLink to this section
| Area | What you can do |
|---|---|
| Conversation list | Search by name, text or full reference such as T-0000C. Filter, filter by tag and sort. Select conversations for bulk assign, resolve, reopen, tag and snooze. |
| Thread | Read messages, events and internal notes. Change assignee, status, Snooze, tags, and use the … menu to move to another workgroup. |
| Composer | Reply sends through the conversation’s own channel. Note adds an internal note that never leaves KasaDESK. The toolbar offers canned replies, Search knowledge, attachments and, where enabled, AI drafting, cleanup and voice dictation. |
| Customer details | Customer identity and verification, channel, workgroup, handling state, assignee, priority, first response, past conversations and, for verified customers on a connected site, Customer records. |
New conversations start in their channel’s default workgroup, where staff take them or assign them to teammates in that workgroup. Supervisors can reassign within their workspaces. See Route conversations.
Presence. Each staff member sets Available, Busy, Away or Offline in their profile. The profile notes that availability affects new assignments only and never hides assigned conversations. Inside a conversation, the inbox also shows when a teammate is viewing it or typing.
Voice. When Twilio Voice or WhatsApp calling is connected, calls ring in the browser inbox for available staff with the tab open. Account menu → Call history lists your calls. Admins review everyone’s calls in Agents & Roles → Call history. See Calls in the inbox.
ReportsLink to this section
Reports (/reports) shows the SLA report: Service level by workspace for a Period of Last 24 hours, Last 7 days, Last 30 days or Last 90 days.
| Column | Meaning |
|---|---|
| Workspace | Admins see every workspace. Supervisors see the workspaces they supervise. |
| Open | Open conversations now. |
| At risk | Conversations inside the SLA warning window now. |
| Breached now | Conversations past their due time now. |
| First response met | Percentage and count of conversations created in the period whose first-response clock has finished. |
| Breach alerts | First- and next-response breach alerts raised in the period. |
Back returns admins to /admin and supervisors to /inbox. Agents cannot open reports.
Account menu and drawerLink to this section
In the inbox, the Account menu at the bottom of the navigation offers Profile, Account, Inbox notifications, Call history and Sign out. Each item except Sign out opens the account drawer, which has the tabs Profile, Account, Call history and Alerts. Inbox notifications opens the Alerts tab.
| Tab | Contents |
|---|---|
| Profile | Name, email and role. Profile photo (PNG, JPEG or WebP, up to 1 MB, at least 64×64 pixels, shown to your team and never to customers). Availability. Continue on phone, offered when a conversation is open. Appearance (Light or Dark). Install KasaDESK. Admin settings for owners and admins. |
| Account | Change password (12 or more characters, other sessions are signed out), Two-factor authentication with New recovery codes (confirmed with your password; old codes stop working), Active sessions with Sign out other sessions, and Sign out. |
| Call history | Calls you placed or answered on voice routes you can access. Selecting one opens its conversation. |
| Alerts | Your Inbox alerts, Inbox message sound and background alert enrollment. |
Staff inbox notificationsLink to this section
Each staff member turns alerts on for their own account under Account menu → Inbox notifications. Both settings start off. Alerts follow the account across browsers and the staff phone app. Background browser alerts need Web Push configured by the operator. See Inbox alerts and Operator setup for background alerts.
Smoke checksLink to this section
Run these on a test installation with synthetic accounts, one per role. Each expected result is the console’s own behaviour.
- On a new installation,
/goes to/setup. After setup, a signed-out visit to/goes to/login. - The owner signs in with password and authenticator and lands on Overview at
/admin. The checklist shows Required for anything missing. -
/admin/settingsopens General, and the menu lists the 15 sections in the order of the table above. - An agent and a supervisor who open
/admin/settings/staffland on/inbox. - A supervisor sees SLA report under Views, and
/reportslists only their workspaces. An agent has no SLA report link, and/reportssends them to/inbox. - A new agent without an authenticator sees Set up two-factor authentication at sign-in when Require authenticator for agents (recommended) is on.
- With Account emails on Not configured (no account emails), Forgot your password? sends no email. After you choose a tested mailbox, a reset email arrives.
- Changing a test agent’s role shows … Their sessions were signed out., and the agent must sign in again.
- In Knowledge → Reference files, an uploaded file shows Pending. After Convert and publish it shows Converted, and its article appears under Articles as Published.
- Retention → Run preview shows counts and Preview updated. Nothing was deleted.
-
/admin/settings/developer?tab=docsreloads on Developer docs, and/admin/settings/appearance?tab=chatopens Customer chat. - Creating and revoking a test API key adds
api_key.createdandapi_key.revokedto the Audit log. -
/inbox?c=<conversation ID>opens the conversation for its assignee, and shows nothing for an agent outside its workgroup. - Account menu → Inbox notifications opens the drawer on Alerts.