# Control a test number's phone

> See linked devices, send a message as the phone and unlink a device 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 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`.

> **Note**
>
> **Before you begin.** Your team needs [test numbers access](https://docs.polymorfa.com/testing). Reading
> the phone needs `sandbox:read`; sending and unlinking need `sandbox:write`. Use
> the project's Test key, or a project token or team key with those scopes.
> 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.

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

```bash
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:**

```bash
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.

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

**Console:**

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

**API:**

```bash
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](https://docs.polymorfa.com/testing/inspector/devices) to see the
message, or check your webhook for its `message.received` event.

## Limits and errors

Phone messages and [test events](https://docs.polymorfa.com/testing/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**.

| Status | Meaning |
| --- | --- |
| `400` | The phone is offline, or `to` is not another connected test number in the same project. |
| `403` | Test numbers access is missing, the key lacks the scope, or a client token was used. |
| `404` | `resource_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. |
| `429` | The project reached the shared testing limit. Retry after the `Retry-After` interval. |
| `502` | The phone could not complete the request. Retry later. |

## See also

- [Get testing phone](https://docs.polymorfa.com/api/testing/get-testing-phone)
- [Send testing phone message](https://docs.polymorfa.com/api/testing/send-testing-phone-message)
- [Unlink testing phone device](https://docs.polymorfa.com/api/testing/unlink-testing-phone-device)
- [Trigger test events](https://docs.polymorfa.com/testing/test-events)
