Skip to main content
Staging-verified; production rolling out. Tool names and arguments are stable — treat the MCP server URL as environment-specific until GA.
The Sapot Chat MCP server exposes 46 tools across 7 domains. Every tool is backed by a live REST endpoint and is unlocked by a capability scope carried on your agent key. A tool whose scope your key wasn’t granted is simply invisible to that key — this is default-deny by design, not an error. This section is the technical reference. Each domain has its own page listing every tool with its scope, arguments, and return shape.

​
Tools by scope

Scopes are additive and independent. A key with only conversations:read can read the inbox but cannot reply; a key with flows:manage but not flows:publish can attach inboxes but cannot take an agent live.

​
How to read a domain page

Every tool entry on the per-domain pages follows the same layout:
1

Scope

The exact capability scope the key must carry. If it’s missing, the call returns Access token is missing the required scope: <scope>.
2

Arguments

A table of argument names, types, and behavior — matched verbatim to the tool signature. Defaults are noted; the account id is never an argument (it’s fixed by the X-Sapot-Account-Id connection header).
3

Returns

The response shape the tool hands back, using the envelope conventions below.

​
Return-envelope conventions

The tools proxy Sapot Chat’s REST API, so responses follow its shapes. Three patterns cover almost everything: Notes that trip people up:
  • payload is the array of records; meta holds the counts and pagination. Read meta before assuming there’s a next page.
  • Some success responses are empty — deletes, set_conversation_priority, and an “unassign” all return {}. That’s success, not a silent failure.
  • search_knowledge is the odd one out: it returns {text_context, entries: […]} — the same retrieval the AI runtime uses.

​
Page sizes

Pagination is per-domain and fixed server-side: Paginated tools take a 1-based page argument; increment it and re-call to walk the pages.

​
Metering

Only allowed, successful (2xx) calls count against your plan’s per-billing-period action quota. A denied (401/403), not-found, or invalid (422) call consumes nothing. When the quota is exhausted, tools return 429 with Agent action quota exceeded for the current billing period; it resets at the next billing-period renewal.

​
Boundaries shape two domains

Two domains are deliberately narrowed to honor the locked product boundaries — read Safety & Boundaries before relying on them:
  • Flow agents are intent-level only. You list, inspect, attach inboxes, and publish — but the Designer graph (graph_data / graph_snapshots / designer_history) is stripped server-side, and there is no build-from-scratch, export, or import tool.
  • Campaigns are draft-only. A campaign created or edited via an agent key is forced into a non-sending draft state. An agent prepares the blast; a human sends it from the dashboard.

​
The domains

Conversations

Read, search, and filter conversations; reply, assign, resolve, prioritise, and label. (11 tools)

Contacts

Find, create, update, and label contacts; resolve numeric label ids. (7 tools)

Reports

KPI summaries, single-metric time series, leaderboards, and live counts. (5 tools)

AI Knowledge

Curate FAQs, products, and promos, plus the always-on business profile. (8 tools)

WhatsApp Templates

List, create, update, delete, and sync Meta message templates. (5 tools)

Flow Agents

Operate and publish flow agents at the intent level. (5 tools)

Campaigns

Preview audiences and prepare campaign drafts for a human to send. (5 tools)
Not connected yet? Start with the Quickstart at /ai-agents/quickstart, or read the scope model at /ai-agents/authentication.