SEsentdm
Channels
Voice

Change one voice number

Changed on

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

BodyEffect
"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": truemakes 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": nullunbinds the agent, so callback_url answers calls to the number again
key omittedleft 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.

patch/v3/channels/voice/{number}

Request

  • Base URL
    https://api.sent.dm
  • URL
    https://api.sent.dm/v3/channels/voice/{number}
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Path parameters

numberstring required

The number in E.164 format with the plus sign URL-encoded, e.g. %2B12125550100

Headers

Idempotency-Keystring

Unique 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.

x-profile-idstring uuid

Profile 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.

Request body

sandboxboolean

Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

status'ACTIVE' | 'INACTIVE' nullable

ACTIVE turns calls on for the number again, INACTIVE turns them off. Matched ignoring case. Turning the default line off is refused while other active voice numbers remain.

default_for_app_callsboolean nullable

true makes this the line app-originated calls are placed from when a voice token names no number. false is refused: an account with active voice numbers always has exactly one default, so the default moves by giving it to another number.

callback_urlstring nullable

A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL on a public host, where Sent asks what to do with each call. The signing secret is kept.

agent_idstring nullable

One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to the number, or null to unbind it so the callback URL answers them again. The agent wins over callback_url for calls to the number; calls your app places from it still follow your app.

Example request

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

Response

The voice number as stored

successboolean

Indicates whether the request was successful

Changes

  • 41acb2ceb84dRevision changes
    • info

      added the new optional request property /

    • info

      added the non-success response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

  • 6c829543a93eRevision changes
    • info

      endpoint added