Send a message | Dial — Communication Stack for AI Agents

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.

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.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

tostringRequired

Recipient phone number in E.164 format.

fromNumberstringOptional

The Dial number to send from, referenced flexibly: a phone-number ID, one of your numbers in E.164 format, or a number’s nickname. A nickname shared by more than one of your numbers is rejected with 400. Provide exactly one of fromNumber or fromNumberId.

fromNumberIdstringOptional

ID of the Dial number to send from (see List phone numbers). Legacy alternative to fromNumber — provide exactly one of the two.

bodystringOptional

Message text. Optional when media is attached; a request with neither a non-empty body nor media is rejected with 400.

forceAudioFilebooleanOptionalDefaults to false

Send an audio attachment as a regular file attachment instead of an iMessage voice message. No effect on standard numbers or non-audio media.

mediaUrlslist of stringsOptional

Publicly reachable http(s) URLs of media to attach. Dial downloads each one server-side and re-hosts it; the source URL is preserved on the media item as originalUrl. iMessage numbers accept at most one item.

Response

Message queued.

messageobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

413

Content Too Large Error

429

Too Many Requests Error

Sends a message from one of your Dial numbers.

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

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.

$	curl -X POST https://api.getdial.ai/api/v1/messages \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"to": "+14155550123"
>	}'

1	{
2	"message": {
3	"id": "string",
4	"phoneNumberId": "string",
5	"from": "+14155550123",
6	"to": "+14155559876",
7	"body": "string",
8	"direction": "inbound",
9	"channel": "sms",
10	"service": "imessage",
11	"status": "delivered",
12	"statusError": null,
13	"media": [
14	{
15	"id": "a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30",
16	"url": "https://getdial.ai/public-media/a3f9c2d41e8b4f0a9c6d2e7b5a1f8c30.jpg",
17	"contentType": "image/jpeg",
18	"originalUrl": "https://your-cdn.example.com/summary.png"
19	}
20	],
21	"replyToId": null,
22	"reaction": null,
23	"createdAt": "2024-01-15T09:30:00Z"
24	}
25	}