Contact
API Reference
Overview
WhatSetter API 2026-10
Section titled “WhatSetter API 2026-10”The WhatSetter public API lets you connect your CRM and tools to your
WhatSetter workspace: push leads into lists, read leads and conversations
on WhatsApp, Instagram and Messenger, send messages (WhatsApp through the
anti-ban engine, Instagram and Messenger inside Meta’s 24-hour window),
manage campaigns, read and change the prompts and the knowledge your
agents run on, run your Instagram accounts (posts, automations, numbers),
and receive signed webhooks. An MCP server is also available for AI
agents at mcp.whatsetter.com. It uses the same API keys.
Authentication
Every request needs an API key, created from your WhatSetter dashboard (Settings → API) or by your account manager. Pass it as a Bearer token:
Authorization: Bearer ws_live_xxxxxxxxxxxxxxxxxxxx
A key belongs to one workspace (team) and carries scopes. Keep it secret. It is shown once at creation and can be revoked at any time.
Errors
All errors use one envelope:
{ "error": { "code": "validation_error", "message": "…" } }
| HTTP | code | meaning |
|---|---|---|
| 400 | validation_error | malformed URL encoding in the path (e.g. /leads/%ZZ) |
| 401 | missing_api_key / invalid_api_key | key absent, unknown or revoked |
| 403 | insufficient_scope | key lacks the required scope |
| 403 | not_in_plan | a Social workspace on lists, groups, links, webhooks or WhatsApp sending |
| 403 | instagram_not_enabled | Instagram is not enabled on the workspace (Instagram routes, Instagram leads) |
| 404 | not_found | resource doesn’t exist (or belongs to another workspace) |
| 422 | validation_error | bad parameter or body |
| 429 | rate_limited / quota_exceeded | slow down / a daily or per-workspace quota is reached |
| 500 | internal_error | our fault (or a feature not configured on this deployment), retry later |
| 502 | upstream_error / send_failed | a downstream engine (workflow, WhatsApp) refused or timed out |
| 503 | agent_disconnected | the campaign’s WhatsApp number is not available |
Endpoint-specific codes (lead_not_contacted, request_in_flight,
invalid_state, already_blocked, plan_limit_reached,
version_conflict, variant_required, variant_not_live,
draft_pending, messaging_window_closed, recipient_unreachable, instagram_reconnect_required,
facebook_page_required, facebook_reconnect_required,
facebook_permission_required, instagram_account_not_found,
invalid_media_url, post_already_started, post_already_published,
too_many_planned, no_reminder_recipient, automation_conflict,
instagram_publishing_unavailable, instagram_rate_limited,
instagram_unavailable) are listed on each operation. An error may carry
more fields next to code and message when they help you act
(window_closes_at, conflict).
Rate limits
Requests are limited per workspace (all keys combined), by plan:
| Plan | Requests / minute |
|---|---|
| Social | 30, no lists, groups, links, webhooks or WhatsApp sending (403 not_in_plan) |
| Free | 60 |
| Starter | 120 |
| Business | 300 |
| Scale | 1000 |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and
X-RateLimit-Reset. On 429 rate_limited, honor the Retry-After header.
(WhatsApp sending has its own separate daily anti-ban quota: see
POST /messages.)
Idempotency
POST /messages is retry-safe: pass an Idempotency-Key header (any unique
string ≤200 chars, e.g. a UUID per send intent). A key that already produced
a response replays it (with X-Idempotent-Replay: true) instead of sending
a second message (WhatsApp, Instagram or Messenger). A retry fired while the first is still processing
gets 409 request_in_flight. If a send times out (502), retrying with the
SAME key is safe (it will never double-deliver); retrying WITHOUT a key may.
Always use an Idempotency-Key when sending.
Pagination
List endpoints return pagination.has_more and pagination.next_cursor.
Pass cursor=<next_cursor> to fetch the next page. limit is 1–100
(default 25). An invalid or expired cursor (its row was deleted) answers
422 validation_error on every paginated endpoint.
Authentication
Section titled “Authentication”bearerAuth
Section titled “bearerAuth”Authorization: Bearer ws_live_… is the recommended form. The same
key is also accepted in an X-Api-Key: ws_live_… header (for tools
that cannot set Authorization).
A key carries scopes; each endpoint names the one it needs. A key
missing the scope answers 403 insufficient_scope.
| Scope | Grants |
|---|---|
leads:read |
read leads and their notes |
leads:write |
update leads (status, tags, owner, next action, outcome), add notes, handoff / resume |
conversations:read |
inbox + message transcripts |
lists:read / lists:write |
contact lists + imports |
campaigns:read / campaigns:write |
campaign directory + pause / resume |
messages:send |
send a message (WhatsApp, Instagram, Messenger), add an opt-in lead to a campaign |
bookings:read |
calls booked by the AI |
groups:read |
tracked WhatsApp groups |
webhooks:manage |
webhook subscriptions |
blocklist:manage |
read, add and remove blocked numbers / dial prefixes |
team:read |
list team members (id, name, role) to assign leads |
links:read |
read tracked links and their click stats |
prompts:read / prompts:write |
read an agent’s prompts and their versions / change or restore them (live at once) |
knowledge:read / knowledge:write |
read and search knowledge bases / add, correct and remove answers |
instagram:read / instagram:write |
the Instagram accounts, planned posts, insights, automations and numbers / plan, change and cancel posts, create, change and delete automations |
A key made with « Full access » before a scope existed does not carry
it (full access is the list of scopes at the time the key was made):
a key made before the Instagram endpoints were released has no
instagram:* scope. Create a new key to use the Instagram routes.
Security scheme type: http
Bearer format: ws_live_…