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. To create one, follow the 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 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:
curl "https://api.polymorfa.com/platform/sessions?projectId=$PROJECT_ID" \
-H "Authorization: Bearer $POLYMORFA_KEY"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 can also stop, start and restart its test numbers, but not remove them. $SESSION_ID is the Number's identifier from the list.
# 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"// 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.
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.