Receive an SMS

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.

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:

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

Receive media (MMS)

When an inbound message carries media (pictures, etc.), 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 and originalUrl preserves the carrier’s source URL. Plain SMS events have an empty media array.

1
for item in event["data"]["media"]:
2
    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