Skip to content
Shortcut: /, ⌘K or Ctrl+K

How Polymorfa works

Learn how teams, projects, Numbers, credentials, regions and events fit together.

View as Markdown

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.

Text
Team ─┬─ members, billing, team keys
      └─ Project ─┬─ Numbers (real and test)
                  ├─ project tokens
                  ├─ webhook endpoints
                  └─ campaigns, templates, Customers, settings

Teams 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:

RoleCan
OwnerManage the team and perform owner-restricted actions
AdminManage members and the project resources allowed to admins
MemberUse 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.

KindWhat it is
Real numberA WhatsApp account on a phone, connected as a linked device or through Meta's Cloud API
Test numberA 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:

StatusMeaning
CONNECTINGThe connection is being established.
CONNECTEDThe Number is ready to send and receive.
DISCONNECTEDThe 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.

CredentialPrefixWhere to use itReach
Team keypmfa_Your serversSelected permissions across the team and all its projects
Project tokenpmfa_pt_Your serversSelected permissions inside one project
Client tokenpmfa_ct_Browsers and mobile appsOne 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.

APIPath prefixUse it to
Messaging/messagingSend messages, read conversations and control Numbers
Meta-compatible (Graph)/graph/whatsapp/{version}Reuse code written for Meta's Cloud API
Platform/platformManage 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.

See also#