Adds voice to one of the numbers you hold, or gives you a new one. Send number for a number that is already yours (see GET /v3/channels); leave it out to be given a new US number, optionally in a particular area_code. Sending both is refused. Nothing registers, so the number can carry calls as soon as this returns.

What happens on a call is decided by your callback_url: when a call arrives on the number, or a caller presses a key on a menu, Sent POSTs a signed question there and follows the answer. The response carries the callback_secret the questions are signed with, the one time it is shown without rotating; verify a question the way you verify a webhook. POST /v3/channels/voice/{number}/test sends a test question and reports the verdict.

Send agent_id instead of callback_url, or with it, to have one of your voice agents (GET /v3/voice/agents) answer calls to the number. The agent wins over the callback URL for calls to the number; calls your app places from it still follow your app. routes_to in the response says which answers, and reads agent_pending while the number is still being moved to the agent. Calls follow the move within about an hour, as the provider applies it on its own clock. While numbers cannot be bound to agents, a request with agent_id is refused with 502 before any number is obtained or anything is written; send callback_url instead.

Your first voice number becomes the line app-originated calls are placed from when a voice token names no number; send default_for_app_calls: true to give that role to another number. A number you turned off earlier is turned back on, and the same number with a different callback_url has its URL replaced and keeps its secret.

Read the number's settings with GET /v3/channels/voice and change them with PATCH /v3/channels/voice/{number}.

With sandbox: true the request is validated and a simulated number reported with 202; nothing is written and no number is bought.

{
  "number": "+12125550100",
  "callback_url": "https://example.com/voice"
}