OptionalavatarOptionalcallingSwitch calling on or off for this number, in both directions. false stops
inbound calls from being connected and makes DialClient.makeCall
from this number throw calling_disabled (409); messaging is unaffected.
Takes effect on the next call — a call already in progress is not ended.
Omitted leaves it unchanged.
OptionalchannelWhich channel(s) name and avatar are written to. Use "both" when the
number should present one identity everywhere: it is a single call instead
of two, and the name and photo are checked against every targeted channel
before any of them is written, so a value one channel rejects can't leave
the two profiles disagreeing. Cannot be combined with the per-channel fields
(firstName, lastName, whatsappName, whatsappAvatar).
OptionalfirstiMessage display first name shown beside this number's messages in
recipients' Messages apps (max 30 chars). null or "" clears it. Valid only
on numbers with the imessage capability — rejected with 400 otherwise.
OptionalforwardForward inbound calls to this phone number (E.164) instead of having the AI
voice agent answer; the call ends if that phone is busy or doesn't answer.
null stops forwarding. Omitted leaves it unchanged. Rejected (400) when not
valid E.164 or when it is the number's own number. Has no effect while
callingEnabled is false.
OptionalinboundNew system prompt the AI voice agent uses on inbound calls to this number.
OptionalinboundBCP-47 language tag pinning inbound calls to this number to one language. null clears it, so the language reverts to per-call detection from the caller's country prefix.
OptionalinboundVoice gender for inbound calls: "male" or "female". null clears it, so the voice reverts to the default (female).
OptionallastiMessage display last name (max 30 chars); null or "" clears it. iMessage numbers only.
OptionalmaxCap calls on this number to at most this many seconds, applied as a hard ceiling to both inbound calls to the number and outbound calls placed from it. The effective cap on any call is the smallest of the per-number, account, and per-call limits.
OptionalnameThe display name to set on the channel(s) channel names; requires channel.
WhatsApp stores it verbatim (1–25 chars). iMessage has no single-name field,
so it is split on the first space — "Ana Lee" becomes first name "Ana",
last name "Lee", and a single word leaves the last name cleared.
OptionalnicknameHuman-readable label for the number, max 100 chars; null or "" clears it.
OptionalwhatsappWhatsApp avatar photo: a public image URL (downloaded server-side), a local file path, or raw bytes (both uploaded as multipart). Square jpeg or png between 192×192 and 640×640 — not resized — with no transparent pixels (a png with any is rejected with 400). WhatsApp-ready numbers only.
OptionalwhatsappWhatsApp display name shown to recipients (1–25 chars, no reserved verification marks). Valid only on WhatsApp-ready numbers; the call blocks until WhatsApp applies it and fails with 503 if the line can't be driven.
The avatar photo: a public image URL (downloaded server-side), a local file path, or raw bytes (both uploaded as multipart). Replace-only — a photo can't be removed.
Without
channelthis is the iMessage avatar: jpeg/png/gif/webp, max 5 MB, iMessage numbers only. Withchannelit is applied to the channel(s) named there, and when WhatsApp is among them it must also satisfy WhatsApp's stricter rules — square jpeg or png between 192×192 and 640×640, not resized, with no transparent pixels.