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

Control a test number's phone

See linked devices, send a message as the phone and unlink a device from a test number.

View as Markdown

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 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. Each request names the test number in its path, and the Number decides the project. A real Number, or a test number outside your key's project, returns 404 resource_not_found.

Open phone controls#

Console

Open the project's Numbers page. Under Test numbers, choose Phone controls beside a connected test number, or open the test number and choose Phone controls in its header. The dialog shows whether the phone is online and lists its linked devices.

API

Read the phone. my-test-number is the test number's session value.

Shell
curl "https://api.polymorfa.com/messaging/my-test-number/phone" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
JSON
{
  "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: the sender's linked devices receive the sent copy and the recipient receives an ordinary incoming message.

Console

In the phone controls dialog, under Send from phone, choose a test number in To, enter a Message and select Send.

API

Shell
curl -X POST "https://api.polymorfa.com/messaging/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:

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

to is the phone number of another connected test number in the same project, in E.164 format. text is 1 to 4,096 characters.

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

Console

In the phone controls dialog, select Unlink beside the device.

API

Shell
curl -X POST "https://api.polymorfa.com/messaging/my-test-number/phone/devices/74/unlink" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
JSON
{ "session": "my-test-number", "deviceId": 74, "unlinked": true }

A device ID that is not linked returns 404.

Verify the result#

Read the phone again. After an unlink, the device is gone from devices. After a send, open the recipient in Inspector to see the message, or check your webhook for its message.received event.

Limits and errors#

Phone messages and test events share a limit of 30 requests per minute per project. Above it, the API returns 429 with a Retry-After header, and the Console shows Testing limit reached.

StatusMeaning
400The phone is offline, or to is not another connected test number in the same project.
403Test numbers access is missing, the key lacks the scope, or a client token was used.
404resource_not_found when the Number is a real Number or is outside your key's project. A plain 404 when the device to unlink isn't linked.
429The project reached the shared testing limit. Retry after the Retry-After interval.
502The phone could not complete the request. Retry later.

See also#