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

#Add a test phone

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 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:

{ "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

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

{ "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

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" }.

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.