Core concepts

Five nouns explain the whole platform.

Agents (personas)

An agent is a persona on the phone: a name, a playbook (system_prompt), a greeting (first_message), a voice, optional knowledge, and optionally a number. Create one from a preset in a single call (POST /api/agents/quickstart) or field by field (POST /api/v1/agents). A persona is just an agent made public.

Phone numbers

A number belongs to exactly one agent — that invariant is what makes inbound routing unambiguous. Provisioning wires Twilio voice, SMS, and status webhooks automatically, so the number works the moment it exists. In the v1 API a number is addressed by its owning agent (number.id == agent.id).

Calls

Inbound calls hit the agent that owns the dialed number. Outbound calls are placed with POST /api/v1/calls (agent_id, to, optional objective). Every call persists a turn-by-turn transcript you can poll live, plus post-call summary, sentiment, and intent.

Messages

The same number does two-way SMS (POST /api/v1/messages) and receives WhatsApp. Inbound messages are answered by the owning agent and emitted as events.

Events

Everything observable — call.started, call.ended, call.transcribed, call.completed, call.takeover, message.received, message.sent, webhook.ping — is persisted and delivered three ways: signed webhooks, an SSE stream, and cursor/long-poll endpoints. Pick per consumer; they're the same events.

How they fit

persona + voice + number  →  agent
agent + caller            →  call (live transcript)
agent + knowledge base    →  grounded answers
anything happening        →  event → webhook / stream / poll