# Controlar o telefone de um número de teste

> Veja os dispositivos vinculados, envie uma mensagem como o telefone e desvincule um dispositivo de um número de teste.

Todo número de teste tem um telefone simulado que funciona como o dispositivo
principal dele. A API da Polymorfa e o Inspector se conectam a ele como
dispositivos vinculados, da mesma forma que se conectam a um telefone real. Use
os controles do telefone para conferir quais dispositivos estão vinculados,
enviar uma mensagem como o telefone ou desvincular um dispositivo, como uma
pessoa faria em **Aparelhos conectados** no próprio telefone.

Os controles do telefone funcionam apenas para números de teste. Cada
solicitação indica o número de teste no caminho, e o número define o projeto.
Um número real, ou um número de teste fora do projeto da sua chave, retorna
`404 resource_not_found`.

## Antes de começar

- A sua equipe tem acesso a números de teste. Consulte [O que é o Sandbox?](https://docs.polymorfa.com/pt-br/testing).
- Ler o telefone exige `sandbox:read`; enviar e desvincular exigem
  `sandbox:write`. Use a chave de teste do projeto, ou um token de projeto ou uma
  chave de equipe com esses escopos. Tokens de cliente não podem usar os
  controles do telefone.
- Enviar e desvincular exigem que o número de teste esteja em execução. Inicie-o
  primeiro se o telefone estiver offline.

## No Console

Abra a página **Números** do projeto. Os números de teste aparecem em **Números de
teste**. Escolha **Controles do telefone** ao lado de um número de teste conectado,
ou no cabeçalho do número de teste, para
ver os dispositivos vinculados dele, desvincular um deles ou enviar uma mensagem
do telefone para outro número de teste do projeto.

## Ler o telefone

`my-test-number` é o valor `session` do número de teste.

```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` é `true` enquanto o telefone simulado está em execução. `devices` lista
os dispositivos vinculados pelo ID do dispositivo.

## Enviar uma mensagem pelo telefone

O telefone envia um texto para outro número de teste em execução no mesmo
projeto. A mensagem passa pela rede simulada do WhatsApp, então os dispositivos
vinculados do remetente recebem a cópia enviada e o destinatário recebe uma
mensagem recebida comum.

```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" }'
```

A API retorna `202 Accepted` com o ID da mensagem no WhatsApp quando o telefone
informa um:

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

As mensagens do telefone e os [eventos de teste](https://docs.polymorfa.com/pt-br/testing/test-events)
compartilham um limite de 30 solicitações por minuto por projeto. Acima dele, a
API retorna `429 Too Many Requests` com um cabeçalho `Retry-After`.

## Desvincular um dispositivo

Desvincular desconecta o dispositivo, como aconteceria em um telefone real. O
dispositivo 0 é o próprio telefone e não pode ser desvinculado.

```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 }
```

Um ID de dispositivo que não está vinculado retorna `404 Not Found`.

## Erros

| Status | Significado |
| --- | --- |
| `400` | O telefone está offline ou `to` não é outro número de teste conectado no mesmo projeto. |
| `403` | Falta o acesso a números de teste, a chave não tem o escopo ou foi usado um token de cliente. |
| `404` | `resource_not_found` quando o número é um número real ou está fora do projeto da sua chave. Um `404` simples quando o dispositivo a desvincular não está vinculado. |
| `429` | O projeto atingiu o limite de testes. Tente novamente depois do intervalo de `Retry-After`. |
| `502` | O telefone não conseguiu concluir a solicitação. Tente novamente mais tarde. |

Depois de enviar, confira o evento `message.received` no seu webhook ou abra o
destinatário no Inspector.

Consulte os métodos na referência da API: [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) e
[Unlink testing phone device](https://docs.polymorfa.com/api/testing/unlink-testing-phone-device).
