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.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/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-10-06T09:10:22.6863285+00:00",
"version": "v3"
}
}{
"success": true,
"data": {
"callback_secret": "string"
},
"error": {
"code": "string",
"message": "string",
"details": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"doc_url": "string"
},
"meta": {
"request_id": "string",
"timestamp": "2019-08-24T14:15:22Z",
"version": "string"
}
}{
"success": false,
"data": null,
"error": {
"code": "BUSINESS_024",
"message": "Phone number is not voice-enabled for this account",
"details": null,
"doc_url": "https://docs.sent.dm/reference/api/error-catalog"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-10-06T09:10:22.68633+00:00",
"version": "v3"
}
}{
"success": true,
"error": {
"code": "string",
"message": "string",
"details": {
"property1": [
"string"
],
"property2": [
"string"
]
},
"doc_url": "string"
},
"meta": {
"request_id": "string",
"timestamp": "2019-08-24T14:15:22Z",
"version": "string"
}
}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 is kept, and a number that was waiting for its first URL is turned on | | 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. A body that names none of the three is refused. ## 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 added without a `callback_url` is `INACTIVE` for that one reason, so sending it a `callback_url` turns it on by itself, and it becomes your default line if you have no other active voice number. A number you turned off while it had a URL stays off. **A number you never turned voice on for is `404`.** Add it with `POST /v3/channels/voice`. 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.