v4

OpenAPI 3.1.02026-08-0255174167.5 KB

phoneNumbers

Update a phone number

Update a number's properties. Send any subset of the fields below — at least one is required; omitted fields are left unchanged. A new inboundInstruction takes effect on the next inbound call; in-progress calls are unaffected.

iMessage display identity. On numbers with the imessage capability, firstName, lastName, and an avatar photo set the identity shown beside the number's messages in recipients' Messages apps. Sending any of these fields for a number without the imessage capability is rejected with 400.

The avatar photo is set either by uploading a file (the avatar part, multipart/form-data only) or by passing a publicly reachable image URL (avatarUrl, JSON or multipart) that Dial downloads server-side. Accepted types: jpeg, png, gif, webp; max 5 MB. A square image of 512×512 or larger is recommended — it is shown as a circle. Dial mirrors the photo into its own storage and serves it from the stable public URL returned as avatarUrl. The photo can be replaced but not removed — avatarUrl: null is rejected with 400. Identity changes can take a few minutes to propagate to recipients' devices.

patch/api/v1/numbers/{id}

Path parameters

idstring required

Headers

Authorizationstring required

Your Dial API key, sent as Authorization: Bearer sk_live_...

Request body

inboundInstructionstring

New inbound voice-agent system prompt for this number.

inboundVoiceGender'male' | 'female'

Voice gender for the AI agent on inbound calls to this number. Send null to clear it (the voice reverts to the default, female). Takes effect on the next inbound call.

inboundLanguagestring nullable

BCP-47 language tag for the AI voice agent on inbound calls to this number. Send null to clear it — the language is then detected from the caller's country prefix on each call, with the agent handling both that language and en-US. Takes effect on the next inbound call.

nicknamestring nullable

Human-readable label for the number. Trimmed; at most 100 characters. Send null or an empty string to clear it.

firstNamestring nullable

iMessage display first name shown beside this number's messages in recipients' Messages apps. Trimmed; at most 30 characters. Send null or an empty string to clear it. Only valid on numbers with the imessage capability — rejected with 400 otherwise.

lastNamestring nullable

iMessage display last name. Trimmed; at most 30 characters. Send null or an empty string to clear it. Only valid on numbers with the imessage capability — rejected with 400 otherwise.

avatarUrlstring uri

Publicly reachable http(s) URL of an image to set as the number's iMessage avatar photo. Dial downloads it server-side, mirrors it into its own storage, and serves it from the avatarUrl returned on the number. jpeg, png, gif, or webp; max 5 MB. The photo can be replaced but not removed — null is rejected with 400. Only valid on numbers with the imessage capability.

maxCallDurationSecondsinteger nullable

Cap on the length of calls on this number, in seconds, for both inbound calls to the number and outbound calls placed from it. The effective cap on a call is the first one set in priority order — the per-call cap, then this number cap, then the account cap — falling back to the global default. This number cap overrides the account cap (raising or lowering the limit) but is itself overridden by a per-call cap. Must be between 60 and 3600 seconds (1 minute to 1 hour); a value outside that range returns 400. Send null to clear it (falls back to the account cap or global default). Free accounts — accounts that have never added credit and never subscribed — are capped at 300 seconds (5 minutes), reported as limits.maxCallDurationSeconds on the account: a higher value sent here returns 400, and a cap inherited from another level is clamped to 300. When a cap is active, Dial automatically injects a warning to the agent ~40 seconds before the hard cut, prompting it to wrap up naturally.

Response

Updated.