Core concepts
Understand organizations, connections, API keys, scopes, and MCP grants.
Organizations
An organization owns WhatsApp connections, API keys, MCP grants, webhooks, usage, and billing state. Personal use still happens through an organization with one member.
Connections
A connection is one WhatsApp account pairing. Each connection has its own pairing lifecycle. Organizations can create multiple connections when they need multiple WhatsApp accounts.
API keys can be scoped to one or more connection IDs. If a key allows only one connection, API requests can omit a connection selector. If a key allows multiple connections, send X-WhatsApp-Use-Connection-Id with the connection ID you want to use.
Message history
Sync and message APIs serve the most recent 30 days of messages for a connection. Older messages, including older history imported when an account first pairs, are not stored. If your product needs longer history, persist messages on your side as they arrive through sync or webhooks.
API keys
API keys are organization credentials. The full secret is shown once when the key is created. After that, the platform stores only a verifier and public metadata.
Use the Authorization header:
Authorization: Bearer pa_live_...Scopes
Scopes control which APIs a key or MCP grant can use.
| Scope | Allows |
|---|---|
whatsapp:read | Read status, pairing state, conversations, messages, contacts, and media. |
whatsapp:write | Start pairing, send messages, react, edit, delete, mark read, manage groups, and unlink. |
webhooks:manage | Create, update, delete, test, and inspect webhook endpoints and deliveries. |
MCP grants
MCP clients authenticate with OAuth. A grant binds the MCP client to a resource, scopes, organization, and connection. API keys are not accepted directly by MCP clients.