Send a message

Sends a message from one of your Dial numbers.

The channel is determined by the number, not the request. A standard number sends SMS/MMS. An iMessage number sends iMessage, automatically falling back to RCS/SMS when the recipient can't receive iMessage — you don't (and can't) pick the channel per message. For standard numbers, status tracks delivery (sent → delivered/undelivered/failed, with a statusError reason on failure); iMessage sends report status: "unknown".

Media. Attach media as public URLs (mediaUrls, JSON or multipart) or as uploaded media file parts (multipart only):

• Standard numbers: up to 10 items combined, 5 MB each.
• iMessage numbers: at most one attachment (URL or file).

body is optional when media is attached — a media-only message sends just the attachment (its body is recorded as an empty string). A request with neither a non-empty body nor media is rejected with 400.

Voice messages (iMessage numbers). When the attachment is a single audio file, it is delivered as a native voice message. If a body is also present, the recipient receives two messages — the text, then the voice message — but the API still returns (and records) a single Message. If the recipient can't receive voice messages (no iMessage/RCS), the audio is delivered as a link over SMS instead. Set forceAudioFile: true to always send audio as a regular file attachment in one message. forceAudioFile has no effect on standard numbers, non-audio media, or multi-attachment sends — audio attached to a standard number's message is always MMS media.

Supported types: images (jpeg, png, gif, webp, bmp), audio (mp3, m4a, ogg, wav, amr), video (mp4, 3gpp), pdf, vCard, and iCalendar; any other type is rejected with 400 (HEIC and SVG are not supported). Dial mirrors every attachment into its own storage and serves it from a stable public URL (see Get public media); the message's media array carries those URLs. For standard numbers, true MMS delivery is supported only for US and Canada — to other destinations the carrier delivers an SMS with a link to the media.

Destination limits (standard numbers): accounts on a subscription can send only to US numbers — any other destination is rejected with 400. Pay-as-you-go accounts can send to any supported destination (a destination with no SMS price tier is rejected with 400).

Choosing the from-number. Provide exactly one of fromNumber (a flexible reference: phone-number ID, one of your numbers in E.164 format, or a nickname) or the legacy fromNumberId (ID only). Sending both — or neither — is rejected with 400.

Not idempotent — there is no idempotency key, so retrying a failed request can send a duplicate message. On an ambiguous failure, confirm via List messages before re-sending.