> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Control a Test number's phone

> See linked devices, send a message as the phone, and unlink a companion from a Test number.

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?](/sandbox/introduction).
* 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

```bash theme={null}
curl "https://api.polymorfa.com/messaging/testing/$PROJECT_ID/numbers/my-test-number/phone" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```json theme={null}
{
  "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.

```bash theme={null}
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:

```json theme={null}
{ "session": "my-test-number", "to": "+15550100002", "messageId": "3EB0A1B2C3D4E5F6" }
```

Phone messages and [test events](/sandbox/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.

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

```json theme={null}
{ "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](/api-reference/messaging/testing/get-testing-phone),
[Send a message from a Test number's phone](/api-reference/messaging/testing/send-testing-phone-message)
and [Unlink a companion](/api-reference/messaging/testing/unlink-testing-phone-device).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.