REST API v1
HTTPS endpoints for your Chatzyn workspace's contacts, conversations, messages and templates.
Base URL: https://chatzyn.com/api/v1
Everything here is scoped to one workspace by the key. There is no workspace parameter, and no way for a key to name a different workspace. Rate limit: 120 requests a minute per key.
Authentication
Authorization: Bearer czk_a1b2c3d4_<64 hex chars>- Keys are created in Settings → API & MCP and shown exactly once. Only a hash of the key is stored, so we cannot recover a lost key, only revoke it and issue another.
?api_key=is not accepted. Query strings end up in access logs, browser history andRefererheaders.- Revocation is immediate; there is no cache to wait out.
- Only keys made in Settings → API & MCP (
czk_…) work here. A token a connected app received through the consent screen (czo_…) is for the MCP endpoint only and gets403 forbidden("OAuth tokens are only valid at /api/mcp") on every v1 route.
Requires the api_access entitlement (Growth and Pro plans).
Scopes
Enforced server-side on every request, read from the key row — never from anything the caller sends. There is no "all scopes" value.
| Scope | Grants | Lowest key role | Used by |
|---|---|---|---|
contacts:read | Read contacts and their tags. | viewer | REST and MCP |
contacts:write | Create, update and delete contacts. | agent | REST only |
conversations:read | Read conversations and their message history. | viewer | REST and MCP |
messages:send | Send messages, including uploading the media they carry (all send guards still apply). | agent | REST and MCP |
templates:read | List approved message templates. | viewer | REST and MCP |
flows:read | Read flow definitions and their publish state. | viewer | MCP only |
flows:write | Create flows and save their draft graph. Does not publish. | admin | MCP only |
flows:publish | Publish a flow, making it live. | admin | MCP only |
conversations:assign | Assign or unassign conversations to workspace members. | agent | MCP only |
broadcasts:send | Preflight and launch WhatsApp broadcast campaigns (all send guards still apply). | admin | MCP only |
templates:write | Create WhatsApp message templates and submit them to Meta for review. | admin | MCP only |
store:read | Read store automation settings, abandoned-cart figures and recent store orders. | viewer | MCP only |
store:write | Switch store automations on or off and change their template (order and COD confirmation, review requests, cart recovery). | admin | MCP only |
templates:send | Send one-time passcodes to any WhatsApp number with an approved authentication template (all send guards still apply). | agent | REST only |
analytics:read | Read workspace analytics: conversation, message, lead and order figures, agent performance and campaign results. | admin | MCP only |
broadcasts:read | Read broadcast campaigns, their delivery figures and a sample of recipients. | admin | MCP only |
A request with a valid key but the wrong scope gets 403 insufficient_scope and lists what was required.
Roles
Every key has a role — viewer, agent or admin — chosen when it is made, and it is enforced here exactly as in the dashboard:
- A scope needs a role. A key whose role is below the one in the table gets
403 insufficient_role, even though it holds the scope. Settings refuses to make such a key in the first place. - Which chats a key sees follows its role. An admin key sees every conversation in the workspace. An agent or viewer key acts for the person who made it and sees only the conversations given to that person, on the numbers they may work — the inbox's own rule. Everything else answers
404, the same as an id that does not exist. This applies toGET /conversations,GET /conversations/{id}/messagesandPOST /messages. Need every chat? Use an admin key.
Keys made before roles existed run as agent.
When the person who made a key leaves the workspace, the key keeps its role. An admin key carries on as before. An agent or viewer key still acts for that person, and nobody can give chats to someone who has left: their open chats go back to Unassigned, so from then on the key lists only their old resolved chats and answers 404 for every live one. Contacts and templates are not affected. Replace such a key with an admin key before removing its maker.
Rate limits
120 requests / minute / key, fixed window. Every response carries:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 34 # seconds until the window rolls
X-Request-Id: <uuid>Over the limit → 429 rate_limited with Retry-After.
Separately, every call consumes one unit of the plan's api_calls_month entitlement. Exhausting it returns 402 payment_required — the per-minute limiter protects the platform, the monthly meter is the commercial limit.
Need more headroom for one integration? Issue it its own key: the limiter is per key, so a runaway script cannot starve your other integrations.
Errors
Every non-2xx response has this exact shape — parse one, parse them all. A 500 never leaks a stack trace or a database message.
{
"error": {
"code": "insufficient_scope",
"message": "This key is missing the \"messages:send\" scope.",
"details": { "required": "messages:send", "granted": "contacts:read" },
"requestId": "0f3c…"
}
}code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing, malformed, unknown or revoked key |
forbidden | 403 | Workspace suspended, or a czo_ connected-app token (MCP only) |
insufficient_scope | 403 | Key lacks the scope this endpoint needs |
insufficient_role | 403 | Key holds the scope, but its role may not use it |
invalid_request | 400 | Bad body, bad parameter, bad cursor |
not_found | 404 | No such row in this workspace |
conflict | 409 | Duplicate contact, closed window, disconnected channel |
rate_limited | 429 | Per-key limit exceeded |
payment_required | 402 | No active subscription / api_access off / monthly allowance used |
unavailable | 503 | Stored but not queued — safe to retry |
internal | 500 | Our fault. Quote requestId to support |
Timeouts. During a brief service interruption (a few seconds), a send (POST /messages, POST /messages/template) waits for it rather than failing, so it can take up to about 8 seconds, and about 16 in the worst case. Give these calls a client timeout of at least 20 seconds: a shorter one can give up on a request that still sends, and a retry then sends twice.
Pagination
Collections return:
{ "data": [ … ], "nextCursor": "MjAyNi0wOC0wNFQxMDoxMjozM1o…" }Pass it back as ?cursor=…. nextCursor: null means you have everything.
Cursors point at a position in a fixed order, not a page number, so new rows arriving while you page never make you skip or repeat one. ?limit= is clamped to 100.
Endpoints
GET /contacts — contacts:read
Query: limit, cursor, search (name/email/phone substring), phone (normalised before matching, so +91 98… and 9198… find the same person).
Soft-deleted and merged-away contacts are never returned.
{
"data": [{
"id": "…", "name": "Priya", "phone": "919876543210", "email": null,
"locale": "ml", "attributes": {}, "tags": ["vip"], "isBlocked": false,
"lastSeenAt": "2026-08-01T09:12:00.000Z",
"createdAt": "…", "updatedAt": "…"
}],
"nextCursor": null
}POST /contacts — contacts:write
{ "name": "Priya", "phone": "+91 98765 43210", "email": null,
"locale": "ml", "attributes": { "city": "Kochi" } }At least one of phone / email. Phone numbers are stored as bare digits, no + (what WhatsApp ingest writes) — send whatever format you have, we normalise. An existing contact on that number returns 409 conflict with its id in details.contactId rather than creating a duplicate.
201 with the created contact.
GET /contacts/{id} — contacts:read
PATCH /contacts/{id} — contacts:write
PATCH is a true patch: an absent key leaves the field alone, an explicit null clears it. Send {"name": null} to clear a name; send {} and you get 400.
DELETE /contacts/{id} — contacts:write, admin key
Deleting a contact is admin-only in the dashboard, so it needs an admin key here; an agent key gets 403 insufficient_role.
A soft delete: the contact disappears from the API and the dashboard, but conversations, messages and the audit trail survive. Hard erasure is a separate, deliberate GDPR job — not something a loop in an integration can trigger.
GET /conversations — conversations:read
Query: limit, cursor, status (open|resolved|snoozed), contactId.
An admin key lists every conversation; an agent or viewer key lists only the ones given to the person who made it (see Roles).
Ordered by createdAt descending, not by last activity, so rows do not jump between pages every time a customer replies.
windowExpiresAt is the important field — past it, free-form sending is refused and you need an approved template.
GET /conversations/{id}/messages — conversations:read
Newest first. Query: limit, cursor.
POST /media — messages:send
Put a file where a send can name it. The body is the raw file, not multipart and not base64:
POST /api/v1/media?purpose=voice_note
Authorization: Bearer czk_…
Content-Type: audio/ogg
Content-Length: 41233
x-file-name: note.ogg
<raw bytes>purpose is message (default) or voice_note. Returns 201:
{ "id": "a17d…", "kind": "audio", "mimeType": "audio/ogg", "sizeBytes": 41233,
"fileName": "note.ogg", "durationSeconds": 7, "voiceNote": true }mimeType is what we sniffed from the bytes, not what you declared — upload WebM/Opus and it comes back audio/ogg, because it was remuxed. Caps are Meta's: image 5 MB, audio and video 16 MB, document 100 MB.
Voice-note intent is declared at UPLOAD time, and it has to be. audio/ogg is a container, not a codec: WhatsApp shows the push-to-talk bubble only when the send carries voice: true, and Meta rejects that flag on anything that is not Opus — a rejection that counts against your number's quality rating. ?purpose=voice_note is the only path that proves Opus, by remuxing WebM/Opus, re-encoding MP4/AAC, or asserting the codec on an Ogg you supply. Send Ogg/Opus and it always works.
image/webp is refused. WhatsApp treats WebP as a sticker, a MIME type alone cannot say which you meant, and silently turning a customer's photo into a sticker reads as a bug. Send JPEG or PNG.
There is no DELETE. API-uploaded files appear on Settings → Storage with a blank uploader and can be removed there. Nothing sweeps files you upload and never send, and they count against the workspace's storage.
POST /messages — messages:send
Exactly one of text or media:
{ "conversationId": "…", "text": "Your order has shipped." }{ "conversationId": "…", "media": { "id": "a17d…" } }media.caption (≤ 1024 chars, refused on audio and stickers), media.filename (documents only) and media.voice are optional. media.voice defaults to the asset's own voiceNote; setting it true on a file that was not uploaded with ?purpose=voice_note is a 400, never a silent upgrade. Setting it false on a recording sends it as an ordinary audio file.
There is no media.link or media.url, and there will not be one. A URL we never fetched skips every check this pipeline exists to run — the type sniffer, the allowlist, the size caps, the polyglot check — Meta then fetches it under limits we cannot pre-check, and a failure comes back as an opaque error against your number rather than as a local 400. It also leaves the message with no attachment in your own inbox.
A media send costs two API calls: the upload and the send. Both count against api_calls_month and the per-minute rate limit.
body on the returned message is a preview ([Voice note], [Image] my caption), not the caption you sent.
Which conversations and files a key may use follows its role (see Roles). An admin key may send into any conversation in its workspace and attach any file in it. An agent key may send only into the conversations given to the person who made it, and attach only files that person could see, or files this same key uploaded with POST /media.
Returns 202 Accepted with the message row at status: "queued".
202 is not a delivery promise. The send goes through the same pipeline an agent's reply does: it is queued, then every guard is checked again (24-hour window, opt-out, blocked contact, channel health) before anything reaches Meta. Poll GET /conversations/{id}/messages or subscribe to the message.status outbound webhook for the outcome.
Fast-fail 409s you can get before queueing: closed customer-service window, disconnected channel, contact with no WhatsApp identity.
Free-form text and media here. The only template send in v1 is a one-time passcode through POST /messages/template below; marketing and utility template sends need per-template variable validation and a category, and shipping half of that publicly is how unreviewed marketing goes out on a client's number. Use the dashboard, or broadcasts, for those. Instagram and Messenger attachments are not supported: both Send APIs need a public file URL, and media uploaded here is kept private.
Sending the same media.id twice sends the file twice — there is no request-level idempotency anywhere in v1 yet.
POST /messages/template — templates:send
Send a login or verification code to any WhatsApp number — no existing conversation needed — with an approved AUTHENTICATION template.
{ "to": "+919876543210", "channelId": "…", "templateName": "login_code",
"language": "en", "code": "482913" }to— E.164 with the+and country code. We never guess a country code: guessing one sends a stranger somebody else's code.channelId— the WhatsApp number that sends it. Required when the workspace has more than one connected number; optional when it has exactly one. A non-admin key may use only numbers its maker may work.templateName+language— an approved template in that number's WhatsApp business account (as listed byGET /templates).code— 4 to 8 digits, as a string. It fills the body's{{1}}and the copy-code / one-tap / zero-tap button.
Authentication templates only. A marketing or utility template is refused with 400 invalid_request, whatever its content. That is deliberate, not a gap waiting to be filled: those categories need consent and variable rules a public endpoint cannot check for you.
The number is found or added as a contact and the code lands in its WhatsApp thread in the inbox, the same way an inbound message or a broadcast would. The thread stays Resolved and nobody is asked to reply. The code itself is masked (••••••) in the inbox, in previews and in GET /conversations/{id}/messages, so staff cannot read users' codes.
Returns 202 Accepted:
{ "messageId": "…", "conversationId": "…", "status": "queued" }As with POST /messages, 202 is not delivery. The send is still refused for a blocked or deleted contact, a disconnected number, a template Meta has paused, and an empty prepaid wallet (insufficient_balance). Authentication templates may be sent outside the 24-hour window, so there is no window check. Watch the message.status webhook for the outcome: errorCode 131026 means the number is not on WhatsApp (or cannot receive the message), so fall back to SMS.
Limit per number: 5 codes per number per WhatsApp channel per hour, on top of the per-key limit. The sixth gets 429 rate_limited with Retry-After (seconds until the oldest of the five is an hour old). This is what stops a leaked key from flooding a stranger's phone.
| Error | When |
|---|---|
400 invalid_request | Bad to / code, missing templateName/language, several numbers and no channelId, a non-authentication template, a template shape we cannot fill (a header, a non-OTP button, no {{1}}) |
404 not_found | No such connected channel, or no template with that name and language on that number |
409 conflict | No connected WhatsApp number, number disconnected or not linked to a business account, template not approved |
429 rate_limited | Per-key limit, or 5 codes to this number in the last hour |
402 payment_required | Subscription or trial over |
GET /templates — templates:read
Approved templates only — a draft, rejected or Meta-paused template is not sendable, and listing it would invite you to build against a name that will be refused. bodyVariableCount tells you how many {{n}} placeholders the body has.
GET /me — contacts:read
Which workspace this key is bound to, what it may do, and the rate limit. Use it as a health check. If the workspace here is not the one you expect, you are holding the wrong key.
GET /wallet — messages:send
The prepaid message wallet, when the workspace's plan uses one. Each WhatsApp message's price is set aside when it is sent and only charged once WhatsApp reports it delivered and billable; a failed or unbilled message costs nothing. When the balance cannot cover a message, the send fails with error_code: "insufficient_balance" (visible on the message and in its message.status webhook).
{
"data": {
"enabled": true,
"currency": "INR",
"balance": "1234.5600",
"balanceCentipaise": 12345600,
"pricePerMessage": { "marketing": "0.1000", "utility": "0.0500", "authentication": "0.0500", "service": null }
}
}Amounts are rupees as decimal strings (4 places) and 1/100 paise as integers; null means that message type is free. enabled: false means the plan does not charge per message.
Outbound webhooks
The push half of the integration story is configured in Settings → Webhooks. Each endpoint has its own secret; deliveries are HMAC-signed and timestamped:
X-Chatzyn-Timestamp: 1785913200 # unix seconds
X-Chatzyn-Signature: sha256=<hex> # HMAC-SHA256 of "<timestamp>.<raw body>"
X-Chatzyn-Event: message.status
X-Chatzyn-Delivery: <uuid>Verify by recomputing the HMAC over "<timestamp>.<raw body>" — the raw bytes, before any JSON parse — and comparing in constant time. Reject anything with a timestamp more than five minutes old; that is what stops a captured delivery being replayed at you later.
message.status payload:
{ "messageId": "…", "conversationId": "…", "channelId": "…", "channel": "whatsapp",
"status": "failed", "errorCode": "131026", "errorTitle": "Message undeliverable",
"at": "2026-11-04T09:12:00.000Z" }status is delivered, read or failed as WhatsApp reports them. errorCode and errorTitle appear only on failed. For a failure WhatsApp reports, they are Meta's error code and title. A send refused before it reached Meta (blocked contact, insufficient_balance, paused template) also fires one failed event, with our code (contact_blocked, insufficient_balance, …) and the reason text as errorTitle.
Failed deliveries retry with exponential backoff and are marked dead after the configured attempt ceiling. Every attempt is visible in the dashboard.
Not in v1 (deliberately)
- Marketing and utility template sends (authentication/OTP is the one template send in v1), broadcast triggering, flow triggering, leads/deals CRUD. None are half-shipped here.
- Reading media bytes back.
ApiMediacarries no URL: a presigned link is a bearer capability with a 300-second life, so media stays private. - An
Idempotency-Keyheader. Worth doing across all of v1 at once. - Bulk endpoints. Loop the single-resource ones — the rate limiter is sized for it.
- Anything that crosses a workspace boundary. There is no such endpoint and there will not be one.