Rotate a voice number's callback secret
Generates a new signing secret for the questions Sent sends to this number's callback URL and returns it. The previous secret stops signing immediately, so update your backend before the next call reaches it. The number is the E.164 value in the path with the plus sign URL-encoded (%2B).
With sandbox: true a secret is generated and returned with 202, and nothing is written.
number*stringThe voice number from the route, in E.164 format with the plus sign URL-encoded (%2B), for example /v3/channels/voice/%2B12025550123/rotate-secret.
Idempotency-Key?stringUnique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.
^[a-zA-Z0-9_-]+$length <= 255x-profile-id?stringProfile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.
uuidapplication/json- body
Base request for mutation operations (POST, PUT, PATCH) with sandbox mode support
sandbox?booleanSandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution
The new secret. The old one no longer signs anything
application/json- response
Standard API response envelope for all v3 endpoints
success?booleanIndicates whether the request was successful
data?|nullThe response data (null if error)
error?|nullError details (null if successful)
meta?Metadata about the request and response
curl -X POST 'https://api.sent.dm/v3/channels/voice/+12125550100/rotate-secret' \ -H 'Idempotency-Key: req_abc123_retry1' \ -H 'Content-Type: application/json' \ -d '{ "sandbox": false}'{ "success": true, "data": { "callback_secret": "whsec_MWYyZDFlMmU2N2RmNmI3YThmNTZhODFiYzJlNGQzYjI=" }, "error": null, "meta": { "request_id": "req_7X9zKp2jDw", "timestamp": "2026-11-12T15:32:26.8665131+00:00", "version": "v3" }}Change one voice number PATCH
Changes one of your voice numbers and answers with the number as stored, the same shape `GET` on this path returns, so what comes back can be sent back. ## What it changes | Body | Effect | | --- | --- | | `"status": "ACTIVE"` | turns calls on again for a number you turned off; the callback URL and the secret it had are kept | | `"status": "INACTIVE"` | turns calls off; the callback URL and the secret stay on the number | | `"default_for_app_calls": true` | makes this the line app-originated calls are placed from when a voice token names no number | | `"callback_url": "https://example.com/voice"` | replaces where Sent asks what to do with each call on the number; the signing secret and the status are kept | | `"agent_id": "agent_…"` | one of your voice agents answers calls to the number, within about an hour of the change (the provider applies the move on its own clock, and `routes_to` reads `agent` as soon as it has recorded it); it wins over `callback_url` for calls to the number, and calls your app places from it still follow your app. `routes_to` reads `agent_pending` while the number is still being moved to the agent | | `"agent_id": null` | unbinds the agent, so `callback_url` answers calls to the number again | | key omitted | left exactly as it is | `status` is matched ignoring case. Any combination is accepted: `status: "ACTIVE"` with `default_for_app_calls: true` turns a number on as the new default, and a `callback_url` sent with either status is written too. `agent_id` is applied first, so a refusal to move the number to or from the agent leaves everything as it was, and the `409` and `400` refusals below are decided before anything is written, so they leave everything as it was too. A body that names none of them is refused. A number can be on without a callback URL: calls placed from your app then connect straight to the number or user they dial, and calls to the number are declined. ## What it will refuse **`default_for_app_calls: false` is `400`.** An account with active voice numbers always has exactly one default, so the default moves by giving it to another number. **Turning the default line off is `409`** while other active voice numbers remain. Move the default to another number first. Turning off your last voice number is allowed; that turns phone calls off. **Making an inactive number the default is `400`.** Send `status: "ACTIVE"` in the same call. **A number you never turned voice on for is `404`**, and so is an `agent_id` that is not one of your agents. Add the number with `POST /v3/channels/voice`. **`502` means the number could not be moved to or from the agent**, or an `agent_id` was sent while numbers cannot be bound to agents; nothing was written. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`). With `sandbox: true` nothing is written: the request is validated against the stored number and the number is reported with `200` as it would read after the change.
Test a voice number's callback URL POST
Sends a synthetic call.request question, flagged "test": true, to the number's callback URL, signed with that number's real secret, and reports what came back. Use it to build and debug your callback endpoint without placing calls: no call is placed, nothing is billed, and nothing is stored. One attempt with the same deadline as a live call, no retry. The outcome is ok when your endpoint answered 2xx with a valid answer; otherwise it is timeout, connection_failed, http_error or invalid_answer, with the reason and, for an invalid answer, the field at fault. The number is the E.164 value in the path with the plus sign URL-encoded (`%2B`). With `sandbox: true` nothing is sent: the verdict comes back ok with `202` and no request or response in it.