--- title: "Turn phone calls on for a number" method: POST path: "/v3/channels/voice" tags: ["Channels", "Voice"] --- # Turn phone calls on for a number `POST /v3/channels/voice` ## Request - Base URL: `https://api.sent.dm` - URL: `https://api.sent.dm/v3/channels/voice` - Auth: one of: - API key in header `x-api-key` - HTTP bearer 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. ## Headers - `Idempotency-Key` string - `x-profile-id` string, uuid ## Request body - SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest: Turns phone calls on for a number: one you already hold, or a new one. Voice is per number the way SMS is per market: each number you hold can carry calls on its own, and each has its own callback URL, where Sent asks what to do with every call on it, or a voice agent that answers calls to it. The first number you turn voice on for becomes the line app-originated calls are placed from when a voice token names no number. Send number to add calls to a number you already hold, or leave it out to be given a new US number — optionally in a particular area_code. The two are alternatives, not a pair. - `sandbox` boolean: Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution - `number` string, nullable: One of your phone numbers, in E.164 format. Leave the field out entirely to be given a new one instead; sending it empty is a refused request rather than a request for a new number. - `area_code` string, nullable: The US area code a new number should be in, as 212. Only for a request that leaves number out — sending both says two different things about which number to use, and is refused. Omit it too and the number comes from anywhere in the country. - `callback_url` string, nullable: Where Sent asks what to do with each call on this number: an absolute HTTP or HTTPS URL on a public host. A signed question is POSTed here when a call arrives or a caller presses a key, and the answer decides the call. Every question is signed with the callback_secret the response returns, the same way your webhooks are signed. Turning the number on again with a different URL replaces it and keeps the secret. Required unless agent_id is sent. - `agent_id` string, nullable: One of your voice agents (GET /v3/voice/agents), such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to this number. It wins over callback_url for calls to the number, and both may be sent; calls your app places from the number still follow your app. Send it instead of callback_url for a number only an agent answers. - `default_for_app_calls` boolean, nullable: Make this the line app-originated calls are placed from when a voice token names no number. Omit it and your first voice number takes that role; a later one leaves it where it is. ## Response `201` Voice is on for the number; store callback_secret now - SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceNumberCreatedResponse: Standard API response envelope for all v3 endpoints - `success` boolean: Indicates whether the request was successful - `data` SentDmServicesEndpointsCustomerAPIv3ChannelsResponsesVoiceNumberCreatedResponse: A voice number as it was just turned on: the same facts GET /v3/channels reports, plus the one it never shows, the signing secret. - `number` string: The number, in E.164. - `status` string: ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing provisions: a number the customer holds can carry calls the moment voice is turned on for it. - `default_for_app_calls` boolean: Whether this is the line app-originated calls are placed from when a voice token names no number. Exactly one active voice number carries it while the profile has any. - `callback_url` string, nullable: Where Sent asks what to do with each call on this number: a signed question is POSTed here when a call arrives or a caller presses a key, and the answer decides the call. The signing secret is not on this read; it is shown when voice is turned on and by the rotate endpoint. - `agent_id` string, nullable: The voice agent calls to this number go to, such as agent_9f2ab000-0000-4000-8000-000000000001. It wins over callback_url for calls to the number; calls your app places from the number still follow your app. Null when no agent answers the number. - `routes_to` string: Who answers calls to this number: agent, the voice agent in agent_id; agent_pending, that agent once the number has finished moving to it, with calls possibly unanswered until then; callback, your callback_url; or none, in which case calls to it are declined. - `created_at` string, date-time - `updated_at` string, date-time - `callback_secret` string: The whsec_ secret every question to callback_url is signed with. Shown here and by POST /v3/channels/voice/{number}/rotate-secret, nowhere else: store it now. Verify a question exactly as you verify a webhook, with X-Webhook-ID, X-Webhook-Timestamp and the body. - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information - `code` string: Machine-readable error code (e.g., "RESOURCE_001") - `message` string: Human-readable error message - `details` object, nullable: Additional validation error details (field-level errors) - `doc_url` string, nullable: URL to documentation about this error - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata - `request_id` string: Unique identifier for this request (for tracing and support) - `timestamp` string, date-time: Server timestamp when the response was generated - `version` string: API version used for this request ## Other responses - `202`: Sandbox: the request is valid and this is what would have been written - `400`: The number is not a phone number or not one of your numbers, number and area_code were both sent, callback_url is not a public HTTP or HTTPS URL, neither callback_url nor agent_id was sent, or agent_id is not an agent id - `401`: Unauthorized - Invalid API credentials - `403`: Forbidden - `404`: agent_id is not one of your voice agents - `409`: Another account already carries calls on this number, or no number is available in the area code asked for - `500`: Internal server error - `502`: The number could not be set up to receive calls or moved to your agent, or agent_id was sent while numbers cannot be bound to agents (refused before any number is obtained); nothing was written ## Changes - **2026-10-28** `41acb2ceb84d`: 9 info - added the new optional request property `allOf[subschema #2: SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest_Properties]/agent_id` - the request property `allOf[subschema #2: SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest_Properties]/callback_url` became nullable - the request property `allOf[subschema #2: SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest_Properties]/callback_url` became optional - the `allOf[subschema #2: SentDmServicesEndpointsCustomerAPIv3ChannelsRequestsAddVoiceChannelRequest_Properties]/callback_url` request property's minLength was decreased from `1` to `0` - …5 more - **2026-10-16** `6c829543a93e`: 1 info - endpoint added [Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/channels/voice/post.md) --- [API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)