Platform

Stream account events

View as Markdown

For anything beyond a single wait, open a long-lived event stream. You’ll receive every event on your account as it happens — message.received for inbound SMS, call.status_changed as a call rings, is answered, and terminates, call.ended when a call finishes, call.transcribed when a call’s transcript is ready, and more. Every event shares one envelope (id, object, type, version, createdAt, relatedObject) with a type-specific data payload. Read fields from event.data; relatedObject.url points at the REST resource (e.g. the call) for the canonical state.

Delivery semantics

The event stream is a presence-based notification channel, not a durable at-least-once queue. If your connection drops, events that occurred while you were disconnected are replayed when you reconnect within 2 minutes — short blips are covered, but longer gaps can miss events. For guaranteed, at-least-once delivery, register a webhook — Dial POSTs each event to your HTTPS endpoint, signed and retried.

From an SDK

Every SDK exposes the same shape: ask the client for an events connection, iterate it, and close it. The connection handles subscription and token renewal for you — you never see the transport.

1from dial_sdk import DialClient
2
3dial = DialClient(api_key="sk_live_...")
4async with dial.new_events_connection() as conn:
5    async for event in conn:
6        if event["type"] == "message.received":
7            print("inbound:", event["data"]["from"], event["data"]["body"])
8        elif event["type"] == "call.transcribed":
9            # thin event — fetch the transcript from the call resource
10            call = dial.get_call(event["data"]["callId"])
11            print("transcript:", call["transcript"])

The connection yields every event on the channel; filter by type in your loop. It stays open until you close it (Python’s async with closes automatically).

dial wait-for / events/wait field filters address data fields by name — -f channel=sms matches event.data.channel, unchanged from before.

From the CLI

To capture events on a machine without writing code, run the listen service — a background daemon that appends every event to a local log your agent can tail.

$dial listen install   # start the background daemon
$dial listen status    # see recent events

Low-level (REST)

If you’re building your own client, POST /api/v1/listen/subscribe mints a short-lived, account-scoped subscription token (subscribeKey, channel, token, ttlSeconds). Re-mint before the TTL expires to keep the stream open. The SDKs do this for you behind new_events_connection(), so reach for the REST endpoint only when porting to a new language.