Key concepts

Eight nouns cover most of what you will touch in the API: workspace, site, conversation, message, visitor, agent, department, and engagement. Once you understand how they relate, the rest of the surface area follows naturally.

If you want the one-paragraph version: a workspace contains sites where visitors interact with the widget. Every interaction becomes a conversation (chat, ticket, or call) handled by agents, optionally grouped into departments. AI usage is metered as engagements.

Workspace

The workspace is the top-level container. One business equals one workspace. Every API call is scoped to a workspace via the bearer token, and we never leak data between workspaces. Workspace-level resources include billing, the team roster, departments, saved replies, the knowledge base, the suppression list, and AI configuration.

You receive a workspace on signup. Most customers run a single workspace; agencies and multi-brand operators may run several and switch between them in the dashboard. Workspace IDs appear in the public widget snippet, but the dashboard never exposes them in any privileged context.

See the Workspaces API for read and update endpoints. The full workspace concept is documented at Concept: workspace.

Site

A site is a domain (or subdomain) where the widget is installed. A workspace can have many sites, and each site holds the per-property configuration: widget appearance, primary colour, welcome message, business-hours rules, and AI engagement settings.

Most teams have one site and never think about this distinction. Agencies, marketplaces, and multi-brand businesses use sites to ship a tailored widget experience per property while still routing inbound to a single team. See the Sites API for the resource shape.

Conversation

The conversation is the universal unit of customer contact. It has a channel field that says whether this is a chat, an email ticket, or a phone call. The unified inbox lists all three side by side, in one queue, with one set of agent actions (assign, transfer, close, tag, note). This collapse is the central product thesis.

Every conversation has a status, an optional assignee, an optional department, a visitor, and an ordered message timeline. Status moves through a small state machine (open, pending, solved, spam) with strict allowed transitions, enforced server-side. See Conversations API and Concept: unified inbox.

Message

A message belongs to a conversation. Its kind says who sent it: visitor, agent, system (status changes and bot announcements), or internal_note (private agent-only commentary).

Messages carry a body (plain text and sanitized HTML), attachments, a delivery status (sent, delivered, bounced, complained), and a seen timestamp. Email tickets and chats share this shape so agents do not learn a different model per channel. See Messages API.

Visitor

The visitor is the customer or end-user. Visitors live at the workspace level, not at the conversation level, so the same person can have many conversations across channels and you still see one record. The widget creates an anonymous visitor on first load; calling Message.identify() upgrades that record with email, name, an external user ID, and any custom attributes you want indexed.

For production use, sign the identify payload server-side with HMAC so a hostile browser cannot impersonate one of your customers. See Identifying visitors and the Visitors API.

Agent

An agent is a team member who handles conversations. Each agent has a role (admin, supervisor, or agent) and a channels[] array that controls which channels they see in the inbox. Admins can do everything. Supervisors see their own departments plus all reports for those departments. Agents see only what is assigned to them or to a department they belong to.

Agents also have a status (available, away, offline) that drives routing and the take-next button. See the Agents API.

Department

A department is a routing group. Conversations can be addressed to a department (Sales, Support, Billing) rather than a specific agent. Agents belong to one or more departments; round-robin or first-claim routing distributes the queue among them.

In the database the table is called groups; the UI and the docs use the word "department". They are the same thing. See the Departments API and Department vs team.

Engagement

An engagement is one AI interaction across any channel. Used purely for billing transparency. Examples of a single engagement: a chat where the AI drafted at least one reply, a Smart Hold session that engaged a caller, an AI Receptionist call, an agent-assist suggestion the agent accepted.

The Starter plan includes 100 engagements per month. Overage is $0.10 per engagement, billed at end of cycle. The /ai-engagements/summary endpoint returns the month-to-date count so you can build a meter into your own dashboards. See the AI engagements API.

How they fit together

A workspace owns many sites, many agents, many departments, many visitors, and many conversations. Every conversation belongs to exactly one workspace, one visitor, and (optionally) one assigned agent and one department. Messages belong to conversations. Engagements reference the conversation and the AI feature that fired.

This means almost every API endpoint takes either no extra scope (the auth token implies the workspace) or a single resource ID. There is no nested CRUD like /workspaces/:id/sites/:id/conversations. The auth token does that work.