How Dial works
Everything in Dial is one of two directions: outbound actions you take, and inbound events you receive.
Outbound: you act
When you send a message or place a call, you make a request to Dial from one of your phone numbers. The request returns immediately with a record — a message or call and its initial status. The final outcome (delivered, answered, completed) happens asynchronously; you observe it through events or by reading history.
Inbound: you receive
When someone texts or calls one of your numbers, Dial turns it into an event on your account’s stream — message.received for an inbound SMS, call.ended when a call wraps up. You never poll: you either wait once for a specific event or keep a live stream open. Today that stream is a presence-based notification channel — missed events replay only if you reconnect within 2 minutes — not a durable at-least-once queue. For guaranteed, off-machine delivery, register a webhook: each event is POSTed to your HTTPS endpoint, signed and retried at-least-once.
AI voice calls
An outbound voice call isn’t a recording — it’s a live conversation handled by an AI voice agent. You supply a system prompt (how it should behave) and optionally a language; the agent talks in real time. When no language is given, Dial detects it from the phone number’s country prefix — the destination number for outbound calls, the caller’s number for inbound calls — and the agent handles both that language and en-US. When the call ends, its status, duration, and a transcript become available.
Dial prepends a minimal general context to your system prompt on every call: the current date and time on the other side of the call (derived from their number’s country) and the agent’s voice gender. It’s deliberately small — two facts the agent would otherwise guess at — and your instruction always takes precedence.
One API, many surfaces
The CLI, the SDKs, and direct REST calls all drive the same model above. Use whichever fits your agent — they interoperate, because they’re the same API underneath.