# Test numbers

> Manage test numbers and review their limits, lifecycle and supported features.

A test number is a simulated WhatsApp Number that belongs to one project. It
has a generated phone number, a simulated phone and a linked device that the
API controls. This page covers how many you can have, how to find, stop, start
and remove them, and which features they support.

Test numbers require access; see [Testing](https://docs.polymorfa.com/testing). To create one, follow the
[quickstart](https://docs.polymorfa.com/testing/quickstart).

## Limits

| Limit | Value |
| --- | --- |
| Test numbers per project | 5, or 50 when your team has the Simulation add-on |
| Credits per test number | None. Test numbers create no reservation, charge or usage record. |
| Test events and phone actions | 30 per minute per project, shared |
| Recipients | Active, connected test numbers in the same project |

The project limit counts test numbers that are not removed. It is separate
from the limit on real Numbers, and it applies on Free and Pay-As-You-Go teams.
The Simulation add-on is a separate purchase; test numbers themselves use no
credits.

Throughput, included data and call allowances follow the Number tier, as for a
real Number. On the Free tier these values are:

| Free tier value | Amount |
| --- | --- |
| Throughput | 5 messages per second per Number |
| Included data | 1 GB per Number |
| Inbound and outbound calls | 5 each per month |
| Serverless calls | 1,000 per month |
| Campaigns | Not included |

See [Free and Pay-As-You-Go](https://docs.polymorfa.com/billing#free-and-pay-as-you-go) for the other
tiers.

## Find your test numbers

**Console:**

Open the project's **Numbers** page. Test numbers are listed under **Test
slots**, separately from real Numbers.

**API:**

List the project's Numbers with a team key or project token that has
`sessions:read`:

```bash cURL
curl "https://api.polymorfa.com/platform/sessions?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const numbers = await platform.sessions.list({ projectId: "<project-id>" });
const testNumbers = numbers.data.data.filter(number => number.testMode);
```

Test numbers have `testMode: true`. Use the returned identifier and phone
number rather than assuming a count or a number format.

*TypeScript:*

Use the returned identifier and phone number rather than assuming a count or a
number format.

## Lifecycle

| Stage | What happens |
| --- | --- |
| Reserved | Creating a test QuickLink reserves the Number. No simulated account exists yet. |
| Connected | Completing the simulated setup creates the account and links the API-controlled device. The device stays linked across service and app restarts. |
| Stopped | Stopping pauses the API-controlled device and keeps the Number, its settings and any Inspector device. |
| Removed | Removal closes any open Inspector session, unlinks every device and clears the simulated account. Removal is permanent. |

Stop, start or remove a test number with a team key or project token that has
`sessions:manage`. The project's [Test key](https://docs.polymorfa.com/testing/test-key) can also stop,
start and restart its test numbers, but not remove them. `$SESSION_ID` is the
Number's identifier from the list.

```bash cURL
# Stop
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Start again
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/start" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Remove
curl -X DELETE "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
// Stop
await platform.sessions.stop("<number-id>", { projectId: "<project-id>" });

// Start again
await platform.sessions.start("<number-id>", { projectId: "<project-id>" });

// Remove
await platform.sessions.delete("<number-id>");
```

Start, stop and restart responses acknowledge the request. Check the Number's
status before treating the action as complete. Repeating a pending start or
restart keeps the same attempt. If cleanup remains unconfirmed, resolve it
before starting a new attempt.

If a removal can't close the Number, the request fails and leaves the Number in
place so you can retry. In the Console, remove test numbers from **Test numbers**
on the **Numbers** page.

## Add simulated history

A history fixture gives a new test number earlier chats to retrieve. Upload
the fixture first, then reference it when you create the test number. A
fixture belongs to the project, not to a Number, because you upload it before
the test number exists. You can reuse it for several test numbers.

**Console:**

In the new test number form, under **Configuration**, select **Upload test
history** and choose a JSON file with up to 100 messages.

**API:**

Upload the messages with a project token or team key that has
`sandbox:write`. The Test key can't upload fixtures.

```bash
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_ID/test-history-fixtures" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "id": "m1", "senderPhone": "+15550100002", "text": "Is my order on its way?", "timestamp": 1760000000, "fromMe": false },
      { "id": "m2", "senderPhone": "+15550100001", "text": "Yes, it ships today.", "timestamp": 1760000060, "fromMe": true }
    ]
  }'
```

The API returns `201 Created` with a `fixtureId`. Pass it as
`configuration.testing.configuration.historyFixtureId` when you create the test
QuickLink.

A fixture holds at most 100 messages in a request smaller than 512 KiB. Each
message needs a unique `id`, a `senderPhone` that belongs to a test number in
the project, `text` of up to 4,096 characters, a Unix `timestamp` in seconds
that is not in the future, and `fromMe`. Uploading a fixture publishes no
message events.

## What test numbers can do

A test number behaves like a real linked-device Number. Messages,
media, message edits and reactions, receipts, contacts, groups, channels,
presence, privacy, profiles, labels and business catalogs work through the
same API methods and produce the same events and webhooks.

The API-controlled device and Inspector share one simulated account, so a
change in one appears in the other. A message sent while the recipient's
Inspector is closed is delivered when it reconnects. Removing the recipient
cancels its pending messages.

## What test numbers can't do

- **Reach anyone outside the project.** Recipients must be test numbers in the
  same project.
- **Use real-phone or Meta Cloud API setup.** A test QuickLink can't prefill a
  phone number, offer Meta Cloud API setup, or turn on observation. Official
  API methods on a test number are simulated and never reach Meta.
- **Keep Hosted Message Storage history.** Test numbers have no retained
  history.
- **Send campaigns without a campaign tier.** Campaign senders need a Number tier that
  includes campaigns; Free and Standard don't. A campaign can select test
  numbers as senders and can run drip sequences on them, but a campaign uses
  one kind of sender: real Numbers, Meta Cloud API Numbers or test numbers.
- **Send weighted message variations.** A campaign with weighted message
  variations sends only from real linked-device Numbers.
- **Count toward billing, Usage or BanSafe scoring.** See
  [How test numbers differ from real Numbers](https://docs.polymorfa.com/testing#differences).

## See also

- [Simulated setup scenarios](https://docs.polymorfa.com/testing#simulated-setup-scenarios)
- [Phone controls](https://docs.polymorfa.com/testing/phone-controls)
- [Open test numbers in Inspector](https://docs.polymorfa.com/testing/inspector/devices)
- [List Numbers](https://docs.polymorfa.com/api/numbers/list-sessions)
- [Create testing history fixture](https://docs.polymorfa.com/api/testing/create-testing-history-fixture)
