# ClientSphere Docs
> ClientSphere is a CRM with support and marketing built in: accounts and contacts, a sales pipeline, a tickets inbox and live chat, broadcasts and sequences, quotes and invoices, and a REST API.
This is the product manual, in three tracks: Set up is for the person who administers a workspace, Use is for everyone on the team, Build is for developers. Each guide covers one screen, the rules it enforces, and the messages it can show.
---
Track: Introduction
# Overview
Source: https://app.clientsphere.io/docs
Set up your workspace, learn everyday work in ClientSphere, or build against the API.
ClientSphere keeps sales, support, email and invoicing in one place. The
documentation is in three tracks, one for each kind of reader.
- [Set up](https://app.clientsphere.io/docs/setup): For the admin configuring the workspace: your team, email sending, inboxes, working hours and SLAs. Read once, in order.
- [Use](https://app.clientsphere.io/docs/use): For everyone on the team: contact lists, broadcasts, the tickets inbox and the sales inbox, one task at a time.
- [Build](https://app.clientsphere.io/docs/build): For developers: the REST API, API keys, the Support Hub and floating launcher embeds.
## If you are new
Start with [Create your workspace and invite your team](https://app.clientsphere.io/docs/setup/workspace/workspace-and-team),
then [Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending). Everything that sends
email, from a broadcast to a ticket reply, depends on that second page.
## Reading these docs with an AI
The whole manual is also available as plain text: [llms.txt](https://app.clientsphere.io/docs/llms.txt)
is an index of every page, and [llms-full.txt](https://app.clientsphere.io/docs/llms-full.txt) has the
full text of every guide. Point an assistant at either instead of pasting
pages.
# What is ClientSphere
Source: https://app.clientsphere.io/docs/introduction/what-is-clientsphere
One workspace for the whole client relationship, and how its parts fit together.
ClientSphere keeps sales, support, email and invoicing in one place, so the
people talking to a client all see the same history. It is priced by the
clients you manage, not by seats, so the whole team can be in it.
## The parts
| Area | What lives there | Who uses it |
|---|---|---|
| **CRM** | Leads, accounts, contacts, opportunities, tasks, and the sales inbox | Sales |
| **Support** | Tickets, live chat, feature requests, and the knowledge base | Support |
| **Email** | Contact lists, broadcasts, transactional email, and opt-outs | Marketing and operations |
| **Automation** | Sequences and triggers | Sales and marketing |
| **Finance** | Quotes, invoices, payments, and products | Finance |
| **Analytics** | Reports and product analytics | Managers |
Everything hangs off the **account**, which is a client company, and its
**contacts**, the people there. A ticket, a deal, an invoice, and an email
thread all point back to the same account, which is what makes the history
one history.
## How things get in
- **People type them in**, or import spreadsheets of accounts, contacts, or
contact lists.
- **Email arrives** at support and sales channels you forward your mailboxes
to, and becomes tickets or sales inbox items.
- **Your website and product** feed it through the Support Hub chat widget
and the floating launcher, which identify visitors and create contacts.
- **Your own systems** use the REST API, with keys you scope yourself.
## Two things worth knowing on day one
- **Roles decide what people see.** A menu group with nothing the role can
do in it disappears entirely. See
[Create your workspace and invite your team](https://app.clientsphere.io/docs/setup/workspace/workspace-and-team).
- **Sandbox mode** is a view of test data inside the same workspace. A
banner shows while it is on, and everything created then is test data.
## Where to go next
[Quick start](https://app.clientsphere.io/docs/introduction/quick-start) gets a new workspace receiving and
sending email in an afternoon. The [Set up](https://app.clientsphere.io/docs/setup) track has the full
detail for each step.
# Quick start
Source: https://app.clientsphere.io/docs/introduction/quick-start
From an empty workspace to answering tickets and sending a broadcast, in the order the pieces depend on each other.
This is the shortest path from sign-up to a working workspace. Each step
links to the guide with the detail. Budget an afternoon, most of it waiting
for DNS and for your email provider to confirm forwarding.
## 1. Create the workspace and invite the team
Sign up, create the company, and invite people with a role. Roles decide
which menus each person sees, so give reps and agents the **Sales Rep** and
**Support Agent** roles rather than Admin.
→ [Create your workspace and invite your team](https://app.clientsphere.io/docs/setup/workspace/workspace-and-team)
## 2. Verify a sending domain
Add your domain under **Settings → Email sending**, publish the DNS records
it gives you, and re-check until it reads **Verified**. Then create a sending
address on it. Nothing that sends email works before this, so do it first
and let DNS propagate while you do the rest.
→ [Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending)
## 3. Connect your support and sales mailboxes
Create a support email channel, forward your support mailbox to the inbound
address it gives you, and send a test. Do the same for sales. Tickets and
the Sales Inbox fill up from here.
→ [Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox) ·
[Connect a sales inbox](https://app.clientsphere.io/docs/setup/email/sales-inbox)
## 4. Set working hours and an SLA
Set the hours your team works, then a first-reply target per channel and
how new items are assigned. Without working hours, every overnight ticket
breaches before anyone is in.
→ [Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment)
## 5. Bring in your contacts
Import a spreadsheet as a contact list, or add accounts and contacts by
hand. Decide whether the rows are people or companies before you upload;
it changes what the list means.
→ [Import a list from a spreadsheet](https://app.clientsphere.io/docs/use/email/import-a-list) ·
[Build a contact list](https://app.clientsphere.io/docs/use/email/contact-lists)
## 6. Send something and answer something
Send a first broadcast to a small list, with a test to yourself first. Open
the tickets inbox and reply to the test ticket from step 3.
→ [Send your first broadcast](https://app.clientsphere.io/docs/use/email/send-a-broadcast) ·
[Work the tickets inbox](https://app.clientsphere.io/docs/use/support/tickets)
## What you can leave for later
The website embeds, AI drafting and auto-reply, sequences and triggers,
invoicing, and the API. Each has its own guide and none of them block the
six steps above.
---
Track: Set up
# Setup overview
Source: https://app.clientsphere.io/docs/setup
Configure a ClientSphere workspace in the order the features depend on each other, and know which steps are optional.
These pages are for the person who administers the workspace. Most need a
role with **Manage integrations** or **Manage company settings**; if a
Settings section is missing for you, that is why.
## The order that matters
Five steps depend on each other, and doing them in this order means
nothing waits on something later. They are the same five as the
[Quick start](https://app.clientsphere.io/docs/introduction/quick-start), with the full detail behind each.
1. [Create your workspace and invite your team](https://app.clientsphere.io/docs/setup/workspace/workspace-and-team).
Roles decide what people can see, so set them before inviting.
2. [Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending). Verify a domain and
add a sending address. Broadcasts, sequences, transactional email, and
ticket replies all wait on this, and DNS takes time, so start it early.
3. [Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox) and
[a sales inbox](https://app.clientsphere.io/docs/setup/email/sales-inbox). Forwarded mail becomes
tickets and sales conversations.
4. [Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment).
Without working hours, every overnight ticket breaches before anyone
is in.
5. [Import your data](https://app.clientsphere.io/docs/setup/workspace/import-your-data), so the team
starts with real accounts and contacts rather than an empty CRM.
Everything after that can be done in any order, when you need it.
## Workspace
- [Create your workspace and invite your team](https://app.clientsphere.io/docs/setup/workspace/workspace-and-team): Sign up, create the company, invite people with a role, and what a role shows and hides.
- [Customise your CRM](https://app.clientsphere.io/docs/setup/workspace/customise-your-crm): Pipeline stages, account and task statuses, and ticket modules. Set them before the data arrives.
- [Import your data](https://app.clientsphere.io/docs/setup/workspace/import-your-data): Accounts and contacts from a CSV with column mapping, or from Zoho CRM.
- [Audit trails](https://app.clientsphere.io/docs/setup/workspace/audit-trails): What changed, who changed it, and how to search the record.
## Email and inboxes
- [Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending): Verify a domain, publish its records, create a sending address. Everything that sends waits on this.
- [Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox): Turn a support address into tickets: create the channel, forward mail to it, confirm.
- [Connect a sales inbox](https://app.clientsphere.io/docs/setup/email/sales-inbox): The same for inbound sales email, so it lands in the Sales Inbox with an SLA.
- [Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment): The hours the SLA clocks run, response targets per channel, and how new items get an owner.
- [Connect Gmail](https://app.clientsphere.io/docs/setup/email/connect-gmail): Link a personal mailbox to send from it and log conversations, and control what is synced.
## Your site and product
- [Put the Support Hub on your site](https://app.clientsphere.io/docs/setup/site/support-hub): Create a support channel, choose the cards visitors see, and get the embed code.
- [Put the floating launcher on your product](https://app.clientsphere.io/docs/setup/site/floating-launcher): The pill button and its menu, installed with the user's identity so Product Analytics fills up.
- [Publish your knowledge base](https://app.clientsphere.io/docs/setup/site/publish-knowledge-base): Public access, who can publish, branding, and your own domain.
## AI and developers
- [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai): Every AI switch in one place, and the order to turn them on so it answers well and stays quiet when it should.
- [API keys, logs and MCP](https://app.clientsphere.io/docs/setup/ai-and-developers/api-keys-and-mcp): Issue and scope keys, watch their requests, and connect an AI assistant to your data.
- [Sandbox mode and test data](https://app.clientsphere.io/docs/setup/ai-and-developers/sandbox-mode): What sandbox is, how to get a test API key, and how to clear test data.
## When something is not working
Every guide ends with a **When it goes wrong** section listing the exact
messages the screen shows and what each means. If a page in the app is
unexpectedly empty, the usual causes are a missing prerequisite from the
list above or a role without the permission; the guide for that screen
says which.
# Create your workspace and invite your team
Source: https://app.clientsphere.io/docs/setup/workspace/workspace-and-team
Sign up, create the company, invite people with a role, and understand what a role shows and hides.
A workspace is a company in ClientSphere. Everything, from contacts to
sending domains, belongs to one. A person can belong to several and switches
between them from the user menu.
## Sign up and create the company
1. Go to `/auth` and click **Create an account**. First name, last name,
work email, and a password of eight or more characters.
2. You land on **Select a Company**. Click **Create New Company** and fill
in the name, industry, and company size. All three are required.
There is no way into the product without a company. If you ever see the
company picker instead of the dashboard, that is why.
Later, under **Settings → Company**, add the details that show up elsewhere:
the logo and icon, the website, the timezone, and the address that goes on
invoices.
## Invite your team
Under **Settings → Users**, click **Add User**. First name, last name, email,
and a **Role**. The person receives an invitation email and sets a password
on the invitation page, which shows them the company and the role they were
given.
[Screenshot: The Add New User dialog: first name, last name, email, and role]
Two things about users:
- **Email cannot be changed** after the account exists. Get it right in the
invitation.
- **Deactivate, don't delete.** Deactivating removes access and keeps
everything the person did. The **Inactive Users** tab lists them, and
they can be reactivated from **Edit User**.
You cannot deactivate yourself.
## Roles decide what people see
Every menu group in the sidebar is filtered by permission, and a group with
nothing visible in it disappears entirely. A rep without **Send
broadcasts**, **Manage contact lists**, or **Manage email automations** does
not see a greyed-out Email menu; they see no Email menu at all. When someone
says a feature "disappeared", check their role first.
**Settings → Roles & Permissions** ships with five roles: **Owner**,
**Admin**, **Manager**, **Sales Rep**, and **Support Agent**. Create your own
with **Create New Role**, pick a **Quick Template** to start from one of the
five, then adjust the checkboxes. The matrix is grouped by area: Contact
Management, Ticket Management, Broadcasts, API, and so on, with a one-line
description under each permission.
[Screenshot: Roles & Permissions with the five system roles and their permission counts]
- The **Owner** role cannot be edited or deleted.
- System roles cannot be deleted. Custom roles can, but deleting one
affects every user assigned to it. Deactivate it instead if you are not
sure.
- Permissions on an API key are separate from roles. See
[API keys](https://app.clientsphere.io/docs/build/guides/authentication).
## Switching companies and sandbox mode
The user menu at the top right has **Switch Company** and a **Sandbox
Mode** switch. Sandbox is a view of test data inside the same workspace,
not a separate login: while it is on, a banner says "Sandbox Mode — Test
data only. Changes here do not affect production." and everything you
create is test data. Turn it off to return to real records.
## Next
[Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending). Nothing that sends email
works until a domain is verified and a sending address exists.
# Customise your CRM
Source: https://app.clientsphere.io/docs/setup/workspace/customise-your-crm
The pipeline stages deals move through, the statuses accounts and tasks can have, and the modules that group tickets. Set them before the data arrives.
Three lists shape how the CRM describes your work: the stages a deal moves
through, the statuses an account or a task can have, and the modules that
categorise tickets. They are yours to define, and every dropdown, filter,
report, and automation condition reads from them.
**Before you start:** a role with **Manage company settings**. Change
these early; renaming a stage after a thousand deals use it is safe, but
removing one leaves those deals showing an unknown stage.
## Pipeline stages
**Settings → Pipeline** shows the stages in order. Click **Edit** to change
them: rename, pick a colour, drag the handle to reorder, **Add Stage**, or
remove one. The last remaining stage cannot be removed. **Save Changes**
applies them.
The defaults are Discovery, Qualification, Technical Evaluation, Proposal,
Negotiation, Closed Won, and Closed Lost. Keep the two closed stages; the
Reports page's pipeline value and won revenue depend on deals reaching
them, and the lead conversion dialog excludes them from its choices.
The stages appear as the kanban columns under
[Opportunities](https://app.clientsphere.io/docs/use/crm/opportunities) and in every stage dropdown.
## Account and task statuses
**Settings → Statuses** has two sub-tabs.
- **Account Statuses**, by default Active, Inactive, Prospect, Customer,
and Churned. Each has a label people see, a value stored on the record,
and a colour. These are what dynamic contact lists and account triggers
filter on, so a status like "Customer" is what makes "email every
customer" possible.
- **Task Statuses**, by default To Do, In Progress, Review, and Done, with
an **Order** that sets how they sort.
Edit, add, reorder, and save the same way as stages. Each list keeps at
least one entry.
## Ticket modules
**Settings → Ticket Modules** defines the product areas tickets are filed
under. Each has a name, an optional description, and a colour; the stored
value is derived from the name. They appear in the ticket form's
**Module** field and in the "Tickets by Module" report.
**A module that tickets use cannot be removed.**
If tickets still reference a module, saving keeps it and tells you which
module was kept and why. Reassign those tickets to another module first,
then remove it.
## When it goes wrong
- **A deal shows "Unknown Stage".** Its stage was removed. Move it to a
current one from its profile.
- **A task's status dropdown looks different from a colleague's.** It
should not; both read the workspace list. One of you has a stale page.
- **The remove button is missing on a stage or status.** It is the last
one in the list. Add another first.
- **"… is still used by tickets and was kept."** Tickets reference the
module; see the note above.
# Import your data
Source: https://app.clientsphere.io/docs/setup/workspace/import-your-data
Bring accounts and contacts in from a CSV with column mapping, or pull them from Zoho CRM. Where the import page lives and what each entity needs.
Two importers bring existing records into the CRM: a CSV import for
accounts and contacts, and a direct import from Zoho CRM. Both live under
**Settings → Import**; there is no entry for them in the main sidebar.
This is for CRM records. To build an email audience from a spreadsheet,
use the contact list importer instead; see
[Import a list from a spreadsheet](https://app.clientsphere.io/docs/use/email/import-a-list). It creates
contacts too, but files them straight into a list.
**Before you start:** a role with **Manage company settings**. For Zoho,
admin access to the Zoho API console.
## CSV import
**Settings → Import → CSV Import** has two tabs, **Import Accounts** and
**Import Contacts**. Do accounts first, so contacts can match them by
company name.
1. Upload a `.csv` with a header row. The page lists the columns each
entity understands:
- **Accounts**: `name` is required; `website`, `industry`, `phone`,
`address`, `size` (small, medium, large, enterprise), and `status`
are optional.
- **Contacts**: `firstName`, `lastName`, and `email` are required;
`phone`, `company`, `jobTitle`, and `source` are optional.
2. **Map CSV Columns** to fields. Each field is matched to a column or
set to **Skip this field**. Required fields are starred and must be
mapped; the import will not start without them.
3. Check the preview of the first rows, then click **Import Accounts** or
**Import Contacts**.
The import runs as a background job. **Recent Import Jobs** shows each
one's progress and, when done, how many were imported, skipped, and
errored.
Accounts are matched by name and contacts by email, so re-running an
## Zoho CRM import
**Settings → Import → Zoho CRM** pulls accounts and contacts from a Zoho
workspace. The page walks through the credentials:
1. In the Zoho API Console, create an app or pick an existing one, and
copy its **Client ID** and **Client Secret**.
2. Generate a **Refresh Token** with the scope `ZohoCRM.modules.ALL`.
3. Enter all three, pick your Zoho **Region** (.com, .eu, .in, .com.au, or
.jp), and click **Test Connection**. A successful test reports how many
accounts and contacts it found.
4. Click **Import Data**. The results card shows imported and skipped
counts per entity, and any errors.
## When it goes wrong
- **"CSV file must have headers and at least one row of data."** The first
row must be column names.
- **"Please map the required fields: …"** The listed fields are starred
and unmapped.
- **Rows were skipped.** Usually a blank required field, or a contact
email that is not an address. The job's error count and the preview's
dashes point at the rows.
- **"Please fill in all Zoho CRM credentials."** All three fields and the
region are needed before testing.
- **"Failed to connect to Zoho CRM."** The refresh token has the wrong
scope, was generated for a different region, or has expired. Generate
a fresh one.
# Audit trails
Source: https://app.clientsphere.io/docs/setup/workspace/audit-trails
The record of what changed in the workspace and who changed it, what it covers, and how to search it.
**Settings → Audit Trails** is a record of changes across the workspace:
who created, updated, or deleted what, and when. It exists for the
questions that come up later: who changed this invoice, when did that
role lose a permission, who deleted the account.
**Before you start:** a role with **View audit logs**.
## What is recorded
Create, update, delete, and bulk update and delete on nearly every kind
of record: accounts and their notes, contacts and their account links,
leads, opportunities, tasks and comments, tickets and comments, ticket
modules, pipelines, documents, quotes, invoices, payments, recurring
billing, knowledge base categories, articles and settings, company
settings, users, invitations, roles, API keys, working hours, imports,
sending and support channels, domain verifications, and quarantined mail.
Each entry shows the action, the record, a summary of what changed with
the fields affected, the user who did it, and the time. Changes made by
the system rather than a person, such as an hourly job, show **System**.
Two limits worth knowing:
- **Sign-ins are recorded only when they fail.** Successful sign-ins are
not in the log.
- **Entries cannot be edited or deleted**, by anyone, including through the
database. The log is append-only by design, and there is no retention
window yet, so it only grows.
## Search it
Search by text, or filter by **Entity Type**, **Action**, user, and a
date range. Filters combine, and the active ones show as chips above the
table. Page size goes up to 100.
## When it goes wrong
- **A change you know happened is not there.** It was made before the
audit trail existed, or it is a type that is not audited, such as a
read or a sign-in.
- **The user column says System.** A background job made the change:
overdue invoices, recurring billing, or an import.
- **You need to remove an entry.** You cannot. That is the point of the
log.
# Set up email sending
Source: https://app.clientsphere.io/docs/setup/email/email-sending
Verify a domain, publish its DNS records, and create a sending address. Broadcasts, sequences and transactional email all wait on this.
Every email ClientSphere sends on your behalf, from a broadcast to a receipt,
goes out from a **sending address** on a **verified domain**. Until both
exist, the Broadcasts and Transactional pages show "Sending isn't set up
yet." This page takes you from nothing to a working address.
**Before you start:**
- A role with **Manage integrations**. Without it you see the notice but not
the **Set up sending** button.
- Access to the DNS for your domain, at your registrar or DNS host. You
will publish a handful of records.
- Fifteen minutes, most of it waiting for DNS.
Everything lives under **Settings → Email sending**.
[Screenshot: The Email sending page: Sender domains above, Sending addresses below]
## Verify a domain
Verifying a domain once covers every address on it, so `support@`,
`sales@` and `billing@` all work without separate confirmation. This is the
recommended path, and it is also the strongest protection against someone
else sending as you.
1. In the **Sender domains** card, type the domain, for example
`yourcompany.com`, and click **Add domain**.
2. The domain appears with a **Pending DNS** badge. Click **DNS records**
to expand them.
3. Publish every record under **Required** at your DNS host. There is a
TXT record that proves this workspace owns the zone, and CNAME records
that let ClientSphere sign your outbound mail so inboxes trust it. Each
row has a copy button that copies the name and value together.
4. Click **Re-check**. Each record shows a green tick when found or a red
cross when not. When all required records resolve, the badge changes to
**Verified**.
DNS usually resolves within seconds, sometimes longer. Re-check is safe to
click as often as you like.
**Two workspaces on one domain.**
The TXT record is different per workspace, so a second ClientSphere
workspace on the same domain publishes its own TXT alongside yours. Nothing
collides.
### Advanced deliverability, optional
Below the required records is an **Advanced deliverability** group with a
**Set up** button. It adds a DMARC policy and a return path on your own
domain, so bounces show `bounce.yourcompany.com` instead of the delivery
provider and your mail authenticates two ways instead of one.
It is optional. Sending works without it, and these records never affect
whether the domain is verified. Turn it on when you are ready to publish
three more records; sending keeps working while you do. If a custom return
path already exists on the domain, the card says so and asks you to add only
the DMARC record.
## Create a sending address
In the **Sending addresses** card, click **New channel**:
- **Channel name (internal)**, for your team, such as "Customer updates".
- **From email address**: any address under the verified domain, or an
address you can receive mail at.
- **From name**: what recipients see, such as your company name.
- **Default reply-to**: where replies go. Each broadcast can override it.
Click **Create channel**. ClientSphere checks the address immediately and
the card tells you what, if anything, is left to do.
[Screenshot: The New broadcast channel dialog]
- On a verified domain the card shows **Verified** straight away. You are
done.
- Otherwise the card offers **Confirm mailbox ownership**, which emails a
link to the address, and **Enable delivery**, which triggers a separate
confirmation from the delivery service. Both must complete before the
badge reads **Verified**. Verifying the domain instead is quicker and
covers every future address.
An address must be **Verified** and **Active** to be picked in a broadcast.
**Deactivate** takes it out of the pickers without deleting its history.
## What depends on this
- **Broadcasts** and **sequences** pick a sending address in their Sender
step.
- **Transactional templates** name a sending address in **Send from**.
Unverified addresses appear in that list but are disabled.
- **Support and sales channels** are separate. They receive mail at an
inbound address and reply from their own From address, verified in their
own settings. Keeping them apart keeps a bad campaign from hurting your
support mail's reputation. See [Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox).
## When it goes wrong
- **A record shows a red cross after Re-check.** Compare the name and
value with what you published. The most common mistakes are a DNS host
that appends your domain to the name automatically, so the record ends
up as `name.yourcompany.com.yourcompany.com`, and a trailing dot missing
from a CNAME value where the host requires one.
- **The domain stays Pending DNS for a long time.** Propagation at some
hosts takes hours. Nothing is wrong on the ClientSphere side; keep
re-checking.
- **"Sending isn't set up yet" is still showing.** The address exists but
is not both verified and active. Open the card and check the badges.
- **You removed a domain.** Addresses it verified go back to unverified
unless they were confirmed individually. Adding the domain again gives
you the same records, and anything already published stays valid.
## Next
[Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox), so email from customers
becomes tickets.
# Connect a support inbox
Source: https://app.clientsphere.io/docs/setup/email/support-inbox
Turn a support address into tickets. Create the channel, forward your mailbox to it, confirm, and set what happens to each new email.
A support email channel is how email from customers becomes tickets. You
create the channel in ClientSphere, it gives you an inbound address, and you
forward your existing support mailbox to that address. Replies from a ticket
go out from the channel.
**Before you start:**
- A role with **Manage integrations**.
- Admin access to the mailbox you will forward, such as
`support@yourcompany.com` in Google Workspace or Microsoft 365.
- Ideally the domain is already [verified for sending](https://app.clientsphere.io/docs/setup/email/email-sending),
so replies come from your address straight away.
Everything is under **Settings → Support → Email Channels**.
## Create the channel
Click **Add Support Email Channel** and fill in:
- **Channel Name**, for your team, such as "Customer Support".
- **From Email**: the address customers see on replies, such as
`support@yourcompany.com`. Until it is verified, replies go out from the
channel's inbound address instead. The form says so.
- **Display Name**, such as "Acme Support Team".
- **Auto-create tickets**: on, unless you want to review email in
quarantine first.
- **Default Priority** for tickets created from this channel.
- **Email Signature**, optional, added under every reply from this channel.
- **AI Auto-Respond**, and if on, the **Response Mode**: **Draft for
review** or **Auto-send immediately**. Start with draft; see
[Turn on AI](https://app.clientsphere.io/docs/setup/index) before choosing auto-send.
Click **Create Channel**.
[Screenshot: The Add Support Email Channel dialog]
## Forward your mailbox
The **Set Up Email Forwarding** dialog opens with the channel's **Inbound
Address**, a long generated address with a copy button. Forward your support
mailbox to it:
- **Gmail and Google Workspace.** Settings → Forwarding and POP/IMAP → Add
a forwarding address → enter the inbound address. Google sends a
confirmation email to that address, which arrives in ClientSphere like
any other message: look for it in **Support → Tickets**, or in
**Settings → Support → Quarantine** if it was held. Use the code or link
in it, then choose "Forward a copy of incoming mail to…".
- **Outlook and Microsoft 365.** Settings → Mail → Forwarding → enable
forwarding → enter the inbound address. Optionally keep a copy in the
mailbox.
- **Other providers.** Look for "Forwarding" or "Mail rules" and forward
all incoming mail to the inbound address.
Click **Send Test Email** in the dialog, or **Test** on the channel row
later, and check that a ticket appears in **Support → Tickets**.
## Verify the From address
Open the channel with **Edit**. Below the form, a verification block shows
the address as **Verified** or **Unverified** and explains what is missing:
> Two things have to be true before this address can be used. Send
> confirmation email mails a link to the address — clicking it proves this
> workspace controls the mailbox. The address also has to be cleared for
> delivery: if your domain is already verified, delivery status shows
> Verified (domain) and you're done. Otherwise click Enable delivery and
> follow the separate link we send.
If the domain is verified under **Email sending**, delivery is already
cleared and only the mailbox confirmation remains. Click **Send confirmation
email**, click the link in the mailbox, then **Re-check**.
## Decide what happens to each email
The other tabs under **Settings → Support** are all per channel, and each
says "Create a channel first" until one exists:
- **SLA & Automation**: the **Default SLA** for a first reply, from 30
minutes to 24 hours, the **Follow-up Reminder**, and **Escalate
Unassigned After**. The clock runs on working hours; see
[Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment).
- **AI Settings**: the same auto-respond and response mode as the channel
form.
- **Defaults**: the **Global Fallback Assignee** used when a channel's
assignment mode does not resolve to anyone, and the **Assignment Mode**
per channel.
- **Templates**: saved replies agents insert from the composer.
- **Quarantine**: inbound email that was skipped, errored, or could not be
linked to a ticket. Each row can be recovered as a new ticket or
dismissed. Nothing is lost.
## When it goes wrong
- **The tickets inbox says "No email channel is receiving mail yet."** No
channel exists; the message links here.
- **Tickets are not appearing.** Send a test from an outside mailbox. If it
shows in **Quarantine** with a reason, act on the reason. If it shows
nowhere, forwarding is not active at the provider: check that the
forwarding address was confirmed and the rule is on.
- **Google's forwarding confirmation never arrived.** It was sent to the
inbound address, so it is in ClientSphere: check Tickets, then
Quarantine.
- **Replies come from a strange long address.** The From address is not
verified yet, so replies use the inbound address. Complete the
verification block above.
- **The channel shows Inactive.** Someone deactivated it. **Edit** and set
it active; inbound mail while it was off is in Quarantine as **Channel
inactive** and can be recovered.
- **Every email becomes a ticket, including newsletters.** Forward only the
support mailbox, not a personal one, and turn off **Auto-create tickets**
if you would rather review first.
## Next
[Connect a sales inbox](https://app.clientsphere.io/docs/setup/email/sales-inbox), which works the same way for
inbound sales email.
# Connect a sales inbox
Source: https://app.clientsphere.io/docs/setup/email/sales-inbox
Route inbound sales email into the Sales Inbox with an SLA and an assignee, the same way a support channel feeds tickets.
A sales email channel does for inbound sales what a support channel does for
tickets: mail forwarded to its inbound address becomes items in the
**Sales Inbox**, each with an SLA, an assignee, and links to the contact and
account. Replies go out from the channel.
**Before you start:** the same as for a
[support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox): a role with **Manage integrations**,
admin access to the mailbox you will forward, and ideally a
[verified sending domain](https://app.clientsphere.io/docs/setup/email/email-sending).
Everything is under **Settings → Sales → Email Channels**.
## Create the channel
Click **Add Sales Email Channel**:
- **Channel Name**, such as "Sales Inquiries".
- **From Email**, such as `sales@yourcompany.com`. Until verified, replies
go out from the inbound address.
- **Display Name**, such as "Acme Sales Team".
- **Default Assigned To**: the person new items go to when the assignment
mode is fixed.
- **Email Signature**, optional.
The form ends with a note worth reading: "SLA, automation, and AI settings
are managed in their own tabs above." Unlike a support channel, none of that
is in the form.
Click **Create Channel**, then forward your sales mailbox to the **Inbound
Address** exactly as described for the
[support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox#forward-your-mailbox), and verify the
From address the same way.
## Set the rules per channel
- **SLA & Automation**: **Default SLA** for a first reply, **Follow-up
Reminder**, and **Escalate Unassigned After**. Sales SLAs typically run
shorter than support: an inbound lead that waits four hours is a lead
that emailed a competitor.
- **AI Settings**: whether the AI drafts or sends replies for this channel.
For sales, draft mode is the sensible default; the rep should own the
first reply.
- **Defaults**: priority is inherited from the channel and edited there.
The **Assignment Mode** card decides who gets each new item:
**Fixed Person**, **Round Robin**, **Load Balanced**, or
**Account-Based**, which assigns to the account owner and falls back to
round robin. Pick the agents in the pool.
- **Templates** and **Quarantine** work exactly as they do for support.
## What a sales item carries
When mail arrives, ClientSphere matches the sender to an existing contact or
lead and shows both on the item. The **Account** link is usually the one
worth setting by hand, so the conversation shows up on the customer's
record. Reps do that from the inbox; see
[Work the sales inbox](https://app.clientsphere.io/docs/use/support/sales-inbox).
## When it goes wrong
The failure modes are the same as for a support inbox: nothing arriving
means forwarding is not confirmed at the provider or mail is in
**Quarantine**; replies from a long generated address mean the From address
is not yet verified; and items landing in **Unassigned** mean the
assignment mode is fixed with no default person.
## Next
[Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment),
which sets the hours every SLA clock runs on.
# Working hours, SLAs and assignment
Source: https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment
Set the hours the SLA clocks run, the response targets per channel, and how each new ticket or sales item gets an owner.
Three settings decide whether "we replied on time" means anything: the
hours your team works, the target for a first reply, and who a new item
lands with. They live in three places, and the first one silently drives the
other two.
**Before you start:** a role with **Manage integrations**, and at least one
[support](https://app.clientsphere.io/docs/setup/email/support-inbox) or [sales](https://app.clientsphere.io/docs/setup/email/sales-inbox) channel,
because SLAs and assignment are set per channel.
## Working hours
**Settings → Company → Working Hours.** The card says what it is for: "Used
by both Sales and Support SLA calculations."
1. Pick the timezone the hours are in.
2. Turn on each working day and set its start and end. **Mon – Fri** fills
in a standard week; **All Days** and **Clear All** do what they say.
3. Add a break to a day with **+ Add break** if your SLA should pause over
lunch.
4. Click **Save All**.
[Screenshot: Working Hours with Monday to Friday, 9:00 AM to 5:00 PM]
Every SLA deadline is computed in these hours. A four-hour SLA on a ticket
that arrives at 5 pm on Friday is due at 1 pm on Monday, not 9 pm on
Friday. The same hours decide when the AI is allowed to answer if a widget
is set to respond only outside business hours.
**No working hours means around the clock.**
If no hours are set, SLA clocks run on the calendar, and every overnight
ticket breaches before anyone is in. Set them before you set an SLA.
## SLAs, per channel
**Settings → Support → SLA & Automation** and **Settings → Sales → SLA &
Automation**. Pick the channel, then:
- **Default SLA**: the target for a first reply, from 30 minutes to 24
hours. This is what the **SLA Deadline** on a ticket and the **2h left**
chip on a sales item count down to.
- **Follow-up Reminder**: after how many days without a customer reply the
team is nudged.
- **Escalate Unassigned After**: how long an item may sit with no owner
before it is escalated.
Click **Save Changes**. A channel with no SLA set has no deadline, so the
reports' SLA figures will be blank for it.
## Assignment, per channel
**Settings → Support → Defaults** and **Settings → Sales → Defaults**, in
the **Assignment Mode** card. Four modes:
| Mode | What it does |
|---|---|
| **Fixed Person** | Always assign to the channel's default assignee. |
| **Round Robin** | Rotate evenly across the agents you pick. |
| **Load Balanced** | Assign to the agent with the fewest open items. |
| **Account-Based** | Assign to the account owner; fall back to round robin among the agents you pick. |
For the last three, tick the **Agent Pool**. The card warns "Select at least
one agent for the pool" if you leave it empty, and the **Agent Workload**
list below shows current open items per agent so you can see the effect.
The **Global Fallback Assignee** at the top of the Defaults tab catches
anything the mode cannot resolve, such as a fixed channel whose default
person was deactivated.
## How to check it is working
Send a test email to a channel and open the item. **SLA Deadline** should be
a time inside working hours, and **Assignee** should be filled according to
the mode. After a reply, **First Reply** fills in. The Reports page then
shows **Support SLA** and **Sales SLA** compliance and a median response
time that excludes nights and weekends per your working hours.
## When it goes wrong
- **Every ticket is overdue in the morning.** Working hours are not set, or
are set in the wrong timezone.
- **Items land in Unassigned.** The mode is Fixed Person with no default
assignee, or the pool is empty. Set the **Global Fallback Assignee** so
nothing is ownerless while you fix the channel.
- **The SLA tabs say "Create a channel first".** They are per channel.
Create the channel, then come back.
- **Reports show no SLA numbers.** The channel has no SLA set, or there
have been no items since it was set.
## Next
The workspace can now receive, assign, and answer email on time. The
[Use](https://app.clientsphere.io/docs/use) track covers the everyday work from here: lists, broadcasts,
tickets, and the sales inbox.
# Connect Gmail
Source: https://app.clientsphere.io/docs/setup/email/connect-gmail
Link a Gmail mailbox so the CRM can send from it and log its conversations against your accounts, and control what gets synced.
Connecting Gmail lets the CRM send email from your own mailbox and log the
conversations you have with contacts against their accounts. It is per
person: each user connects their own mailbox. It is separate from the
workspace's sending domain, which broadcasts and transactional email use.
**Before you start:** an admin must have set up the Google integration for
the workspace. If **Settings → Email** says "Gmail integration is not
configured", that is the missing piece, and only an administrator can add
it.
## Connect
**Settings → Email → Connect Gmail** opens Google's sign-in and asks for
permission to read and send mail. On return, the mailbox is listed with a
**Connected** badge. **Connect Another Gmail Account** adds a second.
**Disconnect** removes one; nothing already logged is deleted.
Once connected, conversations with known contacts appear on their
accounts' **Emails** tab and in the dashboard's **Recent Email Activity**.
## Control what is synced
**Settings → Company → Email Sync** has two workspace-wide rules:
- **Organization Domain**: emails where every participant shares this
domain are treated as internal and not synced. It is detected from the
connected mailbox if left blank.
- **Never Log List**: addresses or domains that are never synced, even
when they belong to a known contact. Add an address such as
`news@acme.com` or a domain prefix such as `@newsletter.com`.
## When it goes wrong
- **"Gmail integration is not configured."** The workspace has no Google
credentials. An administrator sets them up outside these settings.
- **The mailbox shows Inactive.** Google revoked the connection, usually
after a password change. Disconnect and connect again.
- **A conversation is not on the account.** The other party is not a
contact on that account, or the address is on the never-log list, or
everyone on the thread is on your own domain.
- **Recent Email Activity is empty.** Sync only covers mail with known
contacts, and only from the time of connection onward.
# Put the Support Hub on your site
Source: https://app.clientsphere.io/docs/setup/site/support-hub
Create a support channel, choose what visitors see when they open the widget, and paste one script tag onto your site.
The Support Hub is the chat widget visitors open on your website. It can
search your help centre, start a conversation with your team or the AI,
take a message when nobody is online, and collect suggestions. This page is
the admin side: what to configure before a developer pastes the tag. The
tag itself, the identity attributes, and what they write to the CRM are in
the developer guide, [Support Hub](https://app.clientsphere.io/docs/build/guides/support-hub).
**Before you start:** a role with **Manage support widgets**. If you want
the widget to search articles, publish some first; see
[Publish your knowledge base](https://app.clientsphere.io/docs/setup/site/publish-knowledge-base).
Everything is under **Settings → Support Widgets**.
## Create a support channel
A support channel is one widget: one embed code, one stream of
conversations. Click **Create Support Channel**.
- **Channel Setup.** A **Channel Name** for your team, such as "Website
Support". **Link to Account** is optional and is for a widget installed
inside one specific customer's product, so its conversations attach to
that account; leave it as **No Account (General Support)** for a public
site. Keep **Active Channel** on.
- **AI Assistant.** **Enable AI Auto-Respond** lets the AI answer visitor
questions from your knowledge base and imported documents. Visitors can
escalate to a person at any time. The assistant's name and welcome
message are set once for all widgets under **Settings → AI Agent →
Support AI**; see [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai).
- **Preferences.** **Require Email** asks the visitor for an email before a
chat starts, which is how a conversation becomes a contact. **Collect
Customer Info** gathers extra details for agents.
Click **Create Channel**.
[Screenshot: The Create Support Channel dialog with its Channel Setup, AI Assistant, and Preferences tabs]
## Choose the landing experience
The **Support Hub** tab configures what every widget in the workspace shows
when opened. It is workspace-wide, not per widget.
- **Landing Mode.** **Hub (recommended)** opens on a grid of cards.
**Chat-only (legacy)** opens straight into the conversation with the AI
welcome message.
- **Appearance.** **Primary Color** for buttons and highlights, shared by
sandbox and live widgets.
- **Hub Appearance.** The **Hub Title** and optional **Hub Subtitle**
visitors see at the top, a **Banner Color** that defaults to a softened
version of the primary colour, and a **Theme** of auto, always light, or
always dark. A host page can override the theme per page with a
`data-theme` attribute on the script tag.
### Hub cards
Each card is an entry point. Click **Add card**, then set an icon, a title,
a description, a **CTA Label**, and an **Action**:
| Action | What happens |
|---|---|
| **Open chat** | Starts a conversation |
| **Search Help Desk** | Opens a search over your published articles |
| **Open external link** | Goes to the **URL** you enter |
| **Email us form** | A name, email, subject, and message form for when nobody is online |
| **Suggest an improvement** | The feature request form |
Reorder with the arrows, remove with the bin, and switch a card off with
**Enabled** rather than deleting it if you might want it back. The default
set is a good start: search, get in touch, setup guide, API documentation,
and suggest an improvement.
[Screenshot: A hub card with its icon, action, title, CTA label, description, and Enabled switch]
### Product categories
The **Suggest an improvement** form asks the visitor to pick a product
category. Add at least one under **Product Categories**, or the form cannot
be submitted. The defaults are Billing, Features, Integrations, UI/UX,
Performance, and Other; replace them with your own product areas.
Submissions land in **Support → Feature Requests**.
Click **Save changes**.
## Install it
Back on the **Support Hub** tab, the **Install** card has **Get embed
code**. Three variants are offered:
- **Basic Embed**: the widget id only. Visitors are anonymous until they
give an email.
- **Enhanced Embed with Customer Data**: the same tag with the logged-in
user's name, email, and company as attributes, so conversations are
attached to the right contact and account from the first message. Use
this inside your product.
- **Dynamic JavaScript Embed**: for single-page apps and tag managers that
set the attributes at runtime.
Hand the snippet to whoever maintains the site. The developer guide covers
the attribute list, how identification creates contacts and accounts on
page load, and the checks to run when the widget does not appear.
## Watch it work
**Team Status** on the same page shows which agents are online and how
many channels each is watching. Conversations arrive under **Support →
Chat**; see [Live chat conversations](https://app.clientsphere.io/docs/use/support/live-chat).
## When it goes wrong
- **The widget does not appear on the site.** The channel is inactive, the
tag is missing the widget id, or a second copy of the tag is on the
page. The developer guide has the console messages to look for.
- **Visitors cannot submit a suggestion.** There are no product
categories. Add one.
- **The AI answers nothing useful, or does not answer at all.** AI is off
for the channel, off at the workspace master switch, or limited to
outside business hours. See [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai).
- **A card does nothing.** An **Open external link** card with no URL is
skipped by the widget without a warning. Give it a URL or switch it off.
- **Two widgets show different colours.** They cannot. Appearance is
workspace-wide; one of the pages is loading a cached copy of the script.
## Next
[Put the floating launcher on your product](https://app.clientsphere.io/docs/setup/site/floating-launcher), the
lighter embed for inside your app.
# Put the floating launcher on your product
Source: https://app.clientsphere.io/docs/setup/site/floating-launcher
Configure the pill button and its quick-action menu, install it with the user's identity, and feed Product Analytics.
The floating launcher is a small pill button, "Support" by default, that
opens a menu of quick actions: search the help centre, contact you, suggest
an improvement, open a page. It is lighter than the Support Hub, has no
chat of its own, and is meant for inside your product, on every page.
It is also what feeds **Product Analytics**. When the launcher is installed
with the logged-in user's identity, every page load records that the person
was in the product, and every help search is logged. Without the identity
attributes it is just a button. See
[Product Analytics](https://app.clientsphere.io/docs/use/index) for what that data becomes.
**Before you start:** a role with **Manage support widgets**. The tag and
its attributes are covered for developers in
[Floating launcher](https://app.clientsphere.io/docs/build/guides/floating-launcher).
Everything is under **Settings → Support Widgets → Floating Launcher**.
## Appearance
**Label** is the text on the pill, up to 40 characters. **Color** is its
background. **Position** is one of the four corners. **Theme** follows the
visitor's system by default, or can be always light or always dark; a host
page can override it per page with `data-theme` on the script tag.
## Menu items
Each item is one action in the popup. Click **Add item**, give it a
**Label**, and pick an **Action**:
| Action | What happens |
|---|---|
| **Search Help Desk** | Opens a search over your published articles |
| **Suggest an improvement form** | The feature request form; submissions land in **Support → Feature Requests** |
| **Open external link** | Goes to the **URL** you enter |
| **Open chat (link to chat page)** | Goes to the **Chat page URL** you enter, such as a page where the Support Hub is installed |
**A link with no URL is dropped from the menu.**
An **Open external link** or **Open chat** item with an empty URL is left
out of the visitor's menu. Settings shows a warning under the empty field.
Two of the default items, "Contact us" and "Support page", start with no
URL, so they do nothing until you fill them in or remove them.
Reorder with the arrows and click **Save changes**. Changes reach visitors
within about a minute; the launcher caches its configuration briefly.
[Screenshot: Launcher Appearance and Menu Items, with the Contact us item showing an empty URL]
## Install it
The **Install** card offers two snippets. Use the second one.
- **Basic** carries only the workspace id. The launcher works, nothing is
attributed, and Product Analytics stays empty.
- **With user identity (recommended)** adds the user's name, email, and
company as attributes. Replace the placeholder values with the real ones
when your app renders the page. With these set, feature requests carry
the submitter, the person is created as a contact on first load, and
their presence in the product is recorded.
Paste it inside `` or before `` on every page of the product.
If the chat widget is already on the site, the note under the snippets
applies: you can pass your existing widget id instead of the company id and
the launcher resolves the workspace from it.
## What it records
With identity set, on page load the launcher finds or creates the contact
by email and links it to the account named in the company attribute. That
happens once per six hours per browser, so it does not fire on every page.
Each help search is logged with the query and whether it found anything.
Feature requests are tagged with the submitter.
## When it goes wrong
- **The launcher is not on the page.** The tag is missing, or the console
shows that the workspace id could not be resolved. The developer guide
lists the console messages.
- **Product Analytics shows nothing.** The basic snippet was used. Switch
to the identity snippet; data starts with the next page load.
- **Feature requests show as Anonymous.** Same cause.
- **A menu item is missing for visitors.** It is a link with no URL; the
settings page marks it in amber.
- **Search returns nothing.** No published articles match. Publishing is
covered in [Write and publish articles](https://app.clientsphere.io/docs/use/support/articles).
## Next
[Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai), so the widget and your inboxes can answer
on their own.
# Publish your knowledge base
Source: https://app.clientsphere.io/docs/setup/site/publish-knowledge-base
Turn on the public help centre, decide who can write and publish, brand it, and serve it on your own domain.
The knowledge base is one set of articles with three readers: your team,
the AI, and, once you turn on public access, your customers. Publishing an
article changes what the chat widget and the email auto-responder say, so
it is worth deciding the rules before the first article goes live.
**Before you start:** a role with **Manage knowledge base**. Writing the
articles themselves is covered in [Write and publish articles](https://app.clientsphere.io/docs/use/support/articles).
Everything is under **Support → Knowledge Base → Configuration**. Click
**Save Settings** when you are done; nothing saves on its own.
## Turn on public access
In **General Settings**, set the **Knowledge Base Title** and
**Description** visitors see, then turn on **Enable Public Access**. The
**Public URL** in the next card is the address to share, with a **Copy**
button and a preview link.
Two toggles under **Public Access** shape the reader's experience:
- **Show Feedback Options** lets readers mark an article helpful or not.
Leave this on; it is what feeds the **Needs Attention** list on the
Analytics tab.
- **Show View Counts** displays how often each article has been read.
Only articles with status **Published** appear publicly. Drafts and
archived articles stay internal.
## Decide who can write and publish
Under **Permissions & Security**, three settings:
| Setting | Options |
|---|---|
| **Article Creation Permission** | Admin Only, Manager & Above, All Users |
| **Article Publishing Permission** | Admin Only, Manager & Above, Author & Above |
| **Category Management Permission** | Admin Only, Manager & Above |
A common arrangement is that everyone can draft, managers publish, and
admins manage categories. Because a published article is immediately what
the AI answers from, keep publishing narrower than creation until the team
has a review habit.
## Brand it
**Appearance** has a **Theme** of light, dark, or auto, a **Brand Color**,
and **Show Company Logo**, which uses the logo from **Settings → Company**.
**Footer CTA Text** and **Footer CTA URL** in General Settings add a
call-to-action above the footer on every article and category page; both
must be set for it to show.
**SEO Keywords** can be left empty; they are generated from your category
names. Per-article titles and descriptions for search engines are set on
each article.
[Screenshot: Knowledge base Appearance settings and the Custom Domain card]
## Use your own domain
By default the help centre lives at a ClientSphere address. To serve it at
something like `help.yourcompany.com`:
1. Under **Custom Domain**, type the domain and click **Set Domain**. The
card now shows it with a **Pending Verification** badge and a
**DNS Configuration Required** block.
2. At your DNS host, add the record it shows: type **CNAME**, name as
shown (the first part of your domain, such as `help`), value the target
as shown. Copy it exactly.
3. Click **Verify DNS**. When the record resolves, the badge changes to
**Verified** and the help centre answers on your domain.
**This is not the same as verifying an email domain.**
The help centre uses one CNAME record. Email sending uses a TXT record and
several CNAMEs, under **Settings → Email sending**. The two are unrelated;
verifying one does nothing for the other, and their records must not be
confused at the DNS host.
**Remove** disconnects the domain; visitors using it lose access until it
is set again.
## Files for AI assistants
Once public access is on, the help centre also serves two plain-text
files that AI assistants and search agents read in preference to crawling
pages:
| File | What it contains |
|---|---|
| `/llms.txt` | Title, description, your categories, and one line per published article with its excerpt and link. |
| `/llms-full.txt` | The same index followed by the full text of every published article. |
They live at the root of the help centre, so on a custom domain that is
`https://help.yourcompany.com/llms.txt`, and on the default address it
follows the **Public URL** shown in Configuration. There is nothing to
turn on: they exist whenever public access does, they contain only
**Published** articles, and they refresh within an hour of a change.
Nothing else needs to be done for a customer's assistant to find them,
but if you write your own bot or use a tool that asks for a "knowledge
source", the full file is the address to give it.
## When it goes wrong
- **"DNS records not found. Please check your CNAME configuration."** The
record is not published yet, has a typo, or has not propagated. The
block says changes can take up to 48 hours; try again later rather than
removing and re-adding.
- **The public page is blank or shows nothing.** No articles are
**Published**, or public access is off.
- **Readers see articles you meant to be internal.** Their status is
Published. Set it to Draft or Archived.
- **The logo does not appear.** No logo is uploaded under **Settings →
Company**, or **Show Company Logo** is off.
## Next
[Write and publish articles](https://app.clientsphere.io/docs/use/support/articles), and
[Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai) so the same articles answer visitors.
# Turn on AI
Source: https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai
Every AI switch in one place, what each one controls, and the order to turn them on so the assistant answers well and stays quiet when it should.
ClientSphere's AI does four things: drafts or sends replies to inbound
email, answers visitors in the chat widget, coaches your team in the
assistant panel, and writes a daily insights briefing. They share one
master switch and one body of knowledge, but each has its own toggle, and
they live in different places. This page maps them all.
**Before you start:** a role with **Manage AI agent**. The AI answers from
your knowledge base and imported documents, so it is only as good as what
you have published; see [Publish your knowledge base](https://app.clientsphere.io/docs/setup/site/publish-knowledge-base).
## The switches
| Switch | Where | What it controls |
|---|---|---|
| **Enable AI Agent** | Settings → AI Agent → Support AI | The master switch. Off means the AI never auto-responds anywhere. |
| **Enable AI Auto-Respond** | Settings → Support Widgets → each channel → AI Assistant | Whether the AI answers visitors in that widget |
| **AI Auto-Respond** and **Response Mode** | Settings → Support → AI Settings, per channel; the same under Sales | Whether the AI handles inbound email, and whether it drafts or sends |
| **Only respond outside business hours** | Settings → AI Agent → Support AI | Limits widget auto-replies to when the team is offline |
| **Enable daily insights** | Settings → AI Agent → Insights | The dashboard briefing; needs the master switch on too |
The assistant panel your team opens from the header does not have a
switch; it is available to anyone whose role includes it.
## 1. Give it context
**Settings → AI Agent → Context** has five free-text fields the assistant
reads on every request: **Products & Services**, **Target Audience / ICP**,
**Sales Playbook**, **Support Policies**, and **Additional Context**. It
already knows your company name, industry, and pipeline stages. Fill in the
first and fourth at minimum: what you sell and what you promise. Click
**Save**.
## 2. Give it documents
**Settings → AI Agent → Documents** imports public web pages so the AI can
cite them. Click **Import URL**, paste the page, and tick **Crawl linked
pages on same domain (up to 200 pages)** to pull in a whole docs site. The
row shows **Processing** until it is indexed, then **Ready** with the page
and chunk counts. **Re-fetch all pages and discover new ones** on a crawled
document picks up changes later.
Published knowledge base articles are used automatically; nothing to import
there.
## 3. Turn on the master switch and set the behaviour
**Settings → AI Agent → Support AI**:
- **Enable AI Agent**. Everything below is greyed out until this is on.
- **Assistant Name** and **Welcome Message**, shown to visitors in every
widget.
- **Agent Handoff Timeout (minutes)**. After a human agent replies in a
conversation, the AI stays silent for this long. If the timeout expires
and no agent has replied again, the AI resumes. Thirty minutes is the
default; set it to the longest a customer should wait before the AI
steps back in.
- **Only respond outside business hours**. When on, the AI answers
visitors only when your team is offline according to working hours. That
needs working hours to exist; see
[Working hours, SLAs and assignment](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment).
Click **Save**.
[Screenshot: The Support AI Assistant card with the Enable AI Agent master switch, handoff timeout, and business-hours option]
## 4. Turn it on per channel
- **Chat widgets:** **Settings → Support Widgets**, edit the channel, **AI
Assistant** tab, **Enable AI Auto-Respond**.
- **Support email:** **Settings → Support → AI Settings**, pick the
channel, turn on **AI Auto-Respond**, and choose the **Response Mode**:
**Draft for review** puts a draft in the ticket for an agent to send or
discard; **Auto-send immediately** replies on its own.
- **Sales email:** the same under **Settings → Sales → AI Settings**.
Start every channel on **Draft for review**. Read a week of drafts. Switch
to auto-send only where the drafts were right without edits, which is
usually the support channel with a mature knowledge base, and rarely sales.
## 5. Insights, optional
**Settings → AI Agent → Insights**: **Enable daily insights**, a
**Schedule hour (UTC)**, a **Coverage period (days)**, optional **Customer
sentiment analysis**, which uses more tokens, and the categories to cover.
The card notes that it needs the master switch on as well. **Run now**
generates a one-off briefing, at most three a day, so you do not have to
wait for tomorrow's run to see it.
## Watch the usage
**Settings → AI Agent → Usage** shows messages and tokens this month, a
daily chart, and the top users. Check it after the first week with
auto-send on.
## When it goes wrong
- **Nothing answers anywhere.** The master switch is off. It overrides
every per-channel toggle.
- **The widget answers during the day when you wanted it quiet.** **Only
respond outside business hours** is off, or no working hours are set.
- **The AI keeps talking over an agent.** Raise the **Agent Handoff
Timeout**.
- **Answers are generic.** Context fields are empty, or nothing is
published in the knowledge base. Documents still **Processing** are not
used yet.
- **Insights are on but the dashboard is empty.** The next scheduled run
has not happened. Use **Run now**.
## Next
[Sandbox mode and test data](https://app.clientsphere.io/docs/setup/ai-and-developers/sandbox-mode), for trying any of this
without touching real records.
# API keys, logs and MCP
Source: https://app.clientsphere.io/docs/setup/ai-and-developers/api-keys-and-mcp
Generate a key, decide what it may do, watch what it does, and connect an AI assistant to your data over MCP. The admin side; the developer detail is in the Build track.
API keys let your own systems, and any MCP-compatible AI assistant, reach
your workspace's data. This page is the admin side: issuing and scoping
keys and watching their use. How to call the API is in the
[Build](https://app.clientsphere.io/docs/build) track.
**Before you start:** a role with **Manage API keys**. Decide first whether
the key should reach real data or test data; that is set by
[sandbox mode](https://app.clientsphere.io/docs/setup/ai-and-developers/sandbox-mode) at the moment you generate it and
cannot be changed afterwards.
## Generate a key
**Settings → API Keys → Generate Key**. Give it a name that says what
will use it, such as "Zapier Integration". The key is shown once, with the
warning "Store this key securely. You won't be able to see it again after
closing this dialog." Copy it before clicking **Done**.
Keys generated with sandbox mode on start `sk_test_` and only see test
data; with it off, `sk_live_`. One key per integration, so a leak or a
retired system costs you one key.
## Scope it
The pencil on a key's row opens its permissions: a matrix grouped by area
with **Select all** and **Clear all** per group, listing only the
permissions the API actually enforces. A key with no permission for an
endpoint gets a 403 from it. Permissions can be changed after creation;
the key itself cannot.
**Deactivate** stops a key immediately. There is no reactivate; generate a
new one.
## Watch what keys do
**Settings → API Logs** lists every request made with your keys: time,
method, endpoint, which key, the response status, and how long it took.
Filter by key or method. This is where to look when an integration says
it is failing: the status column tells you whether it is being refused,
and the endpoint tells you what it tried.
## Connect an AI assistant over MCP
**Settings → MCP** connects any MCP-compatible assistant to your data, so
it can read and manage contacts, accounts, opportunities, tickets, leads,
tasks, the knowledge base, invoices, quotes, activities, and a dashboard
summary. The setup is three steps, spelled out on the page:
1. Generate an API key as above.
2. **Copy** the configuration block and paste it into your MCP client's
config file, replacing the placeholder with the key.
3. Restart the MCP client.
The key's prefix decides whether the assistant sees sandbox or live data.
The page's **Available Tools** list shows what the assistant can do, group
by group.
## When it goes wrong
- **You closed the dialog without copying the key.** It cannot be
recovered. Deactivate it and generate another.
- **An integration gets 401.** The key is wrong, deactivated, or being sent
to the other side of the sandbox divide. The
[Authentication](https://app.clientsphere.io/docs/build/guides/authentication) guide explains the three
401 codes.
- **An integration gets 403.** The key lacks that permission. Edit its
permissions.
- **The MCP assistant sees no data.** Its key is `sk_test_` and the
workspace has no sandbox data, or the config still has the placeholder.
- **You expected a test-or-live choice in the key dialog.** There is none;
sandbox mode at generation time decides. See
[Sandbox mode and test data](https://app.clientsphere.io/docs/setup/ai-and-developers/sandbox-mode).
# Sandbox mode and test data
Source: https://app.clientsphere.io/docs/setup/ai-and-developers/sandbox-mode
What sandbox is, how to get a test API key, and how to wipe test data when you are done.
Sandbox is a second set of records inside the same workspace: test
accounts, contacts, tickets, and everything else, kept apart from the real
ones. It is a view you switch on, not a separate login or a separate
workspace. Users, roles, settings, and API keys are shared; business
records are not.
**Before you start:** anyone can switch sandbox mode from the user menu.
Clearing sandbox data needs **Manage company settings**.
## Switch it on
Open the user menu at the top right and turn on **Sandbox Mode**. A banner
appears on every page: "Sandbox Mode — Test data only. Changes here do not
affect production." Everything you create while it is on is test data, and
the real records disappear from view until you switch back.
The same switch is under **Settings → Sandbox**.
[Screenshot: The Sandbox settings page with the mode switch, the test API keys note, and Clear All Sandbox Data]
## Get a test API key
API keys come in two kinds. A key starting `sk_test_` reads and writes
sandbox data; `sk_live_` reads and writes real data. A key is bound to one
side for life, and there is no per-request override.
**The kind is decided by sandbox mode, not by a setting on the key.**
Turn **Sandbox Mode** on first, then go to **Settings → API Keys** and click
**Generate Key**. The key you get is `sk_test_`. Generate one with sandbox
off and it is `sk_live_`. There is no key-type option in the dialog; the
mode switch at the moment you generate is what decides.
The developer guides cover the rest:
[Test and live data](https://app.clientsphere.io/docs/build/guides/test-and-live-data) and
[Authentication](https://app.clientsphere.io/docs/build/guides/authentication).
## Chat widgets and the launcher
A chat widget is either a sandbox widget or a live one, decided by which
mode was on when it was created. Conversations from it, and the contacts it
creates, land on that side. The floating launcher always writes live data.
## Clear it out
**Settings → Sandbox → Clear All Sandbox Data** deletes every test account,
contact, opportunity, lead, ticket, task, invoice, quote, and document. It
asks you to confirm, it cannot be undone, and it does not touch real data.
Do this when a demo or an integration test is finished so the next one
starts clean.
## When it goes wrong
- **A record you just created is missing.** You are viewing the other
side. Check the banner and the user menu.
- **The API returns 404 for a record you can see.** The key is bound to the
other side. Sandbox records are only visible to `sk_test_` keys.
- **You generated a live key by mistake.** Deactivate it under **Settings
→ API Keys**, switch sandbox on, and generate again.
## Next
The [Use](https://app.clientsphere.io/docs/use) track, for the everyday work now that setup is complete.
---
Track: Use
# Use overview
Source: https://app.clientsphere.io/docs/use
Everyday work in ClientSphere, one screen at a time, with a starting point for each role.
These pages are for everyone who works in the product. Each covers one
screen and the tasks you do there, states the rules the screen enforces,
and ends with the messages you might see and what they mean. Prerequisites
that live in Settings are linked at the top of each page.
## Start with your role
- **Sales.** [From lead to customer](https://app.clientsphere.io/docs/use/crm/leads), then
[Opportunities and the pipeline](https://app.clientsphere.io/docs/use/crm/opportunities) and
[Work the sales inbox](https://app.clientsphere.io/docs/use/support/sales-inbox). Ask the
[AI assistant](https://app.clientsphere.io/docs/use/insights/ai-assistant) about any deal.
- **Support.** [Work the tickets inbox](https://app.clientsphere.io/docs/use/support/tickets),
[Live chat conversations](https://app.clientsphere.io/docs/use/support/live-chat), and
[Write and publish articles](https://app.clientsphere.io/docs/use/support/articles), which is what the
AI answers from.
- **Marketing.** [Build a contact list](https://app.clientsphere.io/docs/use/email/contact-lists),
[Send your first broadcast](https://app.clientsphere.io/docs/use/email/send-a-broadcast), then
[Sequences](https://app.clientsphere.io/docs/use/automation/sequences) and
[Triggers](https://app.clientsphere.io/docs/use/automation/triggers) to automate follow-up.
- **Finance.** [Quotes and invoices](https://app.clientsphere.io/docs/use/finance/quotes-and-invoices),
including what the product does not automate yet.
- **Managers.** [Reports](https://app.clientsphere.io/docs/use/insights/reports) for the team's numbers
and [Product Analytics](https://app.clientsphere.io/docs/use/insights/product-analytics) for the
customers' behaviour.
## Two rules that come up everywhere
- **Everything hangs off the account.** A ticket, a deal, an invoice, and
an email thread all point at a client company and its contacts, which is
how one relationship's history stays in one place. When something is
missing from an account, the record is usually not linked to it. See
[Accounts and contacts](https://app.clientsphere.io/docs/use/crm/accounts-and-contacts).
- **Email respects opt-outs, except receipts.** Broadcasts, sequences, and
automated email skip anyone on the [unsubscribe or suppression
lists](https://app.clientsphere.io/docs/use/email/unsubscribes-and-bounces), at send time.
[Transactional email](https://app.clientsphere.io/docs/use/email/transactional-email) does not, which is
why it must never carry marketing.
## CRM
- [From lead to customer](https://app.clientsphere.io/docs/use/crm/leads): Add and qualify leads, convert the good ones, and disqualify the rest with a reason.
- [Accounts and contacts](https://app.clientsphere.io/docs/use/crm/accounts-and-contacts): Companies and people, the two owner fields, and one person across several companies.
- [Opportunities and the pipeline](https://app.clientsphere.io/docs/use/crm/opportunities): Deals through the stages you define, on a board you drag across.
- [Tasks](https://app.clientsphere.io/docs/use/crm/tasks): Create, assign, and work tasks as a list, a grid, or a calendar.
## Email
- [Build a contact list](https://app.clientsphere.io/docs/use/email/contact-lists): Static lists you curate, dynamic lists that keep themselves current, and the difference at send time.
- [Import a list from a spreadsheet](https://app.clientsphere.io/docs/use/email/import-a-list): People or companies, column mapping, and what the results report is telling you.
- [Send your first broadcast](https://app.clientsphere.io/docs/use/email/send-a-broadcast): Audience, sender, content, a preview against a real contact, a test, and the send.
- [Transactional email](https://app.clientsphere.io/docs/use/email/transactional-email): Templates your systems send by slug, declared variables, and the sent log.
- [Unsubscribes and bounces](https://app.clientsphere.io/docs/use/email/unsubscribes-and-bounces): The two lists that stop email, and when it is safe to remove someone.
## Automation
- [Sequences](https://app.clientsphere.io/docs/use/automation/sequences): Multi-step email series with delays, tests, and enrollments.
- [Triggers](https://app.clientsphere.io/docs/use/automation/triggers): Enrol people automatically when something happens, with conditions and a backfill.
## Support
- [Work the tickets inbox](https://app.clientsphere.io/docs/use/support/tickets): Reply, leave a note for your team, let the AI draft, and keep inside the SLA.
- [Live chat conversations](https://app.clientsphere.io/docs/use/support/live-chat): Answer visitors from the widget, take over from the AI, and leave notes for colleagues.
- [Work the sales inbox](https://app.clientsphere.io/docs/use/support/sales-inbox): Inbound sales email as a queue: reply, assign, snooze, and link it to the account.
- [Triage feature requests](https://app.clientsphere.io/docs/use/support/feature-requests): Suggestions from the widget and launcher, statuses, and private notes.
- [Write and publish articles](https://app.clientsphere.io/docs/use/support/articles): Draft, categorise, publish to customers and the AI, and find the articles that need fixing.
## Finance and files
- [Quotes and invoices](https://app.clientsphere.io/docs/use/finance/quotes-and-invoices): Quotes, invoices, payments, recurring plans, and what is not automated yet.
- [Documents](https://app.clientsphere.io/docs/use/finance/documents): A shared library of contracts, proposals, and templates, filed by account.
## Insights
- [Reports](https://app.clientsphere.io/docs/use/insights/reports): Built-in reports, exact figure definitions, and a builder for your own.
- [Product Analytics](https://app.clientsphere.io/docs/use/insights/product-analytics): Who uses your product, who is going quiet, and unanswered help searches.
- [Dashboard and AI insights](https://app.clientsphere.io/docs/use/insights/dashboard-and-insights): The dashboard panels and the daily AI briefing.
- [Ask the AI assistant](https://app.clientsphere.io/docs/use/insights/ai-assistant): What the assistant can see, what to ask, and where conversations live.
- [Notifications](https://app.clientsphere.io/docs/use/insights/notifications): What you are told about and how to clear it.
# From lead to customer
Source: https://app.clientsphere.io/docs/use/crm/leads
Add and qualify leads, work them as a list or a pipeline, convert the good ones, and disqualify the rest with a reason.
A lead is a person or company you have not qualified yet. It lives apart
from your accounts and contacts until you convert it, at which point it
becomes all three: an account, a contact, and an opportunity.
**Before you start:** a role with **Read leads** to see them and **Update
leads** to work them. Lead stages come from **Settings → Statuses**; the
defaults are New, Contacted, Qualified, Converted, and Disqualified.
## Add a lead
**CRM → Leads → Add Lead**. The required fields are **Email** and
**Company Name**; name, phone, job title, website, industry, and company
size are optional. **Score** is 0 to 100 and shows as **Hot** at 70 and
above, **Warm** from 40, **Cold** below. **Source** records where the lead
came from, and **Assigned To** gives it an owner.
Leads also arrive on their own from the public API and from website forms
that post to it. Those show their source and can be picked up by an
automation trigger; see [Triggers](https://app.clientsphere.io/docs/use/index).
## Work the list or the pipeline
Two views, switched by the icons next to the search box:
- **List** shows every lead with stage, score, source, owner, and date.
The stage cards above it show the split and filter the list when clicked.
- **Pipeline** shows one column per active stage. Drag a card to another
column to change its stage. Converted and disqualified leads are not
shown here; filtering to either of those switches you back to the list.
The filter button narrows by stage, source, assignee, and date. A **Stalled
only** chip appears when you arrive from a dashboard insight about leads
that have gone quiet.
## Qualify, then convert
Move a lead to **Qualified** when it is worth pursuing, by dragging it or
with **Qualify** on its profile. **Convert** appears only on qualified
leads.
**Convert creates three records.**
The dialog says it plainly: "Converting this lead will create an Account,
Contact, and Opportunity." You name the account, title the opportunity,
give it a value, a stage, and an expected close date. Closed stages are not
offered. After converting you land on the new account, and the lead shows a
"Converted on" banner with links to all three records.
Check before converting whether the company already exists as an account.
Convert always creates a new one, and two accounts for one company is the
most common cleanup job in a CRM.
[Screenshot: The Convert Lead dialog: account name, opportunity title, value, stage, and expected close date]
## Disqualify the rest
**Disqualify** asks for a reason: Bad Fit, No Budget, Unresponsive, Chose
Competitor, Duplicate, or Other, with optional notes. The lead keeps its
history and shows a "Disqualified on" banner with the reason. Prefer this
to deleting; the reasons are what tell you where your leads come from and
why they fail.
**Delete** removes the lead entirely and cannot be undone.
## When it goes wrong
- **Convert is missing from the menu.** The lead is not in the Qualified
stage.
- **"Account name and opportunity title are required."** Both fields in
the convert dialog must be filled.
- **A lead vanished from the pipeline.** It was converted or disqualified.
Switch to the list view and filter by that stage.
- **The score badge shows a dash.** No score was entered. Scores are
manual unless something sets them through the API.
# Accounts and contacts
Source: https://app.clientsphere.io/docs/use/crm/accounts-and-contacts
Accounts are the companies you work with and contacts are the people. How to create them, link them, and keep one record per company.
An **account** is a client company. A **contact** is a person. Everything
else in ClientSphere, from a ticket to an invoice, points at one or both,
which is why the whole history of a relationship shows up in one place.
**Before you start:** roles with **Read accounts** and **Read contacts** to
see them, the matching **Create** and **Update** permissions to change them.
## Accounts
**CRM → Accounts → Add Account**. Only the **Account Name** is required.
The rest is worth filling in because filters and reports use it: industry,
company size, status, and tags.
Two ownership fields sit under **Ownership & Support**, and they are
different people:
- **Account Owner** is the salesperson responsible for the relationship.
- **Support Owner** is the agent who handles its tickets. Support channels
set to **Account-Based** assignment route new tickets to this person.
Both appear as columns and filters on the accounts list. Leaving either
empty shows **Unassigned**.
[Screenshot: The Add New Account dialog with the Ownership & Support section]
### The account profile
Tabs across the top: **Overview**, **Contacts**, **Opportunities**,
**Tickets**, **Notes**, **Tasks**, and **Emails**, each with a count. The
Overview shows pipeline value, won revenue, open tickets, and the
account's product activity if the floating launcher is installed on your
product.
Tags are edited inline on the profile: type in **Add tag…** and press
Enter or a comma. Tags are lower-cased and deduplicated, and they are what
dynamic contact lists and automation triggers filter on.
**Notes** is for the team's own record. Type `@` to mention a colleague.
## Contacts
**CRM → Contacts → Add Contact**. First name, last name, and email are
required. Pick an **Account** by typing to search; when one is chosen, an
**Account Relationship** section appears with a status and a **Primary
contact** checkbox.
The **Contact** filter on the contacts list is by industry, despite the
label; **Title** and **Location** are fixed lists.
### One person, several companies
A contact can belong to more than one account. On the contact's profile,
**Account Relationships** lists them, with a **Primary** badge on the main
one and a role such as "Decision Maker". **Link Account** adds another.
The same relationship is visible from the account's **Contacts** tab,
where **Link Contact** can either pick an existing person or create a new
one in place.
Rows marked **Legacy** with a **Migrate** button are contacts linked the
old way, before relationships existed. Migrating them is one click and
loses nothing.
### Last seen in product
The contact profile shows **Last seen in product** and days active out of
the last 30 when the floating launcher is installed on your product with
the user's identity. Otherwise it reads "Not seen yet". See
[Put the floating launcher on your product](https://app.clientsphere.io/docs/setup/site/floating-launcher).
## Keep it to one record per company
Accounts are matched by name and contacts by email when they are created
through imports, the API, or the website embeds, so duplicates mostly come
from hand entry and from converting leads for companies that already
exist. Search before you create, and before you convert a lead.
## Deleting
Deleting an account removes it and everything attached to it, and the
dialog says so. Deleting a contact removes the person and their
relationships. Neither can be undone. For a company that has simply
stopped being a customer, change its status instead; the history stays
useful.
## When it goes wrong
- **A contact's tickets or emails are not showing on the account.** The
contact is not linked to the account, or is linked as legacy. Link or
migrate from the account's Contacts tab.
- **Tickets are being assigned to the wrong person.** The account's
**Support Owner** is out of date, and the channel uses Account-Based
assignment.
- **"Website must be a valid URL starting with http:// or https://".**
Add the scheme.
- **Two accounts for one company.** Move the contacts, opportunities, and
tickets to the one you keep, then delete the other. There is no merge
yet.
# Opportunities and the pipeline
Source: https://app.clientsphere.io/docs/use/crm/opportunities
Track deals through the stages you define, in a list, a grid, or a kanban board you drag cards across.
An opportunity is a deal: an account, a value, a stage, and a probability.
The stages are yours to define, and the pipeline board is the day-to-day
view of where every deal stands.
**Before you start:** a role with **Read opportunities** and **Update
opportunities**. The stages come from **Settings → Pipeline**, where they
can be added, renamed, recoloured, and reordered. The defaults are
Discovery, Qualification, Technical Evaluation, Proposal, Negotiation,
Closed Won, and Closed Lost.
## Create a deal
**CRM → Opportunities → Add Opportunity**, or convert a lead, which
creates one for you. The title, an account, and a value above zero are
required. **Probability** is a percentage, **Pipeline** is optional for
workspaces that run more than one, and **Stage** comes from the pipeline.
## Three views
The icons beside the search box switch between:
- **Grid**: cards.
- **List**: a table with account, value, pipeline, stage, and size.
- **Pipeline**: one column per stage with the count and the total value at
the top of each. Drag a card to another column to change its stage. The
board loads every opportunity at once rather than a page at a time, so
on a workspace with thousands of deals it takes a moment.
Filters narrow by stage, deal size, lead source, pipeline, and account
owner. A **Stalled only** chip appears when you arrive from a dashboard
insight.
## Closing
Move the deal to **Closed Won** or **Closed Lost**. Won value feeds the
account's **Won Revenue** and the Reports page; open value is the
**Pipeline** figure on both. The Reports tooltip is exact about the
difference: pipeline value excludes both closed stages.
## Deal size and source
**Deal Size** and **Lead Source** are filters and report dimensions.
Size is set when the deal is created or edited; source carries over from
the lead when the deal came from a conversion.
## When it goes wrong
- **"Value must be greater than 0."** A deal needs a value, even an
estimate.
- **"Please select an account."** Every deal belongs to a company. Create
the account first if it does not exist.
- **A stage is missing from the board.** It was removed or renamed under
**Settings → Pipeline**. Deals in a removed stage keep the old value and
show **Unknown Stage** until moved.
- **Dragging a card fails.** The toast says "Failed to update opportunity
stage". Usually a permissions issue; the card snaps back and nothing
is lost.
# Tasks
Source: https://app.clientsphere.io/docs/use/crm/tasks
Create and assign tasks, link them to an account, and work them as a list, a grid, or a calendar.
Tasks are the to-do list of the CRM: follow-ups, projects, admin, each
with an owner, a due date, and a link to the account it is about.
**Before you start:** a role with **Read tasks** and **Create tasks**.
Task statuses are configured per workspace under **Settings → Statuses →
Task Statuses**, so the status list here is whatever your admin set. The
defaults are To Do, In Progress, Review, and Done.
## Create a task
**CRM → Tasks → Add Task**. Only the **Task Title** is required. The
rest:
- **Priority**: Low, Medium, High, Urgent.
- **Type**: Task, Follow-up, Project.
- **Status** from your workspace's list, and **Category**: Sales, Support,
Marketing, Development, Admin.
- **Account**: type to search. Linking a task to an account puts it on the
account's Tasks tab.
- **Assign To**: a colleague, or yourself.
- **Due Date**, with **Today**, **Tomorrow**, and **Next Week** shortcuts.
Past dates cannot be picked.
Tasks also appear on the dashboard under **My Recent Tasks** for their
assignee, and generate a notification when they go overdue.
## Three views
The icons beside the search box switch between:
- **List**: a table with status, priority, due date, and assignee.
- **Grid**: cards.
- **Calendar**: tasks on their due dates, by month, week, day, or agenda,
colour-coded by status and with overdue and high-priority tasks marked.
The counters above the views show the total and one tile per status.
**Filters** narrows by status, priority, category, assignee, created date,
and due date.
## Work a task
Open a task to see its details, change its status or assignee from the
dropdowns, and add comments. Type `@` in a comment to mention a colleague.
An overdue task shows an **OVERDUE** badge.
**Delete** asks for confirmation and shows the task's assignee, due date,
status, and priority so you know what you are removing. It cannot be
undone.
## When it goes wrong
- **"Task title is required."** Everything else is optional.
- **A status is missing from the dropdown.** It was renamed or removed
under **Settings → Statuses**. Tasks in a removed status keep the old
value until changed.
- **The calendar is empty.** Only tasks with a due date appear on it.
- **A task is not on the account's Tasks tab.** It was created without an
account. Edit it and pick one.
# Build a contact list
Source: https://app.clientsphere.io/docs/use/email/contact-lists
Static lists you curate, dynamic lists that keep themselves current, and what each means when a broadcast goes out.
A contact list is an audience. Broadcasts send to one, and sequences enrol
one. There are two kinds, and the kind is chosen when the list is created and
cannot be changed afterwards, so it is worth deciding first.
**Before you start:** you need a role with **Manage contact lists**. Sending
to a list also needs [email sending set up](https://app.clientsphere.io/docs/setup/email/email-sending), but you
can build lists before that is done.
## Static or dynamic
| | Static | Dynamic |
|---|---|---|
| **What it holds** | Companies you link, plus individual people you add | Whatever matches the filters you set |
| **When membership changes** | When you edit it | On its own, as companies start or stop matching |
| **Good for** | A curated audience: a customer segment you picked, a conference list, a set of named people | "All customers", "every prospect tagged fintech", or simply everyone |
| **Can hold people with no company** | Yes, as individual people | Only with **Include every contact** |
The create dialog describes the choice as:
- **Static.** "Pick companies yourself. Fixed until you edit it."
- **Dynamic.** "Tracks companies matching filters — updates itself."
**The type is permanent.**
The detail page edits a static list's members or a dynamic list's filters,
but never the type. If you pick the wrong kind, create a new list.
## One rule that applies to both
Membership is resolved when the broadcast goes out, not when you build the
list or schedule the send. For a static list that links companies, this
means the list is not fixed in headcount: a contact added to one of those
companies next week is in next week's broadcast. The detail page says this
plainly:
> Contacts are resolved from linked companies at send time — new contacts
> added to any linked company are automatically included in the next
> broadcast.
Unsubscribed and suppressed addresses are removed at send time too, so the
contact count shown on the list is approximate. See
[Send your first broadcast](https://app.clientsphere.io/docs/use/email/send-a-broadcast).
## Create a static list
1. Go to **Email → Contact Lists** and click **New list**.
2. Give it a name. The description is optional.
3. Leave **Static** selected and click **Create list**.
The list opens empty, with two panels.
### Link companies
The **Add companies** panel on the right lists every company not yet on the
list. Narrow it with the search box, **Tag**, or **Company status**, then
either tick companies and click **Add selected**, or click
**Add all matching** to link everything that fits the current filters.
**Add all matching** shows the number it will add and asks you to confirm.
It is disabled above 10,000 matches, with the tooltip "Too many matches.
Narrow the filters to 10,000 or fewer."
Linked companies appear in the **Linked companies** panel on the left with
their contact count. Hover a row and click the cross to remove it.
### Add individual people
The **Individual people** section at the bottom is for people you want on the
list by name, including people who belong to no company. Search by name or
email, tick, and click **Add selected**.
People added here are exactly the people you picked. Adding a person does
not pull in their colleagues, and a person whose company is later linked to
the list is still counted once.
## Create a dynamic list
1. Click **New list** and choose **Dynamic**.
2. Set at least one filter: **Company status**, **Tag**, or
**Company name contains**. A company must match all of the filters you
set.
3. Click **Create list**.
The detail page shows **Matching companies** on the left, read-only, and the
**Filters** editor on the right. Change the filters and click
**Save filters**; the note above the editor is worth reading once:
> Changes apply to future broadcasts and sequence enrollments — anything
> already sent is unaffected.
### Include every contact
Tick **Include every contact** to make the list mean everyone in the
workspace, including people with no company. The three filters are ignored
and disabled while it is on.
[Screenshot: The New contact list dialog with Dynamic and Include every contact selected]
**Everyone means everyone.**
An "everyone" list includes contacts created by transactional email, the
public API, and the chat widget, none of whom asked for marketing. Opt-outs
still apply at send time, but a person who never opted in has nothing to opt
out of. For marketing, prefer a status or tag filter that describes consent.
## Enrol the list in a sequence
**Enroll in sequence** at the top of the detail page puts every member into a
sequence in one go. Suppressed addresses and people already active in that
sequence are skipped, and the result screen tells you how many of each.
The button is disabled while the list has no contacts, or while it is still
being built from a file.
## When it goes wrong
- **"At least one filter is required — or turn on 'Include every contact' to
send to everyone."** A dynamic list cannot be saved with no filters. That
is deliberate: an unfiltered list would silently mean everyone.
- **A yellow banner says the list is still being built.** It came from a
file import that has not finished. It cannot be sent to or enrolled until
it has. See [Import a list from a spreadsheet](https://app.clientsphere.io/docs/use/email/import-a-list).
- **"Lists referenced by a broadcast cannot be deleted."** A sent or
scheduled broadcast points at this list. Cancel the schedule first, or
leave the list in place for the report.
- **The company count and the contact count don't add up.** They are not
meant to. Companies are counted once; contacts are the distinct people
reachable through them plus anyone added individually.
# Import a list from a spreadsheet
Source: https://app.clientsphere.io/docs/use/email/import-a-list
Build a contact list from a CSV or Excel file, decide whether the rows are people or companies, map the columns, and read the results.
You can create a contact list straight from a spreadsheet. The import runs in
the background, creates whatever is missing in the CRM, and reports every row
it could not use.
**Before you start:** the file needs a header row. CSV, TSV and plain text
are streamed with no row limit. Excel (`.xlsx`, `.xlsm`) is read in full and
has a row cap; if the dialog tells you only the first rows will be imported,
save the sheet as CSV and try again.
## Decide what the rows are
The one decision that changes the outcome is **What's in the file?**
- **People.** "Each row is a person. Exactly these people are on the list —
a company isn't required." Each row needs an email. The person is matched
to an existing contact by email, or created. If the row has a company name
that matches a company already in the CRM, the person is linked to it. If
it does not match, no company is created: the name is kept on the contact
as text and the person is on the list on their own.
- **Companies.** "Each row is a company. Everyone who works there is
included, now and later." Each row needs a company name. The company is
matched by name or created, and the list links the company, so whoever is a
contact of it when a broadcast goes out receives it. No contacts are
created in this mode.
A people list is exactly the rows in the file. A companies list is open-ended.
[Screenshot: The Create a list from a file dialog with the People and Companies choice]
## Run the import
1. Go to **Email → Contact Lists** and click **Import from file**.
2. Give the list a name, choose **People** or **Companies**, and pick the
file. **Continue** stays disabled until both are set.
3. Map the columns. Each field the CRM stores is matched to a column from
the file, or set to **Don't import**. Headers are matched automatically
where the names are recognisable; check them anyway.
- People: **Email** is required. First name, last name, company name,
job title and phone are optional.
- Companies: **Company name** is required. Website, industry and phone
are optional. There is also a checkbox, **Create companies that aren't
in the CRM yet**. Turn it off to import only names that already match
and get a report of the rest.
4. Check the preview of the first rows, then click **Create list**.
The dialog switches to **Building your list** with a live count. You can
close it; the import carries on, and the list shows a **Building** badge
until it is done.
**A building list cannot be sent to.**
Until the import finishes, the list cannot be used for a broadcast or a
sequence. Broadcasts refuse it, and **Enroll in sequence** is disabled with
the reason in its tooltip. Half an audience is worse than none.
## Read the results
When the import completes the dialog shows three figures:
- **people on the list** or **companies on the list**: the members.
- **newly created**: rows that produced a new contact or company.
- **already in your CRM**: rows that matched an existing record, which was
reused rather than duplicated. Matching is by email for people and by name
for companies, both case-insensitive.
If any rows were skipped, a table lists each one with its row number, the
reason, and the value that caused it. Blank or malformed emails, and
duplicates of an earlier row in the same file, are the usual reasons.
Nothing is skipped silently.
## When it goes wrong
- **"Email is required — pick the column that holds it."** In People mode
the email column has to be mapped before the import can start. The same
applies to **Company name** in Companies mode.
- **"Could not read that file."** The file is not a supported type, or the
first row is not a header row.
- **The Excel banner says only the first rows will be imported.** The sheet
is over the Excel cap. Export it as CSV, which has no limit.
- **"Import failed" and the list may be partially built.** The server
stopped part way. The list keeps the rows that were processed; delete it
and run the import again rather than topping it up.
- **Everyone landed as "already in your CRM".** That is expected on a
re-import. The list still gets every row as a member.
# Send your first broadcast
Source: https://app.clientsphere.io/docs/use/email/send-a-broadcast
Choose an audience and a sender, write the email with merge variables, preview it against a real contact, send a test, then send or schedule it.
A broadcast is one email sent to everyone on a contact list. The editor
walks through three steps that unlock in order, then you preview, test, and
send.
**Before you start:**
- [Email sending is set up](https://app.clientsphere.io/docs/setup/email/email-sending): a verified domain and at
least one active, verified sending address. Without one, the Broadcasts
page shows "Sending isn't set up yet" and nothing can go out.
- A [contact list](https://app.clientsphere.io/docs/use/email/contact-lists) that is not still being built.
- A role with **Send broadcasts**.
## The three steps
Go to **Email → Broadcasts** and click **New broadcast**. Each step collapses
to a one-line summary once it is complete.
[Screenshot: The broadcast editor with its three steps: Audience, Sender, Content]
### 1. Audience
Pick a **Contact list**. The editor shows "Sending to approximately N
contacts. Suppressed addresses are filtered at send time." The number is
approximate for two reasons: membership is resolved when the broadcast
sends, and anyone who has unsubscribed, bounced, or complained is removed at
that moment.
### 2. Sender
Pick a **Sending channel**, which is the From address recipients see, and
enter a **Reply-to email**. Replies go straight to that mailbox; they do not
come back into ClientSphere.
A channel marked **(unverified)** can be selected but the editor warns that
sends may fail. Fix it in [email sending](https://app.clientsphere.io/docs/setup/email/email-sending) first.
### 3. Content
- **Internal name** is for your team. Recipients never see it.
- **Subject** and **Body** are the email. The body is a visual editor:
click a block to edit it, or click **Start from template** to load a
designed starter you can rearrange.
#### Merge variables
The **Merge variables** panel under the body inserts a placeholder that is
filled in per recipient. Click into the subject or a text block first, then
click the variable.
| Recipient | Sender and broadcast |
|---|---|
| `{{firstName}}` `{{lastName}}` `{{email}}` `{{jobTitle}}` `{{company}}` | `{{senderName}}` `{{senderFirstName}}` `{{senderEmail}}` `{{companyName}}` `{{currentDate}}` |
Add a fallback with a pipe for values that may be blank:
`{{firstName|there}}` renders as "there" when the contact has no first name.
Use one in the subject line every time; a subject that reads "Hi ," is the
most common broadcast mistake.
Variables only go into text, heading, and button blocks. If you click one
with nothing selected the editor says so.
## Preview and test
Click **Save draft**, then **Preview & test**.
1. **Choose a preview contact** from the list. The subject and body render
with that person's real values, and the sender context you are using.
2. **Send a test to your inbox.** Enter your address and click
**Send test**. This is one real email with the selected contact's merge
values. It always goes out, even in sandbox mode, and it does not count
in the report.
Test at least once with a contact who has a blank first name, so you see
your fallbacks working.
## Send now
**Send now** opens a confirmation showing From, Reply-to, Subject, and the
approximate recipient count. Type `SEND` in the box to enable the button.
Once sending starts the broadcast is read-only. You can watch progress on
the report page and stop it there if you need to.
## Schedule
**Schedule** asks for a date and time and sends automatically. Two things
the dialog says that are easy to miss:
- **The time is in your device's timezone**, shown in the dialog. If your
workspace spans timezones, check the confirmation line "Sends on …"
before you confirm.
- **Recipients are chosen when it sends, not now.** A list that grows
between scheduling and sending goes out to the larger list. The report
page repeats this while the broadcast is scheduled.
A scheduled broadcast can still be edited; saved changes go out with it.
Choosing a new time replaces the schedule, and **Cancel schedule** on the
report page puts it back to draft.
## Stop a send in flight
On the report page, **Stop sending** appears while the status is
*sending*. The dialog tells you how many have already been sent, and that
those cannot be recalled. Everyone not yet sent is cancelled. The batch
currently in flight finishes first, so a few more may go out before it
halts.
## Read the report
The report shows **Sent**, **Delivered**, **Opened**, **Bounced**,
**Complained**, and **Suppressed**, with a per-recipient table you can filter
by outcome. Two things to know:
- **Sent and Delivered are different.** Sent means the email was handed to
delivery; Delivered means the recipient's server accepted it.
- **Treat open rate as a trend, not a count.** Privacy proxies fetch
tracking pixels automatically, so some opens are not people.
Bounced and complained addresses are added to the suppression list and will
not receive future broadcasts. See [Unsubscribes and bounces](https://app.clientsphere.io/docs/use/index).
## When it goes wrong
- **"Sending isn't set up yet."** No sending address is both verified and
active. An admin fixes this under **Settings → Email sending**; the
notice says so for non-admins too.
- **Send now and Schedule are greyed out** with the hint "Save draft to
unlock Send". Save first.
- **The preview button says "Pick a contact list first"** or "Pick a
sending channel first". Complete that step.
- **"Wait Ns" on the test button.** Tests have a short cooldown between
sends.
- **The broadcast shows *failed*.** Open it; the report page shows the
reason. A failed broadcast stays editable, so you can fix the cause and
send again.
- **"This broadcast has been sent, so it is read-only."** Duplicate it from
the broadcasts list to send something similar.
# Transactional email
Source: https://app.clientsphere.io/docs/use/email/transactional-email
Templates your own systems send by slug, the variables they must declare, the sent log, and why sent and delivered are different words.
Transactional email is one-to-one mail your systems trigger: receipts,
alerts, confirmations, passcodes. You design a template here, and your code
sends it through the API by its slug with the variables filled in. It is
kept apart from broadcasts on purpose, and the rules are different.
**Before you start:** a verified, active sending address; see
[Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending). A role with **Manage email
automations**. The sending API is in the developer track:
[Send a transactional email](https://app.clientsphere.io/docs/build/api/transactional-email/send-transactional-email).
**Transactional mail ignores opt-outs.**
A receipt has to arrive even for someone who left the mailing list, so
transactional messages carry no unsubscribe link and are not blocked by
unsubscribes or suppressions. That is the reason this must never be used
for marketing. Use a [broadcast](https://app.clientsphere.io/docs/use/email/send-a-broadcast) for anything a
person did not ask for.
## Create a template
**Email → Transactional → New template**. A new template offers five
starters, from an order receipt to a one-time passcode, each arriving with
its variables already declared.
- **Name**, for your team.
- **Slug**: the key your code sends against, lowercase letters, numbers and
hyphens. It is generated from the name until you edit it.
- **Subject**. Merge variables work here too.
- **Send from**: the sending address. Unverified and inactive addresses
are listed but disabled.
- **Variables**: every `{{token}}` in the subject or body must be declared
here with a name, a sample value, and whether it is **Required**, or be
written with a fallback such as `{{name|there}}`. A required variable
the caller omits is rejected rather than sent blank.
- **Body**, in the visual designer.
**Save**. Errors appear in a red banner above the form rather than a toast;
an undeclared variable is the usual one, and the message names it.
[Screenshot: A new transactional template: starters, details with the slug, and the variables card]
**The slug is permanent.**
Once saved, the slug is locked: "Fixed once created — your integration
sends against it." Renaming it would silently break every system sending
to it. Create a new template instead.
**Send test** on an existing template sends it to you using each variable's
sample value, and it is recorded in the log like any other message.
## Read the sent log
**Email → Transactional → Sent log** lists every message with its status.
The statuses are deliberately distinct, and hovering one explains it:
| Status | Meaning |
|---|---|
| **Rejected** | Refused before contacting delivery: unknown template, missing required variable, or unverified channel. Nothing was sent. |
| **Queued** | Accepted and stored; a background sweep will retry the handoff. |
| **Sent** | Accepted by the delivery provider. Not yet confirmed delivered. |
| **Delivered** | Confirmed delivered to the recipient's mail server. |
| **Bounced** | The recipient's server rejected it. Recorded against the address; transactional sending is not blocked. |
| **Complained** | The recipient marked it as spam. |
| **Failed** | Could not be sent. Nothing reached the recipient. |
Open a message to see its delivery timeline, the variables it was sent
with, the rendered content, and the **Message ID**, which is what the send
API returned and what API errors refer to.
## Metrics
The **Metrics** tab shows sent, delivered, bounced, complained, failed, and
rejected over 7, 30, or 90 days, a volume chart, a breakdown by template,
and **Why sends were refused**, which groups rejections by reason. There
is no open rate on purpose: transactional mail carries no tracking pixel.
## When it goes wrong
- **The save banner names a variable.** It is used in the subject or body
but not declared. Declare it, or give it a fallback.
- **Messages show Rejected.** Open one; the reason chip says whether the
template was unknown, a required variable was missing, or the channel is
unverified.
- **Sent but never Delivered.** The provider accepted it and the
recipient's server has not confirmed. Bounces arrive later and change the
status.
- **"Any code still sending against this slug will start failing."** That
is the delete confirmation. Deleting a template breaks the integration
sending to it; deactivate or replace it instead.
- **"No sending channels yet. Set one up before sending."** See
[Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending).
# Unsubscribes and bounces
Source: https://app.clientsphere.io/docs/use/email/unsubscribes-and-bounces
The two lists that stop email going out, what each one means, and when it is safe to remove someone from them.
Two lists keep email from going to people who should not get it. They look
similar and mean different things, which is why they are separate tabs.
- **Unsubscribes** are consent. The person asked not to be emailed.
- **Bounces & complaints** are deliverability. The address rejected mail,
or the person reported it as spam, and the delivery provider recorded it.
Both are applied at send time to every broadcast, sequence, and automated
email. Neither applies to [transactional email](https://app.clientsphere.io/docs/use/email/transactional-email),
which is sent regardless.
**Before you start:** a role with **Send broadcasts**.
## Unsubscribes
**Email → Unsubscribes** lists every opted-out address with its **Source**:
**Website**, **Unsubscribe link**, **One-click**, **API**, **Import**, or
**Added here** for ones your team recorded by hand.
- **Add unsubscribe** records an opt-out that came another way, such as a
phone call. It asks for the address and an optional reason. The dialog
says what it does: "This address will be skipped by every broadcast,
sequence and automated email until it's resubscribed."
- **Resubscribe** on a row reverses it, after a confirmation that ends
"Only do this if they've asked to be resubscribed." Do not resubscribe
someone because they went quiet; do it because they asked.
## Bounces and complaints
The second tab lists addresses the delivery provider has suppressed, with
the reason as **Bounce** or **Complaint** and where the event came from.
These are added automatically; there is no button to add one.
**Lift suppression** on a row removes the block. The confirmation is
specific about the risk: sending again to an address that bounced or
reported spam can damage your sending reputation, and you should only lift
it if you know the address has been fixed. A mailbox that was full and has
been emptied is a fair reason. A complaint almost never is.
## What the counts mean elsewhere
The broadcast editor's audience count is approximate because both lists are
applied when the broadcast sends, not when you pick the list. The report
afterwards shows **Suppressed** as its own outcome, and new bounces and
complaints from that send are added to the second list for next time.
## When it goes wrong
- **Someone says they unsubscribed but still got email.** Check whether it
was transactional; those are sent regardless. Otherwise search both tabs
for the address; an unsubscribe recorded after the broadcast started does
not recall it.
- **A good address is on the bounce list.** Lift the suppression once,
then watch the next send's report. If it bounces again, the address is
not good.
- **An address is on both lists.** Both apply independently. Lifting a
suppression does not resubscribe, and resubscribing does not lift a
suppression.
# Sequences
Source: https://app.clientsphere.io/docs/use/automation/sequences
Build a multi-step email series with delays between steps, test each step, activate it, and watch who is moving through it.
A sequence is a series of emails sent one after another with a wait between
each: a welcome series, a nurture, a renewal reminder. People are enrolled
into it by hand from a contact list, or automatically by a
[trigger](https://app.clientsphere.io/docs/use/automation/triggers).
**Before you start:** a verified, active sending address; see
[Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending). A role with **Manage email
sequences**.
## Create the sequence
**Automation → Sequences → New sequence**. The editor has three tabs.
### Settings
- **Name** and an optional **Description**.
- **Sending channel**: the address the emails come from. Unverified or
inactive addresses are listed but cannot be chosen.
- **Skip weekends**: "Push sends that land on Sat/Sun (UTC) to the
following Monday."
### Steps
Each step is one email. **Add step** appends one; the arrows reorder and the
bin removes, though the last remaining step cannot be removed.
- The delay is entered as days, hours, and minutes. On the first step it is
labelled **Delay from enrollment**; on every later step, **Delay from
previous step**. A collapsed step shows its wait as "Wait 2d 4h" or
"Send immediately".
- **Subject** and **Body**. The body is the visual editor, and **Start from
template** loads a designed starter into it. Merge variables such as
`{{firstName}}` and `{{companyName}}` work in both, typed directly or from
the toolbar menu.
[Screenshot: Step 1 of a new sequence: the delay from enrollment, the subject, and Send test and Start from template]
**Edits to a step are captured when you leave it.**
Only one step editor is open at a time. Switching to another step or another
tab saves what you typed into the draft. Save the sequence itself with
**Save changes** before closing the page.
**Send test** on a step emails you that one step with its current, unsaved
content. Merge variables are sent literally rather than filled in, so the
test checks layout and wording, not personalisation. It needs the sequence
saved and a channel chosen first.
### Enrollments
This tab is disabled until the sequence has been saved once; there is
nothing to enrol into before that. Afterwards it lists everyone in the
sequence by **Active**, **Completed**, **Exited**, and **Failed**, with
their current step and next send time. **Stop** ends one person's
enrolment; **Stop all active** ends everyone's. Neither can be resumed.
## Save, activate, pause
**Create sequence** saves it. The button stays disabled, with the reason
beside it, until there is a name, a channel, and a subject on every step:
"Step 2 needs a subject" is the usual one.
A new sequence starts paused. **Activate** starts sending; **Pause** stops
future sends without removing anyone. Enrolments made while paused queue
up and fire when it is activated.
## Enrol people
- **From a contact list:** open the list and click **Enroll in sequence**.
Suppressed addresses and people already active in the sequence are
skipped, and the result screen counts each. See
[Build a contact list](https://app.clientsphere.io/docs/use/email/contact-lists).
- **Automatically:** a [trigger](https://app.clientsphere.io/docs/use/automation/triggers) enrols a lead, contact, or
an account's contacts when something happens.
Opt-outs are honoured at every step: someone who unsubscribes mid-sequence
receives nothing further.
## When it goes wrong
- **"No broadcast channels — create one in Broadcasts settings first."**
There is no sending address. See
[Set up email sending](https://app.clientsphere.io/docs/setup/email/email-sending).
- **Save fails with a message about the body.** A step has a subject but
an empty body. The editor lets you leave it empty; the server does not.
- **The Enrollments tab is greyed out.** Save the sequence first.
- **Sends go out on a Saturday.** **Skip weekends** is off, or the wait
landed on Friday night in UTC, which is still Friday.
- **Someone did not get step 3.** They unsubscribed, bounced, or were
stopped. The Enrollments tab shows which under **Exited** or **Failed**.
# Triggers
Source: https://app.clientsphere.io/docs/use/automation/triggers
Enrol people into a sequence automatically when something happens, with conditions to narrow it, and a backfill to catch up existing records.
A trigger watches for an event, such as a lead being created or an account
changing status, checks any conditions you set, and enrols the person into
a sequence. It is the automatic half of [Sequences](https://app.clientsphere.io/docs/use/automation/sequences).
**Before you start:** the sequence to enrol into must exist and be saved.
A role with **Manage email automations**.
## Build a trigger
**Automation → Triggers → New trigger**.
1. **Name** it for what it does, such as "Webform → Welcome series".
2. **When this event happens.** The events are:
| Event | Fires when |
|---|---|
| Lead created, Lead updated, Lead stage changed, Lead tag added, Lead converted | A lead changes in that way |
| Contact created, Contact tag added | A contact changes in that way |
| Public API lead submitted | A lead arrives through the API, such as from a website form |
| Account created, Account status changed, Account tag added | An account changes in that way. These enrol **every active contact** of the account |
3. **Conditions (all must match).** Optional. Each condition is a field, an
operator, and a value. Text and number fields offer **equals**, **does
not equal**, **is one of**, **is not one of**, **is empty**, **is not
empty**. Tags offer **contains**, **does not contain**, **is empty**,
**is not empty**. Stage and status values are pulled from your own
settings, so custom statuses appear. With no conditions, the helper says
it plainly: the trigger fires for every lead created.
4. **Do this.** **Enroll the recipient in a sequence** and pick the
sequence. The other option, sending a template directly, is listed but
disabled; it is only available through the API for now.
5. **Skip if already in sequence** stays on. It stops the same event firing
twice from enrolling someone twice.
6. **Active** is on by default. Turn it off to pause the trigger without
deleting it.
**Create trigger** saves it. From then on, every matching event enrols.
[Screenshot: The trigger editor: event, conditions, action, and the two switches]
## Catch up existing records
A trigger only fires on new events. To enrol the leads or contacts that
already match, click **Run on existing** in the editor header.
The dialog previews how many records match and how many were scanned, then
**Enroll N records** does it. Three things it tells you that matter:
- **The scan stops at 10,000 rows.** "Results above reflect that subset."
Narrow the conditions if you have more.
- **Account triggers fan out.** Each matched account enrols every active
contact at it, so sends can exceed the match count.
- **Each run has a limit.** If the run hits the per-request limit of new
enrolments, the result says so and offers **Run again**. Already-enrolled
records are skipped, so repeating is safe.
Suppressed addresses and people already active in the sequence are always
skipped.
## Watch it work
**Enrollments from this trigger** at the bottom of the editor lists who it
enrolled and where they are in the sequence, with the same **Stop**
controls as the sequence's own tab.
## When it goes wrong
- **Create trigger is disabled.** It needs a name and, for the enrol
action, a sequence.
- **"No sequences yet — create one first."** Build the sequence before the
trigger.
- **Nothing is enrolling.** The trigger is inactive, the sequence is
paused, the conditions do not match the events you expected, or the
people are suppressed. Check **Run on existing** to see what would match
right now; a preview of zero means the conditions.
- **Far more people enrolled than expected.** An account trigger fanned
out to every contact at each account.
- **"Delete this trigger? Existing enrollments are unaffected."** Deleting
stops future enrolments; people already in the sequence continue.
# Work the tickets inbox
Source: https://app.clientsphere.io/docs/use/support/tickets
Find the tickets that need you, reply by email or leave a note for your team, let the AI draft, and stay inside the SLA.
Tickets are support requests. Most arrive by email through a support
channel; some are created by hand from an account or a chat. The tickets
inbox is where you work them.
**Before you start:** for tickets to arrive by email, an admin needs to
[connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox). Until then the inbox stays
empty, and replies from a ticket are not possible because there is no
address to send from. Working the inbox needs a role with **Read tickets**;
replying needs **Update tickets**.
## Find what needs you
The bar at the top counts **Unresolved**, **My Tickets**, **All Tickets**,
and **Resolved**. Start on **My Tickets**.
In the list, a blue dot means **Needs reply**: the last message is from the
customer. A red **SLA Overdue** badge means the response deadline has
passed. The filter button narrows by status, priority, assignee, type, and
date, and the **SLA breached** badge appears when you arrived from the
dashboard's SLA card.
## Reply, or leave a note
The composer under the conversation has two tabs, and the difference
matters:
- **Reply** sends an email to the customer. **To** is filled in from the
last inbound message and **Cc** with everyone else on the thread except
the channel's own address. You can **Attach** files and insert a saved
template with **Templates**.
- **Note** is internal. It is never sent. Type `@` to mention a colleague;
they get a notification. Notes appear in the thread with an **Internal
note** label.
**Send** stays disabled until there is a recipient and a body.
[Screenshot: A ticket conversation with the Reply and Note composer]
## Let the AI draft
**AI Draft** writes a reply from the knowledge base and the conversation so
far. It appears in the thread as an **AI Draft** with **Send** and
**Discard**, or in the composer for editing, depending on how the channel is
set up. The toast says it plainly: "Review and edit before sending."
If the channel is set to **Auto-send immediately**, the AI answers inbound
email on its own and the reply appears in the thread as sent. That mode is
chosen per channel in **Settings → Support → AI Settings**.
## Properties and the SLA
The **Properties** panel on the right holds status, priority, assignee, and
type. Two rows track time:
- **SLA Deadline** is when a first reply is due, computed from the
channel's SLA and the workspace's working hours. It turns amber in the
last quarter of the window and shows **Overdue** past it, unless the
ticket is resolved or closed.
- **First Reply** shows when an agent first replied, or **Awaiting** until
one does. Notes do not count as a reply.
**Resolve** and **Close** are at the top of the conversation. Resolved
tickets drop off the Unresolved count; closed ones are done.
## Create a ticket by hand
**New Ticket** opens a form: title, description, priority, type (Support,
Bug, Feature Request), module, account, and status. An account is required,
because a ticket belongs to a customer. From an account's Tickets tab the
account is filled in for you.
## Quarantine
Inbound emails that could not become a ticket are held in quarantine rather
than dropped. A shield icon in the inbox header shows the count. An admin
reviews them under **Settings → Support → Quarantine**, where each can be
recovered as a new ticket or dismissed. Nothing there is lost.
## When it goes wrong
- **"No support email channel configured. Set one up in Settings to send
replies."** Replies need a channel. See
[Connect a support inbox](https://app.clientsphere.io/docs/setup/email/support-inbox).
- **The inbox is empty but customers say they emailed.** Forwarding from
the support mailbox is not set up or not confirmed, or the mail is in
quarantine. Check both.
- **AI Draft does nothing useful.** It answers from the knowledge base.
Publish the articles it should draw on, and check that AI is enabled for
the workspace and the channel.
- **SLA Deadline looks wrong.** It runs on working hours. If the workspace
has none set, the clock runs around the calendar.
# Live chat conversations
Source: https://app.clientsphere.io/docs/use/support/live-chat
Answer visitors from the chat widget, take over from the AI, leave notes for colleagues, and close and reopen conversations.
Conversations from the Support Hub widget arrive under **Support → Chat**.
Each one belongs to a visitor, who may be identified or anonymous, and to
the channel it came from.
**Before you start:** a support channel installed on your site; see
[Put the Support Hub on your site](https://app.clientsphere.io/docs/setup/site/support-hub). A role with
**Read support widgets** to view conversations and **Update** to reply.
## The list
The sidebar shows **Conversations** with a **Live** or **Offline** pill for
your connection. Tabs filter to **Open**, **Mine**, **Closed**, and
**All**, each with a count. Search by visitor name or email. A visitor with
no name and no email shows as **Anonymous visitor**.
A red triangle on a row means **Human escalation requested**: the visitor
clicked "Talk to a human" in the widget. Take those first.
## Reply
Messages appear in real time. Type in the composer and press Enter to
send; Shift+Enter adds a line. The paperclip attaches images, PDFs, and
text files.
If the AI is answering this channel, your first reply makes it step back
for the **Agent Handoff Timeout** set under **Settings → AI Agent →
Support AI**. If you do not reply again within that time, the AI resumes.
See [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai).
## Notes for colleagues
The toggle beside the composer switches it to **Internal note**. The
banner reads "Internal note — only visible to agents", the placeholder
changes to "Write an internal note…", and nothing is sent to the visitor.
Notes appear in the thread labelled with your name and "Internal note".
## Assign, close, reopen
- The **Unassigned** dropdown in the header assigns the conversation to a
colleague, which moves it to their **Mine** tab.
- **Close** ends it. Closed conversations stay under the **Closed** tab
with their full history.
- **Reopen** brings a closed one back. You cannot reply to a closed
conversation; the toast says "Reopen the conversation to reply."
## What the visitor sees
Out of hours, a visitor who escalates is told the team is offline and
when it is back, based on your working hours. If the channel's **Email us
form** card is enabled they can leave a message instead, which arrives by
email to the support channel. Conversations from other channels, such as
WhatsApp, are read-only here for now.
## When it goes wrong
- **No conversations are arriving.** The widget is not installed, the
channel is inactive, or you are looking at the other sandbox side. See
the setup guide's troubleshooting list.
- **The AI keeps replying after you took over.** Raise the handoff timeout
or turn off auto-respond for that channel.
- **A file will not upload.** Only images, PDFs, and text files are
accepted.
- **The Live pill says Offline.** Your browser lost its connection to the
server. Messages you send while offline are not delivered; refresh.
# Work the sales inbox
Source: https://app.clientsphere.io/docs/use/support/sales-inbox
Inbound sales email as a queue: reply, leave notes for your team, assign, snooze, and link each conversation to the account it belongs to.
The sales inbox is a shared queue of inbound sales email. Each conversation
is an item with a status, an assignee, an SLA, and links to the contact,
lead, account, and opportunity it concerns.
**Before you start:** an admin needs to
[connect a sales inbox](https://app.clientsphere.io/docs/setup/email/sales-inbox). Until a sales channel is
receiving forwarded mail the inbox stays empty; the empty state says "No
items found", which is also what a filter with no matches says. Working the
inbox needs a role with **Read sales inbox**.
## The queue
Tabs across the top: **All**, **Open**, **Unassigned**, **Mine**,
**Awaiting Reply**, and **Closed**, each with a count. Most reps live in
**Mine**; whoever triages lives in **Unassigned**.
Each row shows the SLA as a chip: **2h left**, **45m left**, or **Overdue
3h**. A blue dot means the customer spoke last. The filter button narrows by
status, assignee, and last activity, and a **Scoped to account** badge
appears when you arrived from an account page.
## Reply, or leave a note
The composer has two tabs:
- **Reply** sends email to the customer, from the channel the conversation
arrived on. **Attach** adds files; **Templates** inserts a saved reply.
- **Note** is internal and never sent. Type `@` to mention a colleague and
notify them. Notes show in the thread as **Internal note**.
**AI Draft** writes a reply from the conversation and the knowledge base,
for you to edit before sending.
## Assign, snooze, close
- **Assignee** is in the Properties panel. Pick a person to move it to
their **Mine** tab.
- **Snooze** hides the item until a time you choose: **Later today**,
**Tomorrow morning**, **Next Monday**, or a custom date and time. It
reappears when the time comes or when the customer replies, and
**Snoozed Until** shows in Properties. **Unsnooze** brings it back early.
- **Close** ends the conversation. Closed items stay searchable under the
**Closed** tab.
## Link it to the account
The Properties panel shows the **Contact** and **Lead** the sender matched,
and an **Account** field. If the account is blank, search and pick one; the
conversation then appears on that account's page and in its history. Click
the cross to unlink. An **Opportunity** link appears when there is one.
Linking is what turns an inbox conversation into part of the customer
record, so do it early rather than at the end.
## Start a new email
**New Email** in the inbox header composes an outbound email that becomes an
item in the queue, so the reply lands here rather than in someone's personal
mailbox. Pick the channel if you have more than one, then To, Cc, subject,
and body. **Send** stays disabled until all of those are set.
## When it goes wrong
- **The inbox is empty.** No sales channel is receiving mail yet, or
forwarding from the sales mailbox has not been confirmed. An admin checks
**Settings → Sales → Email Channels**.
- **Items are not being assigned.** Assignment runs per channel under
**Settings → Sales → Defaults → Assignment Mode**. With a fixed assignee
and no one chosen, items land in **Unassigned**.
- **A reply went out from a strange address.** Until the channel's From
address is verified, replies are sent from the channel's inbound address.
The channel row in Settings says so.
- **Something is missing from the queue entirely.** Look in quarantine under
**Settings → Sales → Quarantine**, where mail that could not be linked is
held rather than dropped.
# Triage feature requests
Source: https://app.clientsphere.io/docs/use/support/feature-requests
Review the suggestions visitors submit through the widget and the launcher, track them through statuses, and keep notes the submitter never sees.
Feature requests are suggestions visitors submit from the Support Hub's
"Suggest an improvement" card or the floating launcher's menu. Each one
carries a product category, an urgency, a title, and a description, plus
the submitter if the embed passed their identity.
**Before you start:** the forms need at least one product category under
**Settings → Support Widgets → Support Hub**, or visitors cannot submit;
see [Put the Support Hub on your site](https://app.clientsphere.io/docs/setup/site/support-hub). A role with
**Read tickets**.
## Review the queue
**Support → Feature Requests** lists everything with its category,
urgency, status, submitter, company, and date. Filter by **Status**,
**Urgency**, or **Category**, or search title, description, and submitter.
A submitter shown as **Anonymous** means the embed did not pass the user's
identity. The request is still real; there is just nobody to follow up
with. Installing the identity snippet fixes that for future submissions.
## Work a request
Open a row. The sheet shows the description, the submitter, and two things
you set:
- **Status**: New, Reviewing, Planned, Shipped, Declined. Move requests
through these as decisions are made.
- **Internal notes**: "Notes for your team — not visible to the
submitter." They save when you click away.
**Delete** removes the request permanently. The dialog is clear that the
submitter is not notified either way; there is no reply channel from this
screen. If you want to tell someone their idea shipped, the submitter's
email is on the sheet.
## Use the numbers
Requests per account is a useful engagement signal: customers engaged
enough to ask for things are rarely the ones about to leave. Filter by
company to see who is asking.
## When it goes wrong
- **The queue is empty but visitors say they submitted.** Check that the
card or menu item exists and that a product category is configured; with
none, the form cannot be submitted.
- **Everything is Anonymous.** The basic embed snippet is in use. See the
identity snippet in
[Put the floating launcher on your product](https://app.clientsphere.io/docs/setup/site/floating-launcher).
- **The Category filter only offers a few values.** It lists the categories
present in the current results, not every configured one.
# Write and publish articles
Source: https://app.clientsphere.io/docs/use/support/articles
Draft help articles, organise them in categories, publish them to customers and the AI, and find the ones that need fixing.
Articles are the content of your help centre. The same article is read by
customers on the public knowledge base, by agents drafting replies, and by
the AI when it answers a visitor or an email. Publishing is the moment all
three start using it.
**Before you start:** who can create, publish, and manage categories is
set under **Support → Knowledge Base → Configuration**; see
[Publish your knowledge base](https://app.clientsphere.io/docs/setup/site/publish-knowledge-base). If you cannot
see **New Article**, that is why.
## Write an article
**Support → Knowledge Base → New Article**:
- **Title** and **Content** are required. The content editor is rich
text.
- **Excerpt** is the summary shown in lists and search results. Write it;
the AI uses it too.
- **Category** groups the article; **Tags** are comma-separated and help
search.
- **Status**: **Draft** is internal, **Published** is live everywhere,
**Archived** hides it without deleting.
- **Featured Article** promotes it on the help centre's front page.
Under **SEO Settings**, the **URL Slug** is generated from the title until
you edit it, and **SEO Title** and **SEO Description** override what search
engines show. The counters turn red past 60 and 155 characters but do not
block saving.
[Screenshot: The Create New Article dialog]
## Organise with categories
The **Categories** tab creates and edits categories with a name and a
description. Deleting a category leaves its articles in place as
uncategorised. Category names also become the help centre's SEO keywords
unless you set your own.
## Publish
Set **Status** to **Published** and save. From that moment the article is
on the public help centre if public access is on, searchable from the chat
widget and the launcher, offered to agents in the ticket composer, and
used by the AI.
**Publishing changes what the AI says.**
A published article is an instruction to the auto-responder. Publish a
wrong refund policy and the AI will quote it to customers within the hour.
Keep publishing rights narrower than drafting rights until reviews are
routine.
## Find what needs fixing
The **Analytics** tab shows totals, **Most Viewed Articles**, **Most
Helpful Articles** ranked by helpfulness ratio, and **Needs Attention**,
which lists articles rated helpful less than half the time. Those are the
ones to rewrite first; they are what readers found and did not trust.
**Product Analytics** adds the other half: the searches that found no
article at all. Together they are the writing queue.
## When it goes wrong
- **The article is not on the public site.** Its status is Draft, or
public access is off.
- **The AI does not use a new article.** It is still a draft, or the AI
is off for that channel.
- **"Title is required" or "Content is required".** Both must be filled.
- **A slug conflicts.** Edit the **URL Slug** to something unique; the
public URL shown under the field updates as you type.
# Quotes and invoices
Source: https://app.clientsphere.io/docs/use/finance/quotes-and-invoices
Send a quote, turn it into an invoice, record payments against it, share it by link, and set up recurring plans. And what the product does not do yet.
**Finance → Invoicing** holds quotes, invoices, a payments ledger, and
recurring plans, with a products catalogue behind them. It tracks what you
have quoted, billed, and been paid. It does not yet send anything by email,
which is the single most important thing to know before you rely on it.
**Before you start:** roles with **Read quotes** or **Read invoices** to see
the section, and the matching create and update permissions to work in it.
Add your **Products & Services** first so line items can be picked rather
than typed.
## Products and services
**Finance → Products & Services → Add Product**: a name, an optional
description, a **Unit Price**, a **Tax Rate**, and whether it is a product
or a service. **Archive** hides one from the pickers without touching the
quotes and invoices that already use it; deleting does not affect them
either.
## Quotes
**Finance → Invoicing → Quotes → New Quote**. A quote has line items, a
validity date, payment terms, and notes, and moves through **Draft**,
**Sent**, **Approved**, **Declined**, **Expired**, and **Converted**.
Status changes are manual. **Mark as sent** on a draft, and **Mark as
Approved**, **Mark as Declined**, and so on in the **Actions** menu, record
what happened; nothing leaves ClientSphere when you mark a quote sent.
**Preview** opens it as the customer would see it, and **Download PDF**
produces the file to send.
**Convert to Invoice** appears on an approved quote, on its detail page and
in the quotes list's row menu, and creates the invoice with the same lines,
then opens it.
## Invoices
**Invoices → New Invoice**, or convert a quote. Statuses are **Draft**,
**Sent**, **Paid**, **Partial**, **Overdue**, and **Cancelled**.
- **Preview** opens the invoice at a public share link, a URL with a token
rather than the invoice id, so it can be revoked. That is the link to
give a customer.
- **Download PDF** produces the file.
- **Mark as sent** records that a draft went out. It does not email anyone.
- **Record Payment** takes an amount up to the remaining balance, a
**Payment Method** of Manual, Credit Card, Bank Transfer, Check, or Cash,
and an optional reference and notes. A full payment sets the invoice to
**Paid**; a smaller one to **Partial**. The **Payment History** and
**Payment Summary** on the invoice show the balance.
- **Mark Overdue** and **Cancel Invoice** are manual too. Sent invoices
past their due date are also moved to Overdue by an hourly job.
**Payments** in the sub-navigation is the ledger across every invoice,
filterable by method and date, with **Export CSV**.
## Recurring plans
**Recurring** lists plans that generate an invoice on a schedule: weekly,
monthly, quarterly, or annually. Each shows its next invoice date and how
many it has generated. **Pause** stops generation without deleting the
plan; **Resume** picks it up again; **Delete** removes the plan and leaves
the invoices it already produced. Generation runs hourly.
## The overview
**Overview** shows total quotes and invoices, outstanding, overdue, paid
this month, revenue year to date, a monthly revenue chart, and a status
breakdown. Money is shown in dollars regardless of the currency recorded
on individual invoices.
## What it does not do yet
- **Email an invoice or a quote.** "Sent" is a status you set. Download
the PDF or share the link yourself.
- **Payment reminders.** The fields exist; nothing sends them.
- **Multiple currencies.** Each invoice records a currency, but totals are
summed as plain numbers. Keep one currency per workspace.
- **Online payment.** Payments are recorded after the fact, not collected.
## When it goes wrong
- **"Please enter a valid payment amount."** The amount is blank, zero, or
more than the balance.
- **Record Payment is disabled.** The invoice is cancelled or already paid.
- **Convert to Invoice is missing.** The quote is not **Approved**.
- **A cancelled invoice still shows as outstanding.** It does not; check
the status filter on the list.
# Documents
Source: https://app.clientsphere.io/docs/use/finance/documents
Upload contracts, proposals, and templates, file them by category, and attach them to the account they belong to.
Documents is a shared file library for the workspace: contracts, SLAs,
proposals, and templates, each filed under a category and optionally
attached to an account.
**Before you start:** a role with **View documents** to see the library and
**Upload documents** to add to it.
## Upload a document
**Resources → Documents → Upload Document**. Two steps:
1. **Upload File.** PDF, Word, Excel, and PowerPoint files up to 10 MB.
The file uploads immediately and shows its size when done.
2. **Add Details.** A **Document Name** and a **Category** are required:
Contracts, SLAs, Proposals, Templates, or Other. A description is
optional. **Associated Account** attaches it to a customer, so it shows
on that account too. **Mark as template** flags it as one to reuse;
the helper says templates are available to all team members.
**Create Document** finishes.
## Find and use documents
Search by name, or filter by category. Each row offers **Download** and
**Delete**. Deleting asks for confirmation and cannot be undone; the file
is removed from storage, not just the list.
## When it goes wrong
- **"Please upload a file before submitting."** Step 1 did not complete.
Choose the file again and wait for the size to appear.
- **"Please select a document category."** Category is required.
- **The file is refused.** It is over 10 MB or not one of the supported
types. Compress it, or share a link instead.
- **A document is not on the account.** It was uploaded without an
associated account. There is no edit for that yet; upload it again with
the account set and delete the first copy.
# Reports
Source: https://app.clientsphere.io/docs/use/insights/reports
The built-in reports and headline figures by category, exactly how each figure is calculated, and how to build and export your own report.
**Analytics → Reports** holds the built-in reports, headline figures with
their definitions, and a builder for your own. The definitions matter
more than the charts: two people looking at "pipeline value" should mean
the same thing, and the tooltips on this page are where that is settled.
**Before you start:** a role with **View reports**. The SLA figures only
mean something once [working hours and SLAs](https://app.clientsphere.io/docs/setup/email/working-hours-slas-assignment)
are set.
## Choose a view
Tabs across the top: **My Reports**, **Team Performance**, **Sales**,
**Support**, **Team**, **Financial**, and **Leads**. Each shows the
figures and built-in reports for that area.
Two controls apply everywhere:
- **Date range**: 7 days, 30 days, 90 days, 1 year, or **Custom**.
- **Date basis**: **Created** or **Activity**. It filters SLA metrics and
report data by either the record's creation date or its last activity.
The headline figures always use created date.
## What the figures mean
These are the tooltips, verbatim, because they are the definitions.
| Figure | Definition |
|---|---|
| **Pipeline Value** | Sum of open opportunity values (excludes both closed-won and closed-lost). Won deals are shown separately as Won Revenue. |
| **Won Revenue** | Sum of opportunity values with stage 'closed_won' |
| **Conversion Rate** | Percentage of opportunities that reached 'closed_won' out of all opportunities |
| **Lead Conversion** | Percentage of leads that reached 'converted' stage out of all leads |
| **Sales SLA** | Percentage of sales inbox items responded to within the SLA deadline |
| **Sales Median Response** | Median working-hours time from sales email received to first agent reply (excludes nights/weekends per your configured working hours; median ignores outliers) |
| **Unresolved Tickets** | Tickets with status: new, open, in progress, pending customer, or escalated |
| **Support SLA** | Percentage of tickets responded to within the SLA deadline |
| **SLA Breaches** | Number of tickets that exceeded their SLA deadline in the selected period |
| **Support Median Response** | Median working-hours time from ticket creation to first agent reply (excludes nights/weekends per your configured working hours; median ignores outliers) |
| **Overdue Invoices** | Invoices that are past due date and not paid or cancelled |
A dash means there is no data yet for that figure in the range.
[Screenshot: The Reports header: category tabs, the Created and Activity date basis, the range, and the figure tiles]
## The built-in reports
Twenty-one reports cover pipeline by stage and value, deals and revenue by
lead source, deals by forecast, tickets by status, priority, type, and
module, chat conversations per agent, by status, by channel, and by close
reason, accounts by owner and size, tasks by status, invoices and invoice
revenue by status, and leads by stage, source, and average score. Each
opens as a chart with the underlying rows.
## Build your own
**Create Report** opens the builder:
1. A **Report Name** and a **Data Source**: Accounts, Contacts,
Opportunities, Tickets, Tasks, Activities, Invoices, or Leads.
2. **Group By** a field of that source.
3. A **Chart Type** and an **Aggregation**: Count, or Sum, Average,
Minimum, or Maximum of a **Value Field** such as deal value, estimated
hours, invoice total, or lead score. Sources with no numeric field only
support Count.
4. Optional **Filters**, each a field, an operator (`=`, `!=`, `>`, `<`,
`contains`), and a value.
5. **Generate Preview** to check it, then **Save Report**.
Saved reports live under **My Reports**, where each can be viewed,
exported as CSV, or deleted.
## When it goes wrong
- **SLA figures show a dash or look wrong.** Working hours or SLAs are not
set, or there were no items in the range. Median response excludes
nights and weekends by design.
- **"Please select a data source and group by field."** Both are needed
before a preview.
- **"No numeric fields for this data source. Use Count instead."**
Contacts, Tickets, Accounts, and Activities have nothing to sum.
- **Pipeline Value seems low.** It excludes won deals. Add Won Revenue for
the total.
# Product Analytics
Source: https://app.clientsphere.io/docs/use/insights/product-analytics
Who is using your product, which customers are going quiet, and what people search for without finding an answer. What each number means and where it comes from.
**Analytics → Product Analytics** shows how your customers use your
product. All of it comes from one source: the floating launcher, installed
on your product with the logged-in user's identity. Until that is in place
the page says so and shows nothing.
**Before you start:** [Put the floating launcher on your product](https://app.clientsphere.io/docs/setup/site/floating-launcher)
with the identity snippet. A role with **View analytics**.
## How the data is collected
When a page of your product loads with the launcher on it, the launcher
records that this person was in the product today, and the page they
landed on. It does that at most once every six hours per person per
browser, so it is not a page-view counter. Every help search made from the
launcher is logged with whether it found anything.
The numbers are near real time. A person's first visit of the day shows
within seconds. Their "last seen" can lag by up to six hours because of the
throttle. Days are counted in UTC.
## The page
Pick **Last 7 days**, **Last 30 days**, or **Last 90 days** at the top.
**Four tiles**, each against the previous period:
- **Active today** and **Active this week**: distinct people seen.
- **Active accounts this week**: distinct customers with at least one
person seen.
- **Stickiness**: average daily actives divided by distinct actives over
the range. If 100 people used the product this month and 10 on a
typical day, stickiness is 10%. High means it is part of people's
routine; low means they dip in occasionally.
**Active users over time**: daily actives as one line, and the trailing
seven-day actives as another. The second line smooths weekends out.
**Active accounts**: your customers ranked by people active in the last
30 days, with this week's count, users ever seen, and last seen. A **Going
quiet** badge marks an account that had activity in the 30 days ending two
weeks ago and none since. That is the early churn signal; open the account
and look at its tickets and deals.
**Unanswered help searches**: searches that returned no article, grouped
by query, with how often, from which pages, and when last asked. The
header shows total searches and the share that found nothing. This list is
your knowledge base writing queue; see
[Write and publish articles](https://app.clientsphere.io/docs/use/support/articles).
**Where people land**: the first page each person hit each day, grouped.
It tells you what people open the product for.
**Recently seen**: people in the order they were last seen, with their
account and today's landing page. Rows link to the contact.
Each table shows one page at a time, ten rows for accounts and people
and five for searches and landing pages, with **Previous** and **Next**
under it when there is more. Changing the range takes you back to the
first page.
## Where else it shows
Each contact's profile shows **Last seen in product** and days active out
of the last 30. Each account's Contacts card shows how many of its people
were active this week and this month.
## When it goes wrong
- **"No product activity recorded yet."** The launcher is not installed,
or it was installed with the basic snippet rather than the identity one.
- **A known user never appears.** Their email in the snippet does not match
their contact, so a new contact was created for them. Search contacts for
the address.
- **The latest day reads as yesterday.** Days are UTC. Between midnight
and the UTC boundary the current day has not started yet.
- **Last seen is hours behind.** Expected; the launcher identifies at most
once every six hours per browser.
# Dashboard and AI insights
Source: https://app.clientsphere.io/docs/use/insights/dashboard-and-insights
What the dashboard shows, and how to turn on the daily AI briefing, read its cards, and dismiss the ones you have handled.
The dashboard is the first screen after sign-in: a greeting, quick-create
buttons, four headline figures, your recent tasks, recent email, recent
companies, and, when it is switched on, a daily **AI Insights** briefing.
**Before you start:** the headline figures need **View analytics**; without
it they read "Restricted Access". The insights panel needs **View AI
insights**, and turning it on needs **Manage AI agent**.
## The panels
- **Quick actions**: New Contact, New Deal, New Ticket, New Lead, New
Account.
- **Total Accounts**, **Pipeline Value**, **Conversion Rate** with the
number of open deals, and **Active Tickets**, which reads "All good"
until there are urgent ones.
- **My Recent Tasks**: your uncompleted tasks with due dates, and how
overdue they are.
- **Recent Email Activity**: from a connected Gmail account; empty until
one is [connected](https://app.clientsphere.io/docs/setup/email/connect-gmail).
- **Recent Companies**: the newest accounts.
## AI insights
The **AI Insights** panel is a daily briefing written by the assistant from
your pipeline, support, leads, and, optionally, customer sentiment. Each
card has a category, a severity of Critical, Warning, Info, or Positive, a
short finding, and often a link into the records it is about, such as the
tickets that breached SLA.
### Turn it on
**Settings → AI Agent → Insights**, or the **Configure** button on the
panel while it is off:
- **Enable daily insights**. It needs the workspace's AI master switch on
as well; see [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai).
- **Schedule hour (UTC)**: generation runs once a day after this hour.
- **Coverage period (days)**: how far back to analyse, 7 to 90.
- **Customer sentiment analysis** scores recent customer messages per
account. It uses additional AI tokens.
- **Enabled categories**: leave all unchecked and the model picks, or
constrain it to Pipeline, Support, Leads, Sentiment, Reps, Anomaly, and
Conversion.
Until the first scheduled run, the panel says it is waiting. **Run now** on
the settings card generates a briefing immediately, at most three times a
day.
### Read and dismiss
Filter the cards by severity. The **X** on a card dismisses it for you
only, with no confirmation; a dismissed card does not return on later runs.
When every card is dismissed the panel says "Nothing notable today — all
your dismissals are also applied."
## When it goes wrong
- **"Daily insights are off — enable in Settings."** The toggle is off.
- **"Waiting for the first scheduled run."** Use **Run now**, or wait for
the schedule hour.
- **"The most recent generation failed."** It retries on the next daily
run. If it keeps failing, check the AI usage and the master switch.
- **Figures read "Restricted Access".** The role lacks **View analytics**.
- **Recent Email Activity is empty.** No Gmail account is connected for
you.
# Ask the AI assistant
Source: https://app.clientsphere.io/docs/use/insights/ai-assistant
What the assistant can see, what to ask it, how the context your admin set shapes its answers, and where its conversations live.
The AI assistant is a coach that can read your CRM. It opens from **Ask
AI** in the header as a side panel, or as a full page under
**AI Assistant**. Ask it about a deal, a ticket, an account, or your whole
pipeline, and it answers from your data rather than in general.
**Before you start:** the assistant is available to anyone whose role
includes it. What it knows about your business comes from **Settings → AI
Agent → Context** and **Documents**, set by an admin; see
[Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai). It works even with those empty, but the
advice is generic until they are filled in.
## What it can see
The records your role can see: accounts, contacts, leads, opportunities,
tickets, tasks, activities, quotes, invoices, and the knowledge base. It
looks things up as you ask, so "which deals are closing this month" is
answered from the live pipeline, not from memory.
It also reads the five context fields your admin filled in, such as your
products, ideal customer, sales playbook, and support policies, and any
documentation imported for it. That is how it knows your discount policy
when you ask how to handle an objection.
## What to ask
The panel suggests prompts for the page you are on:
- On a deal: how to approach it, what the next steps are, draft a
follow-up email.
- On a ticket: how to resolve it, suggest a response, whether to escalate.
- On an account: summarise it, open opportunities, overdue tasks.
- On the pipeline: its health, which deals need attention, what closes
this month.
- On the dashboard: a daily briefing, what needs attention today.
Anything in that shape works. Be specific: "summarise Northwind Traders"
beats "tell me about my accounts".
## Conversations
The side panel keeps one running conversation and can hand it to the full
page with **Continue in full page**. The full page keeps a list of past
conversations on the left, dated, with **New Chat** to start fresh. The
bin on a conversation deletes it and its messages permanently.
Enter sends a message; Shift+Enter adds a line.
## What it does not do
It does not change records on its own, send email, or act on tickets. It
drafts and advises; you act. The AI that answers customers directly is a
separate thing, configured per channel; see [Turn on AI](https://app.clientsphere.io/docs/setup/ai-and-developers/turn-on-ai).
## When it goes wrong
- **The answer is generic.** The context fields are empty. Ask an admin to
fill in **Products & Services** and **Support Policies** at minimum.
- **It cannot find a record.** It searches within what your role can see,
and by the names and emails on the records. Try the exact account name.
- **A reply shows "Error".** Usually a temporary failure; send the message
again. Persistent errors mean the AI is disabled or out of quota, which
an admin can check under **Settings → AI Agent → Usage**.
# Notifications
Source: https://app.clientsphere.io/docs/use/insights/notifications
What ClientSphere notifies you about, where to find them, and how to clear them.
The bell in the header shows how many notifications you have not read.
Clicking it, or opening **Notifications** directly, shows the Notification
Center.
## What you are told about
| Type | When |
|---|---|
| **Ticket Assigned** | A ticket is assigned to you |
| **Task Overdue** | A task you own passes its due date |
| **Comment Added** | Someone comments on a task or ticket you are on |
| **Status Changed** | A record you follow changes status |
| **Account Updated** | An account you own is changed |
| **User Mentioned** | Someone types `@` and your name in a note or comment |
| **Due Date Reminder** | A task's due date is approaching |
| **Escalation** | A ticket is escalated, or a chat visitor asks for a human |
Each carries a priority of Urgent, High, Normal, or Low.
## Read and clear
Tabs split the list into **All**, **Unread**, and **Read**. Filter by
type or priority, or search. Each row links to the record it is about; the
tick marks that one read, and **Mark all as read** clears the count.
Notifications are per person. Marking yours read does not affect a
colleague's.
## When it goes wrong
- **You are not told about something you expected.** Notifications follow
ownership and mentions. If a ticket is not assigned to you and nobody
mentioned you, there is nothing to send.
- **The count will not go down.** Some notifications are on the Unread tab
filtered out by a type or priority filter. Clear the filters and use
**Mark all as read**.
---
Track: Build
# ClientSphere API
Source: https://app.clientsphere.io/docs/build
A REST API for the accounts, contacts, opportunities, leads and messaging behind your ClientSphere workspace.
The ClientSphere API is a REST API over the same data your workspace uses:
accounts and their notes, contacts, leads and opportunities; quotes, invoices,
tickets and tasks; the knowledge base; and transactional email.
Every endpoint lives under `/api/v1`, takes and returns JSON, and is
authenticated with an API key you create in **Settings → API Keys**.
## Start here
- [Quickstart](https://app.clientsphere.io/docs/build/guides/quickstart): Make your first authenticated request in a couple of minutes.
- [Authentication](https://app.clientsphere.io/docs/build/guides/authentication): API keys, the two ways to send one, and what a key is allowed to do.
- [Test and live data](https://app.clientsphere.io/docs/build/guides/test-and-live-data): How sk_test_ and sk_live_ keys separate sandbox data from production.
- [Support Hub](https://app.clientsphere.io/docs/build/guides/support-hub): Install the hub on your site, and identify visitors to it.
- [Floating launcher](https://app.clientsphere.io/docs/build/guides/floating-launcher): A support button and quick-action menu — the other embed.
- [API reference](https://app.clientsphere.io/docs/build/api/accounts/list-accounts): Every endpoint, with parameters, responses and a request you can send.
## What to know before you build
Four things behave the same way across every endpoint, and reading them once
will save you rediscovering them one at a time:
- [Authentication](https://app.clientsphere.io/docs/build/guides/authentication) — one key, sent as a bearer
token or an `X-API-Key` header; the key's permissions decide what it may
call.
- [Pagination](https://app.clientsphere.io/docs/build/guides/pagination) — list endpoints wrap results in a
`data` array with `meta.pagination` beside it, never a bare array.
- [Errors](https://app.clientsphere.io/docs/build/guides/errors) — every failure is a JSON body with a stable
`error.code` worth branching on.
- [Rate limits](https://app.clientsphere.io/docs/build/guides/rate-limits) — 60 requests a minute per key by
default, with the remaining budget in the response headers.
- [Test and live data](https://app.clientsphere.io/docs/build/guides/test-and-live-data) — a key is bound to one
or the other and cannot cross over.
# Quickstart
Source: https://app.clientsphere.io/docs/build/guides/quickstart
Create an API key and make your first authenticated request to the ClientSphere API.
This walks through one request end to end. It should take a couple of minutes.
## 1. Create an API key
In your workspace, go to **Settings → API Keys** and create a key.
You choose whether the key is a **test** or **live** key at creation, and that
decision is fixed for the life of the key. Test keys are prefixed `sk_test_`
and read and write sandbox data; live keys are prefixed `sk_live_` and touch
production data. See [Test and live data](https://app.clientsphere.io/docs/build/guides/test-and-live-data).
The key is shown once. Store it somewhere your application can read it as a
secret — never in client-side code or a public repository.
## 2. Make a request
Every endpoint is under `/api/v1`. List the accounts in your workspace:
```bash
curl https://clientsphere.io/api/v1/accounts \
-H "Authorization: Bearer sk_test_your_key_here"
```
A successful response looks like this — a `data` array plus a `meta` object,
never a bare array:
```json
{
"data": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Halcyon Foods",
"status": "active",
"industry": "Food & Beverage"
}
],
"meta": {
"pagination": { "page": 1, "limit": 20, "totalCount": 1, "totalPages": 1 }
}
}
```
## 3. Create something
Most write endpoints take the resource's fields directly and return the created
record with its generated `id`:
```bash
curl -X POST https://clientsphere.io/api/v1/accounts \
-H "Authorization: Bearer sk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "name": "Northstar Labs", "status": "prospect" }'
```
That responds `201` with the new account. A `400` means the body failed
validation, and the response tells you which fields — see
[Errors](https://app.clientsphere.io/docs/build/guides/errors).
## Next
- [Authentication](https://app.clientsphere.io/docs/build/guides/authentication) — the second way to send a key,
and what a key is permitted to do
- [Pagination](https://app.clientsphere.io/docs/build/guides/pagination) — walking a list longer than one page
- The [API reference](https://app.clientsphere.io/docs/build/api/accounts/list-accounts) — every endpoint, with a
request you can send from the page
# Authentication
Source: https://app.clientsphere.io/docs/build/guides/authentication
How to send a ClientSphere API key, and what determines whether a key may call a given endpoint.
Every request to `/api/v1` must carry an API key. Requests without one are
rejected with `401` and `error.code` of `UNAUTHORIZED`.
Create keys in **Settings → API Keys**. A key is shown once at creation.
## Sending a key
Two headers work, and they are equivalent — use whichever fits your HTTP client.
As a bearer token:
```bash
curl https://clientsphere.io/api/v1/contacts \
-H "Authorization: Bearer sk_live_your_key_here"
```
Or as a dedicated header:
```bash
curl https://clientsphere.io/api/v1/contacts \
-H "X-API-Key: sk_live_your_key_here"
```
## When a key is rejected
All three rejections are `401`, and the code tells you which problem you have:
| `error.code` | What happened |
| --- | --- |
| `UNAUTHORIZED` | No key was supplied at all — neither header was present. |
| `INVALID_KEY` | A key was supplied but the API will not accept it. |
| `KEY_EXPIRED` | The key was genuine, but its expiry date has passed. |
`INVALID_KEY` covers three cases, and the message distinguishes them:
- The key is not one we issued, or has been **deactivated** in
**Settings → API Keys**. This is by far the most common cause — check the key
still exists and is active before looking anywhere else.
- The key was **truncated or mistyped** in transit.
- The **prefix does not match the key's mode**. A key is created as either test
or live and its prefix reflects that: `sk_test_` or `sk_live_`. The prefix is
not decoration — the API checks it against the key's own mode and rejects a
mismatch, telling you which way round it went.
## Keys can expire
A key may be given an expiry date when it is created. Past that moment it stops
working and returns `401 KEY_EXPIRED` — the key is not deleted, so it is still
listed in **Settings → API Keys**, which is what makes this one easy to
misdiagnose as a permissions problem.
Keys without an expiry date do not expire. If an integration fails at a
suspiciously round moment, check the expiry before anything else.
## Permissions
A key carries exactly the permissions it was granted at creation. Nothing is
added later: a key created before a feature existed does **not** silently gain
access to it, and a key deliberately scoped without a permission keeps that
scoping.
Calling an endpoint the key lacks permission for returns `403` with
`error.code` of `FORBIDDEN`. That is different from `401`, which means the key
was missing or unusable. If you get a `403` from a request you expect to work,
check the key's permissions in **Settings → API Keys** rather than the key
itself.
## Keeping keys safe
- Send keys only from server-side code. Anything in a browser is public.
- Give each integration its own key, so one can be revoked without disturbing
the others.
- Use a `sk_test_` key everywhere that is not production. See
[Test and live data](https://app.clientsphere.io/docs/build/guides/test-and-live-data).
# Test and live data
Source: https://app.clientsphere.io/docs/build/guides/test-and-live-data
How sk_test_ and sk_live_ API keys keep sandbox data and production data completely separate.
ClientSphere keeps a sandbox alongside your production data. It is not a
separate account or a second environment to provision — it is the same
workspace, with its own set of records that your real customers never see.
Which one a request touches is decided entirely by the API key.
## One key, one side
A key is created as either test or live and stays that way:
| Prefix | Reads and writes |
| --- | --- |
| `sk_test_` | Sandbox data |
| `sk_live_` | Production data |
There is no per-request override — no header, no query parameter. A key cannot
reach across, which is the point: an integration pointed at a test key cannot
email a real customer or delete a real account, however wrong its logic is.
The prefix must match the key's mode, and the API rejects a mismatch with `401`
and `INVALID_KEY`.
## Working with both
The usual arrangement is a `sk_test_` key in local development, CI and staging,
and a `sk_live_` key only in production, supplied as a secret at deploy time.
Because the two never mix, you can run a full integration suite against the
sandbox as often as you like.
Records created with a test key are only ever visible to test keys. If a record
you just created seems to have vanished, the most common cause is creating it
with one key and reading it with the other.
## What is shared
Configuration belongs to the workspace, not to one side: your users, roles,
and the API keys themselves are the same for both. It is the business records —
accounts, contacts, opportunities, leads, messages — that are separated.
# Pagination
Source: https://app.clientsphere.io/docs/build/guides/pagination
How list endpoints page their results, and how to walk a collection larger than one page.
Most list endpoints return a page of results rather than the whole collection.
A handful return everything in one response instead — see
[the unpaginated endpoints](#the-unpaginated-endpoints).
## The response shape
A paginated response is an object with a `data` array and a `meta` object. It
is never a bare array — code that assumes an array will break on the first
response it sees:
```json
{
"data": [ /* ... */ ],
"meta": {
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 137,
"totalPages": 7
}
}
}
```
`totalCount` is the number of records matching your filters across all pages,
not the number in `data`.
## Parameters
| Parameter | Default | Notes |
| --- | --- | --- |
| `page` | `1` | Page number, starting at 1 |
| `limit` | `20` | Items per page, maximum `100` |
| `search` | — | Free-text search across the resource, where supported |
```bash
curl "https://clientsphere.io/api/v1/contacts?page=2&limit=50" \
-H "Authorization: Bearer sk_live_your_key_here"
```
## Walking every page
Loop until you have reached `totalPages`, rather than until you get an empty
page — that costs one request fewer and does not depend on how the last page
happens to fall:
```javascript
async function everyContact(apiKey) {
const all = [];
let page = 1;
let totalPages = 1;
do {
const res = await fetch(
`https://clientsphere.io/api/v1/contacts?page=${page}&limit=100`,
{ headers: { Authorization: `Bearer ${apiKey}` } },
);
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const body = await res.json();
all.push(...body.data);
totalPages = body.meta.pagination.totalPages;
page += 1;
} while (page <= totalPages);
return all;
}
```
Use `limit=100` when you are walking a whole collection — it is the maximum,
and it makes the loop do a fifth of the requests the default would.
Bear in mind the default rate limit of 60 requests a minute per key when
paging through something large. See [Rate limits](https://app.clientsphere.io/docs/build/guides/rate-limits).
## The unpaginated endpoints
Five endpoints return every matching record in a single response. They still
wrap the results in `data`, but there is **no `meta` object at all**, and
`page`, `limit` and `search` are ignored if you send them:
| Endpoint | Returns |
| --- | --- |
| [`GET /widgets`](https://app.clientsphere.io/docs/build/api/widgets/list-widgets) | Every widget in the workspace |
| [`GET /activities`](https://app.clientsphere.io/docs/build/api/activities/list-activities) | The whole activity feed |
| [`GET /tasks/overdue`](https://app.clientsphere.io/docs/build/api/tasks/list-overdue-tasks) | Every overdue task |
| [`GET /knowledge-base/categories`](https://app.clientsphere.io/docs/build/api/knowledge-base/list-knowledge-base-categories) | Every category |
| [`GET /knowledge-base/articles/search`](https://app.clientsphere.io/docs/build/api/knowledge-base/search-knowledge-base-articles) | Search matches, up to `limit` |
```json
{
"data": [ /* every record */ ]
}
```
So `body.meta.pagination.totalPages` throws on these. A generic client that
assumes `meta` is always present needs to tolerate its absence.
Most of them are small by nature — a workspace has a handful of widgets and
categories, not thousands. `GET /activities` is the one to watch: the activity
feed grows without bound and has no filters, so it gets slower as a workspace
ages.
### Search has its own shape again
[`GET /knowledge-base/articles/search`](https://app.clientsphere.io/docs/build/api/knowledge-base/search-knowledge-base-articles)
nests its results one level deeper, with the total beside them rather than in
`meta`:
```json
{
"data": {
"articles": [ /* ... */ ],
"totalCount": 42
}
}
```
`totalCount` is the number of matches, which can exceed the number returned —
`limit` defaults to `10` on this endpoint rather than the usual `20`, and there
is no way to ask for the next page.
## A note on ordering
Records created or deleted while you are paging can shift results between
pages, so a long walk is not a consistent snapshot. For large exports, prefer
filtering to a narrow window over paging the entire collection.
# Errors
Source: https://app.clientsphere.io/docs/build/guides/errors
The error response shape the ClientSphere API returns, and what each error code means.
Every failure returns a JSON body with the same shape, whatever went wrong:
```json
{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found."
}
}
```
Branch on `error.code`. It is stable and meant to be read by your code.
`message` is meant for a human reading a log and may be reworded.
## Codes
| Status | `error.code` | Meaning |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | The body failed validation. Carries a `details` array naming the fields. |
| `400` | `INVALID_ID` | A path parameter is not a well-formed UUID. Note this is **not** a `404`. |
| `400` | `INVALID_EMAIL` | An email-shaped path parameter or field is not a valid address. |
| `400` | `INVALID_CONTACT_ID` | A `contactId` in the body is not a well-formed UUID. |
| `401` | `UNAUTHORIZED` | No API key was supplied at all. |
| `401` | `INVALID_KEY` | The key is unknown, deactivated, or its prefix does not match its mode. |
| `401` | `KEY_EXPIRED` | The key was valid but has passed its expiry date. |
| `403` | `FORBIDDEN` | The key is valid but lacks the permission this endpoint needs. |
| `404` | `NOT_FOUND` | No such record in this workspace. |
| `409` | `NO_ELIGIBLE_ACTOR` | Creating a widget found nobody to attribute it to — see below. |
| `429` | `RATE_LIMITED` | Too many requests — see [Rate limits](https://app.clientsphere.io/docs/build/guides/rate-limits). |
| `500` | `INTERNAL_ERROR` | Something failed inside the API. |
[Sending transactional email](https://app.clientsphere.io/docs/build/api/transactional-email/send-transactional-email)
adds a few statuses of its own — `202`, `409`, `413`, `422` and `502` — which
are documented on that endpoint rather than here.
## NO_ELIGIBLE_ACTOR
Widgets record who created them, and that column cannot be null. An API key is
not a person, so the API attributes the widget to a real user: the one who
created the key, failing that the workspace owner, failing that any active
user.
If none of those exist — typically because the person who created the key has
since left and no other active user remains — the request is refused with `409`
rather than writing a row it cannot attribute. Reactivate a user in the
workspace and retry; the request is unchanged and safe to send again.
## A bad id is a 400, not a 404
This is the one that surprises people. An id that is not a well-formed UUID is
rejected before anything is looked up, so it comes back `400 INVALID_ID`:
```json
{
"error": {
"code": "INVALID_ID",
"message": "Invalid account ID format."
}
}
```
`404 NOT_FOUND` means the id was well-formed and simply matched nothing. So if
you are threading ids through from somewhere else, a `400` points at the
plumbing — a truncated value, a slug where a UUID belongs — and a `404` points
at the record.
## 401 and 403 are different problems
They are easy to conflate and they need opposite fixes.
`401` is about the key itself: absent (`UNAUTHORIZED`), unknown or deactivated
or carrying the wrong prefix for its mode (`INVALID_KEY`), or past its expiry
(`KEY_EXPIRED`). `403` means the key authenticated perfectly well and is simply
not allowed to do this — the fix is the key's permissions, in
**Settings → API Keys**, not the credential.
The `403` message names the permission that was missing, so you rarely have to
guess which one to grant.
## Validation errors
A `400 VALIDATION_ERROR` includes a `details` array identifying what failed, so
you can surface it rather than showing a generic message. Each entry names the
field in `path` and explains the problem in `message`:
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input.",
"details": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["name"],
"message": "Required"
},
{
"code": "invalid_string",
"validation": "email",
"path": ["email"],
"message": "Invalid email"
}
]
}
}
```
`path` is an array because it addresses nested fields — a problem inside an
array element arrives as `["items", 0, "quantity"]`. Joining it with `.` is
usually enough to point a user at the right input.
## 500s
`INTERNAL_ERROR` means the failure was ours, not your request's. A read is
always safe to retry. For a write, the request may or may not have taken
effect, so re-check the record's state before sending it again rather than
assuming it was lost.
## 404 is workspace-scoped
Every request is scoped to the workspace its key belongs to. A `404` means no
such record **in that workspace** — an id that is perfectly real in another
workspace, or on the other side of the test/live divide, still returns `404`.
When a record you know exists returns `404`, check you are not reading with a
`sk_test_` key something written with a `sk_live_` one.
# Rate limits
Source: https://app.clientsphere.io/docs/build/guides/rate-limits
How many requests a ClientSphere API key may make, and how to handle being limited.
Requests are rate limited per API key, over a rolling one-minute window. The
default is **60 requests a minute**.
The limit belongs to the key, not to your workspace or IP address, so giving
each integration its own key also gives each its own budget.
## Reading your budget
Responses carry the standard `RateLimit-*` headers, so you can see where you
stand without waiting to be rejected:
| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests allowed in the window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Seconds until the window resets |
## Being limited
Exceeding the limit returns `429`:
```json
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Please slow down."
}
}
```
Nothing was processed, so the request is safe to retry. Wait for the window to
reset rather than retrying immediately — a tight retry loop just spends the
next window's budget on rejections too.
```javascript
async function request(url, apiKey, attempt = 0) {
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (res.status === 429 && attempt < 5) {
const reset = Number(res.headers.get('RateLimit-Reset') ?? 1);
await new Promise((r) => setTimeout(r, (reset || 1) * 1000));
return request(url, apiKey, attempt + 1);
}
return res;
}
```
## Staying under it
- Page with `limit=100` rather than the default `20` — a fifth of the requests
for the same data. See [Pagination](https://app.clientsphere.io/docs/build/guides/pagination).
- Spread bulk work over time instead of firing it in parallel.
- Cache things that rarely change rather than re-fetching them per operation.
If an integration legitimately needs more, a key's limit can be raised — the
60 a minute is a per-key default, not a fixed ceiling.
# Support Hub
Source: https://app.clientsphere.io/docs/build/guides/support-hub
Install the ClientSphere Support Hub on your site, identify visitors, and understand what it writes to your CRM.
The Support Hub is a single `
```
That is the minimum. `data-widget-id` is the only required attribute — without
it the script logs an error and stops.
Find the widget id in your workspace under **Customer Support → Support Hub**,
where the Install section also offers a ready-made snippet to copy.
The script must be loaded from your ClientSphere origin. The widget works out
which workspace to talk to from its own `src`, so pointing the tag at a copy
you host yourself will not work.
## Two modes
The same embed renders one of two ways, decided by a workspace setting rather
than by anything on the script tag:
| Mode | What a visitor sees |
| --- | --- |
| **Hub** | A landing grid of cards — search the help desk, get in touch, suggest an improvement — with chat one click away |
| **Chat-only** | The conversation directly, with no landing |
Hub is the recommended mode and chat-only is kept for workspaces that predate
it. A workspace that has never configured the hub falls back to chat-only, so
switching is a deliberate step.
Set it under **Customer Support → Support Hub**, along with the title, subtitle,
banner colour, and the cards themselves. Each card has a title, description,
icon and button label, and does one of:
| Card action | What it does |
| --- | --- |
| `chat` | Opens the conversation view |
| `kb_search` | Opens a knowledge base search overlay |
| `email_us` | Opens a form that raises a ticket by email |
| `feedback` | Opens a form for a feature or improvement suggestion |
| `link` | Opens the card's `target` URL in a new tab |
With no cards configured, hub mode seeds three: help desk search, get in touch,
and suggest an improvement.
Because the setting is workspace-level, it applies to **every** widget in the
workspace at once — there is no per-widget mode and no embed attribute that
overrides it. Everything else on this page works identically in both modes,
identification included.
## Identifying the visitor
If your site already knows who is signed in, tell the widget. Conversations
then arrive attached to a real person instead of an anonymous visitor:
```html
```
**Note.**
Identifying a visitor writes to your CRM on page load — before they open the
widget, click anything, or send a message. Read [what identification
creates](#what-identification-creates) before you add these attributes to a
high-traffic page.
There is no built-in form that asks a visitor for their email. Identification
happens only through these attributes, so a visitor you do not identify stays
anonymous for the whole conversation.
## What identification creates
The moment the widget loads with `data-user-email`, the workspace either finds
the matching contact or creates one:
| You send | What happens in the CRM |
| --- | --- |
| `data-user-email` | A contact is found by email, or created with `source` of `chat_widget` |
| `data-user-name` | Split into first and last name. Without it, the part of the email before the `@` becomes the first name |
| `data-user-company` | An account is found by name, or created with `status` of `prospect`, and linked to the contact |
For a contact that already exists, only blank fields are filled in — an
existing first name, last name or company is never overwritten by what the
widget sends.
Two consequences worth planning for:
- **Every identified visitor becomes a contact**, whether or not they ever chat.
On a page many signed-in users load, that is a lot of contacts.
- **`data-user-company` creates accounts from free text.** Two spellings of the
same company name produce two accounts, because the match is on the exact
name.
If either is a problem, leave the attribute off. The widget works fine without
identification, and you can attach the conversation to a person later.
If the CRM write fails, the widget still works — the session is created either
way, and the failure is deliberately swallowed so a CRM problem cannot stop
someone reaching you. Nothing surfaces in the page.
## Test and live data
Which side of the [test/live divide](https://app.clientsphere.io/docs/build/guides/test-and-live-data) a
conversation lands on is decided by **the widget**, not the embed. A widget
created in sandbox writes sandbox contacts and conversations; a live widget
writes production data. There is no attribute that overrides this.
So use a sandbox widget on staging and a live widget in production, and give
each environment its own `data-widget-id`.
## Every attribute
| Attribute | Required | What it does |
| --- | --- | --- |
| `data-widget-id` | **Yes** | Which widget to load. Missing, and the script logs an error and stops |
| `data-user-email` | No | Identifies the visitor. Creates or reuses a contact |
| `data-user-name` | No | Visitor's display name, split into first and last |
| `data-user-company` | No | Creates or reuses an account and links the contact to it |
| `data-user-id` | No | Your own id for the user, stored with the session |
| `data-user-avatar-url` | No | Avatar shown beside the visitor's messages |
| `data-customer-id` | No | Your own id for the customer, stored with the session |
| `data-customer-name` | No | Fallback display name. `data-user-name` wins when both are set |
| `data-theme` | No | `auto`, `light` or `dark`. Overrides the widget's configured theme |
## Loading it yourself
If you inject the script rather than writing it into the HTML — a single-page
app, or a tag manager — set the attributes on the element before you append it:
```html
```
Only one widget loads per page. A second script tag is ignored, with a warning
in the console, so a tag manager firing twice is harmless.
To remove the widget — on sign-out, say — call:
```javascript
window.chatWidgetDestroy();
```
That tears down the widget and releases the guard, so a later script tag can
load it again with different attributes. It is the supported way to switch from
an anonymous visitor to an identified one without a page reload.
## When the widget does not appear
- **The widget is inactive.** An inactive widget returns 404 for its
configuration and the script stops. Nothing renders and no session is
created, so no contact is created either.
- **The id is wrong.** Same outcome, same 404.
- **The tag has no `data-widget-id`.** The script logs an error naming the
missing attribute.
All three fail quietly on the page and report themselves in the browser
console, so check there first.
## Managing widgets over the API
Widgets can also be created and configured programmatically, rather than in the
workspace. The API exposes the usual set under `/api/v1/widgets` — list, fetch,
create, update and delete — taking the same appearance and behaviour settings
the workspace exposes, and returning the widget id you embed.
They are documented in the reference: [List widgets](https://app.clientsphere.io/docs/build/api/widgets/list-widgets),
[Get widget](https://app.clientsphere.io/docs/build/api/widgets/get-widget),
[Create widget](https://app.clientsphere.io/docs/build/api/widgets/create-widget),
[Update widget](https://app.clientsphere.io/docs/build/api/widgets/update-widget) and
[Delete widget](https://app.clientsphere.io/docs/build/api/widgets/delete-widget). They manage the widget
*record*; everything on this page is about the embed itself, which is the
part your site interacts with.
Note that two stored settings, `requireEmail` and `collectVisitorInfo`, are not
currently read by the embed. They can be set and returned over the API, but the
shipped widget does not act on them — identification happens only through the
attributes above.
# Floating launcher
Source: https://app.clientsphere.io/docs/build/guides/floating-launcher
Install the floating launcher, a support button with a quick-action menu that is separate from the Support Hub.
The floating launcher is a small button pinned to a corner of your site. Click
it and a short menu opens — find answers, suggest an improvement, and whatever
links you add.
It is a **different embed from the [Support Hub](https://app.clientsphere.io/docs/build/guides/support-hub)**,
with its own script, its own settings and its own behaviour. They are easy to
confuse because they look similar on the page and accept some of the same
attributes.
## Which one do you want
| | Support Hub | Floating launcher |
| --- | --- | --- |
| Script | `chat-widget.js` | `support-launcher.js` |
| What it does | A conversation, with a hub landing if you enable one | A button and a short menu of actions |
| Live chat | Yes | No |
| Creates contacts | On page load, before any interaction | On page load, before any interaction |
| Creates accounts | Yes, when a company is given | Yes, when a company is given |
| Configured under | **Customer Support → Support Hub** | **Customer Support → Floating Launcher** |
If you want visitors to talk to you, you want the Support Hub. If you want a
tidy entry point to your help content and a way to collect suggestions, without
staffing a conversation, the launcher is the lighter option.
They can both be on the same page. They do not talk to each other — see
[using both](#using-both).
## Install
```html
```
The launcher needs to know which workspace it belongs to. Either attribute
works:
- `data-company-id` — your workspace id
- `data-widget-id` — a Support Hub widget id, which the server resolves back to the
workspace
The second exists so you can reuse the id you already have in a Support Hub tag
rather than finding another one. **The same value in the two different script
tags does two entirely different things**, which is the single easiest mistake
to make here.
Provide neither and the script logs an error naming both attributes, and stops.
## What the menu contains
Four items are configured by default:
| Item | Action |
| --- | --- |
| Find answers | Opens a knowledge base search overlay |
| Contact us | Opens a URL you set |
| Suggest an improvement | Opens a feature-request form |
| Support page | Opens a URL you set |
Set the label, colour, corner and the items themselves under **Customer Support
→ Floating Launcher**. Each item does one of:
| Action | What it does |
| --- | --- |
| `kb_search` | Opens the knowledge base search overlay |
| `feedback` | Opens the feature-request form |
| `link` | Opens the item's `url` in a new tab. Nothing happens if the url is blank |
| `chat` | See [using both](#using-both) — this one has a caveat |
Two of the defaults are `link` items with an empty url, so they do nothing until
you fill them in.
Configuration is cached for a minute at the edge, so a change can take up to
that long to reach a visitor already on your site.
## Identifying the submitter
You can pass who the visitor is:
```html
```
They are recorded on any feature request the visitor submits, and they create
CRM records — exactly as the Support Hub does with the same details.
## What identification creates
When the launcher loads with an email address:
- finds the matching contact, or creates one with a `source` of `support_launcher`
- finds or creates an **account** when a company was given, and links the two
- saves the suggestion as a **feature request** pointing at that contact
The address is matched case-insensitively, so `Ada@Example.com` and
`ada@example.com` are one person rather than two contacts.
**Note.**
This happens **on page load**, the moment the launcher knows who the visitor
is — exactly as the Support Hub does. A visitor your site identifies becomes a
contact whether or not they ever open the launcher, so every identified
visitor is in your CRM.
Submitting a suggestion resolves the same person again, which by then is a
lookup rather than a new record, and is what attaches the suggestion to their
contact. Without an email address the suggestion is still saved — it simply has
no contact attached.
## Using both
Nothing stops you running the launcher and the Support Hub on the same page,
and it is a reasonable setup: the launcher for self-service, the widget for
conversations.
They are independent, though, and one gap follows from that. A launcher item
with the `chat` action **cannot open the Support Hub**. It falls back to opening
the item's `url` in a new tab, and does nothing at all when that is blank. To
send someone from the launcher into a conversation, point a `link` item at a
page where the Support Hub is embedded.
## Appearance
| Setting | Default |
| --- | --- |
| Label | `Support` |
| Colour | `#1f2937` |
| Position | `bottom-right` |
| Theme | `auto` |
`data-theme` on the script tag takes `auto`, `light` or `dark` and overrides
the workspace theme, the same way it does for the Support Hub.
## When the launcher does not appear
- **Neither id attribute is set.** The script logs an error naming both and
stops.
- **The workspace id is wrong.** The configuration request returns 404 and
nothing renders.
Both fail quietly on the page and report themselves in the browser console.
---
API reference (one page per endpoint): https://app.clientsphere.io/docs/build/api