# 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.

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

| 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](https://docs.polymorfa.com/teams#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
`/messaging/{session}/messages/send`. 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](https://docs.polymorfa.com/numbers/quicklink) and [Test numbers](https://docs.polymorfa.com/testing/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 `POST /platform/client-tokens`. A client token can't mint
another credential. See [API keys](https://docs.polymorfa.com/development/api-keys) and
[Client tokens](https://docs.polymorfa.com/development/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](https://docs.polymorfa.com/api/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](https://docs.polymorfa.com/api/versioning) and the
[API reference](https://docs.polymorfa.com/api). 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](https://docs.polymorfa.com/development/webhooks).
- **Event streams** deliver the same events over one long-lived HTTP
  connection. Event streams require access. See
  [Event streams](https://docs.polymorfa.com/development/event-streams).
- **Event history** keeps a bounded record you can list and replay. See
  [Events](https://docs.polymorfa.com/development/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](https://docs.polymorfa.com/development/security#hosting-and-messaging-regions).

## See also

- **[Send your first message](https://docs.polymorfa.com/get-started/quickstart)**
Connect a test number, send a message and receive its events.

- **[Glossary](https://docs.polymorfa.com/get-started/glossary)**
Look up the terms these docs use.

- **[API reference](https://docs.polymorfa.com/api)**
Choose the API for each part of your integration.

- **[Teams and projects](https://docs.polymorfa.com/teams)**
Manage members, projects and billing modes.
