This page is a map, not the territory. It tells you what the API can do and how a request is shaped; the full reference — every field, every example — lives at /docs and is always generated from the running app, so it cannot drift out of date.
Base URL and authentication #
Every endpoint sits under /api/v1 and is authenticated with the two headers from an API key. There is no login and no cookie:
x-client-id: client_xxxxxxxxxxxxxxxxxxxxxxxx
x-client-secret: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/jsonThe number a call sends from is decided by the key, not by the request body: a key bound to one WhatsApp account always uses that account, and an unbound key falls back to your default one.
The endpoints #
| Field | What it does |
|---|---|
| POST /api/v1/messages | The main send. type is text, media, interactive or template, and the recipient is one of phone_number, contact_id or conversation_id. An unknown number creates the contact and the conversation for you. Needs messages.send. |
| POST /api/v1/messages/template | A friendlier shape for template sends — to, template_name, language and components — running through the same pipeline as the endpoint above. Needs messages.send. |
| GET /api/v1/templates | Lists your templates with their language, category, approval status and any rejection reason. Needs templates.read. |
| POST /api/v1/templates | Creates a template and submits it to Meta for review. It comes back as a draft; approval is Meta's decision, not ours. Needs templates.write. |
| GET or POST /api/v1/conversations/history | Message history for a phone number, with limit, offset and order, plus a pagination block telling you whether more remains. Needs conversations.read. |
| POST /api/v1/media | Uploads a base64 payload with its content_type and returns a public URL you can pass straight back as media_url on a send. Needs media.write. |
Behaviour worth knowing before you build #
A template send is checked against your local template record first: if the template is known and not approved, the call is refused before it reaches Meta. Templates you have never synced are passed through and Meta decides. Read Message templates for what approval involves.
A free-form send over the API counts as a human answering that customer, so it pauses the AI agent on that conversation exactly as a reply typed in the inbox does. Template sends are the exception — they are notification blasts, so they leave the agent running.
The reference is also machine-readable #
The reference is public: no key is needed to read it, and it is served from the same Markdown source in two shapes. Point a browser at /docs for the rendered page, or fetch /docs.md for the raw Markdown. Sending Accept: text/markdown to the HTML route, or adding ?format=md, returns the same source.
That matters when the thing reading the docs is not a person. A build script, or a coding agent writing your integration, can pull the current endpoint list as plain text instead of scraping HTML — and it always reflects your own base URL and the live webhook event list.