Teams and projects
A team owns members, billing, team keys, projects, and team-level audit history. Current member roles are Owner, Admin, and Member. A project groups messaging resources such as sessions, project tokens, webhooks, templates, campaigns, and integration settings. Project tokens are bound to one project, so they cannot authorize access to another project’s resources.Sessions
A session represents one connected number. Each session has a stable identifier used in Messaging API paths such as/messaging/{session}/messages/send.
The public Messaging API types use three connection states:
New Numbers receive opaque decimal string IDs, regardless of how they were
created. Keep IDs as strings; do not convert them to JavaScript numbers.
Use
testMode to distinguish Test Numbers. Test Numbers are created in a
development project and do not start a real WhatsApp connection.
Credentials
Public
/platform/* Platform API operations accept an team key or verified
dashboard bearer. They reject project tokens. Messaging API, MCP, and
bridge operations accept only the credential kinds stated in their generated
reference.
Every service credential is a bearer secret. Keep team keys and project
tokens on trusted servers, request the narrowest scopes needed, and revoke a
credential when it may have been exposed. See Authentication
for the current scope names and audience rules.
Messages and webhooks
Messaging endpoints use typed request and response bodies for text, media, location, contact, poll, reaction, and other supported operations. Use the generated Messaging API reference for the exact fields and formats. Webhooks deliver events to your HTTPS endpoint. Native deliveries useX-Webhook-Signature; Meta-compatible deliveries use
X-Hub-Signature-256. Verify the signature against the raw request body before
parsing it. The Webhooks guide lists the current event names,
formats, and retry settings.
Versioning
Messaging API requests can pin the current date version:vNN.0 version. See Versioning for
the current defaults and response headers.
Sandbox
Sandbox provides testing-number workflows for development projects. Free testing numbers have a 5 messages-per-second limit, 1 GB of included storage, 5 inbound and 5 outbound calls a month, and 1,000 serverless executions a month. They do not include campaigns. Sandbox pool, claim, device, and message operations have their own documented routes; do not assume every production operation has a simulated equivalent.Where to go next
Quickstart
Make your first authenticated request.
API overview
Choose the correct API contract.
Authentication
Match credentials and scopes to routes.
Sandbox
Test with development-project numbers.