> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Quickstart

> Make your first AI voice call in under 5 minutes

# Voice Quickstart

This guide takes you from zero to a working AI voice call in five
minutes. By the end you'll have:

* A phone number that receives inbound calls
* An agent configured with a system prompt
* An inbound call from any phone reaching your agent
* An outbound call dispatched from the API

Orbit's voice stack is end-to-end: **Orbit Media** for the SFU
media plane (forked from LiveKit OSS under Apache-2 — see
[attribution](/legal/attribution)), Deepgram for speech-to-text,
Cartesia for text-to-speech, Claude for the agent reasoning, all
behind a single API. You don't wire any of it yourself.

## Step 1: Provision a number (60 seconds)

The fastest way to start is a **trial number** — free for 7 days,
shared from our pool, no credit card.

1. Open your dashboard at [orbit.devotel.io](https://orbit.devotel.io).
2. From the home page, click **Claim a trial number** in the
   onboarding card. (Already past onboarding? Open **Numbers →
   Buy** and pick **Use a trial number** at the top of the list.)
3. The dashboard assigns one number from the pool and lists it
   under **Numbers**. Note the E.164 form — e.g. `+14155551234`.

For production traffic you'll buy a dedicated DID via **Numbers →
Buy**, but the trial number works for inbound, outbound, SMS, and
voice during the trial window.

## Step 2: Configure an agent (90 seconds)

1. Open **Agents** → **New agent**.

2. Pick a name, leave the type as `voice` (or `chatbot` — voice
   works with any agent type as long as a system prompt is set).

3. Paste a starter system prompt:

   ```text theme={null}
   You are a helpful customer-support assistant for Acme Inc.
   Greet callers, answer questions about order status and returns,
   and escalate anything billing-related by saying "let me transfer
   you to a billing specialist".
   ```

4. Save. Your agent now has a stable ID like `agt_abc123`.

5. Click **Test by voice** (the second pill next to "Test by chat"
   in Agent Studio). Grant mic permission, talk to the agent in
   the browser, and confirm the system prompt is doing what you
   expect before you wire it to a real number. The browser-mic test
   reuses the same Orbit Media + Deepgram + Cartesia pipeline that
   the PSTN path uses, so anything that works here will work on a
   real call.

## Step 3: Route inbound calls to the agent (45 seconds)

1. Open **Numbers**, click your trial (or purchased) number.
2. Under **Inbound routing**, pick **AI agent**.
3. Select the agent you just saved.
4. Save.

## Step 4: Receive your first call

Pick up any phone and dial your provisioned number. Orbit:

1. Answers the call
2. Streams audio through Deepgram for live STT
3. Routes the user-message transcript to the agent
4. Streams the agent's reply through Cartesia TTS back to the
   caller — with barge-in detection so the caller can interrupt
   long replies naturally

You should hear your agent greet you per the system prompt within
two seconds of pickup. If anything feels off, check the call's
live transcript in **Conversations** while you're still on the
call.

## Step 5: Dispatch an outbound call from the API

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155551234",
    "agent_id": "agt_abc123"
  }'
```

`from` must be a number you own or have claimed as a trial. Replace
`agent_id` with the value from Step 2.

### Node SDK

```bash theme={null}
npm install @devotel/orbit-sdk
```

```ts theme={null}
import { Orbit } from "@devotel/orbit-sdk";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const call = await orbit.voice.calls.create({
  to: "+14155552671",
  from: "+14155551234",
  agent_id: "agt_abc123",
});

console.log(call.id);
```

The Node SDK supports a first-class `agent_id` field on `create()`. When set, the call is dispatched to the named, tenant-scoped voice agent — the server validates it exists and is not archived.

The Node and [Web](/sdks/web) SDKs are GA today. For Python / Go / Java / Ruby / PHP / .NET, call the REST endpoint above with your HTTP client of choice until the official SDKs ship.

## Step 6: Subscribe to call events (optional)

Orbit surfaces call activity two ways: **webhooks** for
server-to-server call-lifecycle delivery, and a **per-call
transcript SSE stream** for live, in-browser transcript tailing.

### Call-lifecycle events (webhooks)

`call.*` lifecycle events — `call.initiated`, `call.ringing`,
`call.answered`, `call.completed` — are published to your
registered webhook endpoints, not to an aggregate SSE feed. Point
a webhook at your server and subscribe to the call events you care
about. See [Webhook Events](/webhooks/events) for the full event
catalog and [Webhooks](/webhooks/overview) for endpoint setup and
HMAC verification.

### Live transcript (per-call SSE)

For an in-browser dashboard you can tail a single call's live
transcript over SSE. First mint a short-lived, call-bound ticket
(so a long-lived API key never lands on the SSE URL), then open the
stream with that ticket:

```js theme={null}
// 1. Mint a 60s single-use ticket for this call.
const { ticket } = await fetch(
  `https://api.orbit.devotel.io/api/v1/voice/calls/${callId}/transcript/ticket`,
  { method: "POST", headers: { "X-API-Key": apiKey } },
).then((r) => r.json());

// 2. Open the per-call transcript SSE stream with the ticket.
const evt = new EventSource(
  `https://api.orbit.devotel.io/api/v1/voice/calls/${callId}/transcript/stream?ticket=${ticket}`,
);

evt.addEventListener("transcript", (e) =>
  console.log("transcript", JSON.parse(e.data)),
);
```

## Language coverage

The voice agent pipeline (Deepgram Nova-3 STT → Claude reasoning →
Cartesia Sonic Turbo TTS) is generally available in **English,
French, Spanish, and German**. Set `language` on the agent config
to `en-US`, `fr-FR`, `es-ES`, or `de-DE` and expect production-grade
prosody, barge-in, and turn detection.

The default TTS model is **Sonic Turbo** (`DEVOTEL_CARTESIA_TTS_MODEL=sonic-turbo`),
tuned for the lowest synthesis latency. Sonic 3.5 is only used when an
operator overrides the model via that env var.

**Turkish (`tr-TR`)** and **Arabic (`ar-SA`)** are in **beta** —
recognition works, but prosody / disfluency edge cases are still
being tuned, so long-form replies may sound slightly off and heavy
code-switching can lower transcript confidence. They work today;
please flag specific phrases that sound wrong so we can feed them
back into the tuning set.

Other locales are on the roadmap. The upstream providers cover \~30
languages between them, but we only GA a locale after validating
phone-PSTN audio quality against the \<500 ms round-trip
budget. [Contact us](mailto:hello@devotel.io) for early access to a
locale that isn't listed above.

## Common next steps

* **Add knowledge:** attach a knowledge base to your agent so it
  can answer FAQ-style questions grounded in your docs. See
  [AI Agents → Creating Agents](/agents/creating-agents).
* **Handoffs:** route specific intents (billing, returns, sales) to
  different agents or to a human queue. See
  [Handoff Targets](/agents/handoff-targets).
* **Cost controls:** set a daily spend cap so a misbehaving prompt
  can't blow through your wallet. See
  [Cost Controls](/agents/cost-controls).
* **Production numbers:** buy a dedicated DID from **Numbers →
  Buy** when you're ready to leave the trial pool. Numbers in
  regulated countries (US, DE, FR, …) may require a compliance
  bundle — the dashboard surfaces the required steps inline.

## Cross-references

* Text-message quickstart: [Quickstart](/quickstart)
* Voice channel reference: [Channels → Voice](/channels/voice)
* Voice API reference: [API → Voice & Numbers](/api-reference/voice)