# Test phones

A workspace's test phones are the WhatsApp numbers that reach its agent's
preview version through Vatio's shared preview number (see
[Preview](https://vatio.ai/docs/api/messages#preview)). Your backend adds a team member's phone
here so they can talk to the agent before the workspace has a WhatsApp number
of its own, without sending a code.

These endpoints take a secret key with the `team` scope, like
[Team members](https://vatio.ai/docs/api/team-members#vatio-trusts-your-backend).

## Add a test phone

```http
PUT /api/server/v1/:slug/test_phones
Authorization: Bearer vsk_…
Content-Type: application/json

{ "phone_number": "+56912345678" }
```

Only a team phone is accepted: the verified WhatsApp of the workspace owner or
of one of its members. Make the person a member with
[`PUT team_members`](https://vatio.ai/docs/api/team-members#add-or-update-a-member) first; that is
what verifies their phone.

The call is idempotent. It answers `201` when the phone was added and `200`
when it already was a test phone of this workspace:

```json
{ "data": { "phone_number": "+56912345678", "verified_at": "2026-10-27T11:09:55Z" } }
```

It is refused, and nothing changes, when:

- the phone is not the verified WhatsApp of the owner or a member
  (`422 not_a_team_phone`);
- the workspace's own WhatsApp number is connected and live
  (`409 own_number_connected`): test phones are only for the shared preview
  number;
- the phone is a test phone of a workspace with a different owner
  (`409 other_workspace`): it is not taken from there. A test phone of another
  workspace with the same owner moves to this one;
- the workspace already has 5 test phones (`409 workspace_full`).

## List test phones

```http
GET /api/server/v1/:slug/test_phones
Authorization: Bearer vsk_…
```

```json
{ "data": [ { "phone_number": "+56912345678", "verified_at": "2026-10-27T11:09:55Z" } ], "max": 5 }
```

Every test phone of the workspace, newest first, including ones added in the
inbox. `max` is how many a workspace can have.

## Remove a test phone

```http
DELETE /api/server/v1/:slug/test_phones/%2B56912345678
Authorization: Bearer vsk_…
```

The phone goes in the path, URL-encoded (`%2B` for `+`). It answers `204`, or
`404 not_found` when the phone is not a test phone of this workspace. The
person's membership and verified phone stay.

## Errors

Errors carry `{ "error": { "code", "message" }, "request_id" }`.

| Status | Code | Meaning |
|---|---|---|
| 401 | `invalid_key` | The key is missing, invalid or revoked. |
| 403 | `workspace_forbidden` | The key belongs to another workspace. |
| 403 | `insufficient_scope` | The key does not have the `team` scope. |
| 404 | `not_found` | `DELETE` for a phone that is not a test phone of this workspace. |
| 409 | `own_number_connected` | The workspace's own WhatsApp number is live. |
| 409 | `other_workspace` | The phone is a test phone of a workspace with a different owner. |
| 409 | `workspace_full` | The workspace already has 5 test phones. |
| 422 | `invalid_phone_number` | `phone_number` is missing or not a full international number. |
| 422 | `not_a_team_phone` | The phone is not the verified WhatsApp of the owner or a member. |
| 429 | `rate_limited` | More than 30 writes a minute with this key. |

Adding and removing are recorded in the workspace's **Activity** as done by the
key, with the last four digits of the phone. A call that changes nothing is not
recorded there.