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.
One display identity for every channel. channel — imessage,
whatsapp, or both — together with name and/or an avatar photo sets
the same identity on the channel(s) it names, in a single request. Use
both when the number should look the same everywhere: the name and
photo are validated against every targeted channel before any of
them is written, so a value one channel would reject (a name over
WhatsApp’s 25-character limit, a non-square photo, a number whose
WhatsApp line isn’t connected yet) fails the whole request instead of
leaving the two profiles disagreeing.
name is one string. WhatsApp stores it verbatim; iMessage has no
single-name field, so it is split on the first space — "Ana Lee"
becomes first name "Ana" and last name "Lee", "Ana Maria de Souza"
becomes "Ana" and "Maria de Souza", and a single word leaves the last
name cleared. name requires channel, and channel cannot be combined
with the per-channel fields below — a request carrying both is rejected
with 400.
iMessage display identity. To give the channels different
identities, omit channel and use the per-channel fields. 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.
WhatsApp display identity. On WhatsApp-ready numbers, whatsappName
and a whatsappAvatar/whatsappAvatarUrl set the display name and photo
shown to WhatsApp recipients. The name is 1–25 characters and cannot
contain the reserved verification marks (✔, ✅, ☑); the avatar must be a
square jpeg or png between 192×192 and 640×640 (Dial validates the
dimensions and does not resize). WhatsApp photos can’t be transparent,
so a png with any transparent pixel is rejected with 400 — flatten it
onto a background first. These fields apply only to
WhatsApp-ready numbers — rejected with 400 otherwise, including while
whatsapp.status is still provisioning or warming_up. Unlike the
iMessage identity, the request blocks until WhatsApp confirms the
change; if the WhatsApp line can’t be driven, the call returns 503.
Authentication
Your Dial API key, sent as Authorization: Bearer sk_live_...
Path parameters
Request
New inbound voice-agent system prompt for this number.
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.
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.
Human-readable label for the number. Trimmed; at most 100 characters. Send null or an empty string to clear it.
Which display profile(s) name and avatarUrl are written to. both writes one identity to every channel the number has, validated against each before any is written. Cannot be combined with firstName, lastName, whatsappName, or whatsappAvatar/whatsappAvatarUrl — rejected with 400.
Display name to set on the channel(s) named by channel, which is required alongside it. WhatsApp stores it verbatim (1–25 characters); iMessage splits it on the first space into its first/last name pair.
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. Cannot be combined with channel.
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.
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. The photo can be replaced but not removed — null is rejected with 400.
Without channel this is the iMessage avatar: jpeg, png, gif, or webp, max 5 MB, and only valid on numbers with the imessage capability. With channel it is applied to the channel(s) named there, and when WhatsApp is among them it must also meet WhatsApp’s stricter rules — a square jpeg or png between 192×192 and 640×640, with no transparent pixels.
WhatsApp display name for this number’s WhatsApp line, shown to recipients as the sender name. Trimmed; 1–25 characters. Cannot be cleared, and cannot contain the reserved verification marks (✔, ✅, ☑). Only valid on WhatsApp-ready numbers — rejected with 400 otherwise. The request blocks until WhatsApp applies the change; a failure returns 503.
Publicly reachable http(s) URL of an image to set as the number’s WhatsApp avatar. Dial downloads it server-side, mirrors it into its own storage, and serves it from the whatsappAvatarUrl returned on the number. jpeg or png; the image must be square, between 192×192 and 640×640 — any other dimensions are rejected with 400 (Dial does not resize). A png with any transparent pixel is also rejected with 400. Only valid on WhatsApp-ready numbers.
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.
Switch calling on or off for this number, in both directions. false stops inbound calls from being connected and makes Place a call from this number return 409 calling_disabled; messaging is unaffected. Takes effect on the next call — a call already in progress is not terminated. capabilities does not change.
Forward every inbound call to this number to another phone number, in E.164 (for example your own business line). While it is set, an inbound call is not answered by the AI voice agent: it rings straight through to forwardTo, and the caller is connected when that phone answers. Must be a valid E.164 number other than this number itself, or 400. Send null (or an empty string) to stop forwarding, so the AI voice agent answers again. Takes effect on the next call. Has no effect while callingEnabled is false — the call is still not connected.