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

Test numbers

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

View as Markdown

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 #

LimitValue
Test numbers per project5, or 50 when your team has the Simulation add-on
Credits per test numberNone. Test numbers create no reservation, charge or usage record.
Test events and phone actions30 per minute per project, shared
RecipientsActive, 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 valueAmount
Throughput5 messages per second per Number
Included data1 GB per Number
Inbound and outbound calls5 each per month
Serverless calls1,000 per month
CampaignsNot 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
curl "https://api.polymorfa.com/platform/sessions?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 #

StageWhat happens
ReservedCreating a test QuickLink reserves the Number. No simulated account exists yet.
ConnectedCompleting the simulated setup creates the account and links the API-controlled device. The device stays linked across service and app restarts.
StoppedStopping pauses the API-controlled device and keeps the Number, its settings and any Inspector device.
RemovedRemoval 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.

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

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

See also#