Control a Test number's phone

Every Test number has a simulated phone that acts as its main device. The Polymorfa API and Inspector connect to it as linked devices, the same way they connect to a real phone. Use the phone controls to check which devices are linked, send a message as the phone, or unlink a device as a person would from Linked devices on their phone. Phone controls work only for Test numbers (testMode: true). A request for any other number returns 400 Bad Request.

Before you start

Your team has Test numbers access. See What is Sandbox?.
You have a project key, or a team key, with the sandbox:read scope to read the phone and sandbox:write to send or unlink. Client tokens can’t use phone controls.
Sending and unlinking need the Test number to be running. Start it first if the phone is offline.

In the Console

Open the project’s Numbers page. Test numbers are listed under Test slots. Choose Phone controls beside a Test number to see its linked devices, unlink one, or send a message from the phone to another Test number in the project.

Read the phone

curl "https://api.polymorfa.com/messaging/testing/$PROJECT_ID/numbers/my-test-number/phone" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

{
  "session": "my-test-number",
  "phone": "+15550100001",
  "online": true,
  "devices": [{ "deviceId": 33 }, { "deviceId": 74 }]
}

online is true while the simulated phone is running. devices lists the linked devices by device ID.

Send a message from the phone

The phone sends a text to another running Test number in the same project. The message travels the simulated WhatsApp network, so the sender’s linked devices receive the sent copy and the recipient receives an ordinary incoming message.

curl -X POST "https://api.polymorfa.com/messaging/testing/$PROJECT_ID/numbers/my-test-number/phone/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15550100002", "text": "hello from the phone" }'

The API returns 202 Accepted with the WhatsApp message ID when the phone reports one:

{ "session": "my-test-number", "to": "+15550100002", "messageId": "3EB0A1B2C3D4E5F6" }

Phone messages and test events share a limit of 30 requests per minute per project. Above it, the API returns 429 Too Many Requests with a Retry-After header.

Unlink a device

Unlinking logs the device out, as it would on a real phone. Device 0 is the phone itself and can’t be unlinked.

curl -X POST "https://api.polymorfa.com/messaging/testing/$PROJECT_ID/numbers/my-test-number/phone/devices/74/unlink" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

{ "session": "my-test-number", "deviceId": 74, "unlinked": true }

A device ID that is not linked returns 404 Not Found.

Errors

Status	Meaning
`400`	The session is not a Test number in the project, the phone is offline, or `to` is not another running Test number in the project.
`403`	Test numbers access is missing, the key lacks the scope, or a client token was used.
`404`	The project, or the device to unlink, was not found.
`429`	The project reached its Testing limit. Retry after the `Retry-After` interval.
`502`	The phone could not complete the request. Retry later.

See the API reference for Get a Test number’s phone, Send a message from a Test number’s phone and Unlink a companion.

Get started

Tools and clients

TypeScript SDK

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

Control a Test number's phone

Before you start

In the Console

Read the phone

Send a message from the phone

Unlink a device

Errors

​Before you start

​In the Console

​Read the phone

​Send a message from the phone

​Unlink a device

​Errors

Before you start

In the Console

Read the phone

Send a message from the phone

Unlink a device

Errors