> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# How Dial works

> The Dial request and event model: outbound actions and inbound events, conceptually.

Everything in Dial is one of two directions: **outbound** actions you take, and **inbound** events you receive.

```mermaid
flowchart LR
  A["Your agent (CLI / SDK)"] -->|send message / place call| D["Dial"]
  D -->|SMS / voice| P["Phone"]
  P -->|reply / inbound call| D
  D -->|event stream| A
```

## Outbound: you act

When you [send a message](/documentation/capabilities/send-an-sms) or [place a call](/documentation/capabilities/place-a-voice-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](/documentation/capabilities/receive-an-sms) for a specific event or keep a [live stream](/documentation/platform/stream-account-events) 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](/documentation/platform/webhooks): 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](/documentation/cli/commands), the [SDKs](/documentation/sdks/overview), and direct REST calls all drive the same model above. Use whichever fits your agent — they interoperate, because they're the same API underneath.