Skip to navigation
Capabilities

Receive an SMS

View as Markdown

When someone texts one of your Dial numbers, Dial emits a message.received event. The most common use is catching a one-time code: an agent triggers an SMS verification on some service, then waits for the code to arrive on its Dial number.

You don’t poll for messages — you wait for the event. There are two ways to wait.

For a one-time code, an active wait (below) is the right tool. But note the underlying event stream is presence-based, not at-least-once — a long-lived listener replays missed events only if it reconnects within 2 minutes. For guaranteed delivery, register an at-least-once webhook.

Wait once

Block until the next inbound message arrives (or a timeout elapses). Ideal for a single code.

# Blocks until an inbound SMS arrives, prints the event as JSON, then exits.
dial wait-for message.received --timeout 60 --json

The CLI and REST events/wait return as soon as a matching event arrives. If nothing arrives within the timeout, the REST endpoint responds 408; the CLI exits non-zero.

Filter to a specific number

If you have several numbers, match on event fields so you only wake for the right one:

dial wait-for message.received --field to=+14155550123 --timeout 60 --json

Use --field name=value for exact matches or --regex name=pattern for patterns (both repeatable).

Extract the code

An inbound message.received event carries the message text at data.body. Pull the code out with a regex in your agent — for example, the first 6-digit run:

import re
code = re.search(r"\b(\d{6})\b", event["data"]["body"]).group(1)

Receive media (MMS and iMessage attachments)

When an inbound message carries media (pictures, etc.) — an MMS on an SMS number or an attachment on an iMessage number — the event’s data.media array lists each attachment with a stable, unauthenticated url hosted by Dial — fetch or render it directly, no API key needed. contentType gives the MIME type. Text-only events have an empty media array.

A shared contact is media too. When someone sends a contact card to your iMessage or WhatsApp line, it arrives as a media item with contentType: "text/vcard", and its url serves the .vcf file itself — parse it with any vCard library, or import it straight into an address book. The message body carries the contact’s display name, so you can show who was shared without parsing the card. The same holds for a vCard attached to an MMS.

for item in event["data"]["media"]:
    print(item["contentType"], item["url"])

Media is also returned on GET /api/v1/messages (each message’s media array), so you can recover attachments after the fact without having caught the event.

Next

Stream account events
Keep a long-lived connection open.
Listen service
Capture events in the background.