Capabilities

Send an SMS

View as Markdown

Send a text message from one of your Dial numbers to any phone number. You need two things: the recipient in E.164 format (e.g. +14155550123) and the id of the Dial number you’re sending from (run dial number list to find it).

$dial message \
>  --to +14155550123 \
>  --body "Hello from Dial" \
>  --from-number-id pn_123

The message comes back with an id and a status of sent, which advances to delivered (or undelivered/failed, with a statusError reason) as the carrier reports back. Track delivery and replies by streaming events or listing messages (GET /api/v1/messages).

Accounts on a subscription can send SMS only to US numbers — any other destination is rejected with a 400. Pay-as-you-go accounts can send to any supported destination.

Attach media (MMS)

Attach up to 10 media items (5 MB each) to a message. Supply each one either as a local file — the CLI and SDKs upload it for you — or as a public URL that Dial downloads server-side. Either way Dial mirrors the bytes into its own storage and serves them from a stable public URL, returned in the message’s media array.

Supported types: images (jpeg, png, gif, webp, bmp), audio (mp3, m4a, ogg, wav, amr), video (mp4, 3gpp), pdf, vCard (.vcf), and iCalendar (.ics). Any other type is rejected with a 400. Note that HEIC (the default iPhone photo format) and SVG are not supported — convert HEIC to JPEG/PNG before sending.

$dial message \
>  --to +14155550123 \
>  --body "Here's your call summary" \
>  --from-number-id pn_123 \
>  --media ./summary.png \
>  --media https://your-cdn.example.com/chart.jpg
Dial sends over SMS. The to and from numbers must both be in E.164 format.
True MMS delivery is supported only for US and Canada numbers. To other destinations, the carrier delivers the message as an SMS containing a link to the media rather than an inline attachment (and returns an error if that conversion is disabled). The media itself is still hosted by Dial at the media[].url either way.
iMessage numbers. A message with media sent from an iMessage number is delivered as native attachments when the recipient supports rich messaging (iMessage or RCS) — text and media arrive together as one message. When the recipient supports neither (e.g. an Android device without RCS), Dial delivers the same message as a text with the media links appended, from the same number. The message’s media array is identical either way.
Sending isn’t idempotent — there’s no idempotency key, so a retry sends a second SMS. If a request fails ambiguously, confirm before re-sending rather than blind-retrying.

Next

Receive an SMS
Wait for a reply or one-time code.
Place a voice call
Make an AI voice call instead.