How Polymorfa works
Learn how teams, projects, Numbers, credentials, regions and events fit together.
Polymorfa connects WhatsApp accounts to your software. Each connected account is a Number. Your server sends messages and manages Numbers through the Polymorfa API, and Polymorfa sends what happens on each Number back to you as events. Teams and projects decide who can do what, and credentials carry that authority into each request.
Team ─┬─ members, billing, team keys
└─ Project ─┬─ Numbers (real and test)
├─ project tokens
├─ webhook endpoints
└─ campaigns, templates, Customers, settingsTeams and projects#
A team is your Polymorfa account. It owns members, billing, team keys, projects and the team audit history. Members have one of three roles:
| Role | Can |
|---|---|
| Owner | Manage the team and perform owner-restricted actions |
| Admin | Manage members and the project resources allowed to admins |
| Member | Use the resources the current membership and project policy allow |
Polymorfa checks the current membership on every request, so a role change applies to the next request.
A project is the boundary for your integration's resources: Numbers, project tokens, webhook endpoints, templates, campaigns, Customers and integration settings. A resource in one project is not visible through another project's credentials. Use separate projects to keep environments or products apart.
Every team starts on Free: one project, one real Number at no charge and test numbers. Pay-As-You-Go removes the project limit and charges credits for each real Number. See Free and Pay-As-You-Go teams.
Numbers#
A Number is one connected WhatsApp account. API paths and fields call it a session, so the Number ID is the {session} value in paths such as API Send message. Number IDs are opaque decimal strings. Keep them as strings; don't convert them to JavaScript numbers.
| Kind | What it is |
|---|---|
| Real number | A WhatsApp account on a phone, connected as a linked device or through Meta's Cloud API |
| Test number | A simulated account that messages only other test numbers in the same project. It never reaches WhatsApp. Test numbers have testMode: true and require access. |
You connect a Number with a QuickLink: a hosted page where the person holding the phone links their account, or where you set up a test number. See QuickLink and Test numbers.
The Messaging API reports three connection states:
| Status | Meaning |
|---|---|
CONNECTING | The connection is being established. |
CONNECTED | The Number is ready to send and receive. |
DISCONNECTED | The Number is not connected. Pair, start or inspect it before sending. |
The session.status, session.connected, session.logged_out and session.phone_offline events report changes as they happen.
Credentials#
Every API request carries a bearer credential. Choose the narrowest one that can do the job.
| Credential | Prefix | Where to use it | Reach |
|---|---|---|---|
| Team key | pmfa_ | Your servers | Selected permissions across the team and all its projects |
| Project token | pmfa_pt_ | Your servers | Selected permissions inside one project |
| Client token | pmfa_ct_ | Browsers and mobile apps | One Number or Customer, the actions you allow, for a short time |
Only a signed-in person creates team keys and project tokens, in the Console. The Console shows each one once. A team key or project token can mint client tokens through API Mint client token. A client token can't mint another credential. See API keys and Client tokens.
A permission, such as messages:write or webhooks:manage, allows one family of actions. A project token never reaches another project, even with every permission selected. See Authentication.
APIs#
All APIs use the host https://api.polymorfa.com.
| API | Path prefix | Use it to |
|---|---|---|
| Messaging | /messaging | Send messages, read conversations and control Numbers |
| Meta-compatible (Graph) | /graph/whatsapp/{version} | Reuse code written for Meta's Cloud API |
| Platform | /platform | Manage projects, Numbers, webhooks, events, Customers and billing |
Pin the Messaging and Platform contract with the Polymorfa-Version header. The current version is 2026-09-22. See Versioning and the API reference. The API reference covers all three APIs: choose the Polymorfa API or the Graph API in its sidebar picker.
Events#
An event records something that happened, such as message.received, message.ack or session.status. Each event belongs to a project or to the team. You can receive events three ways:
- Webhooks deliver each event to your HTTPS endpoint, signed with a secret, and retry failed deliveries. See Webhooks.
- Event streams deliver the same events over one long-lived HTTP connection. Event streams require access. See Event streams.
- Event history keeps a bounded record you can list and replay. See Events.
Deliveries can repeat and arrive out of order. Deduplicate with the event id.
Regions#
Your Console account, settings and secrets are hosted in the EU. Each Number has an assigned messaging region where its WhatsApp session runs and its messages are processed. See Hosting and messaging regions.