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

# Quickstart

> Four requests from nothing to a ringing phone.

You will need a SIP trunk you already have. Wixzel Voice does not resell
telephony, so your carrier rates stay yours.

<Steps>
  <Step title="Connect your SIP trunk">
    Your carrier's credentials. The password is stored encrypted and is never
    returned by the API again — including to you.

    ```bash theme={null}
    curl https://api.voice.wixzel.com/v1/sip-trunks \
      -H "Authorization: Bearer $WIXZEL_API_KEY" \
      -d '{
        "name": "My carrier",
        "host": "sip.carrier.example",
        "username": "acct123",
        "password": "…"
      }'
    ```
  </Step>

  <Step title="Register a number on it">
    ```bash theme={null}
    curl .../v1/phone-numbers \
      -d '{
        "phone_number": "+14155550100",
        "sip_trunk_id": "st_01HXYZ"
      }'
    ```

    Give it an `inbound_agent_id` and inbound calls to this number are answered
    automatically.
  </Step>

  <Step title="Create an agent">
    Name the models you want. Call [`GET /v1/engines`](/api-reference/engines) for
    what is available and what each costs.

    ```bash theme={null}
    curl .../v1/agents \
      -d '{
        "name": "Support",
        "system_prompt": "You are a concise support agent.",
        "opening_message": "Hi, how can I help?",
        "voice": {
          "stt": { "model": "deepgram/nova-3" },
          "llm": { "model": "openrouter/gpt-4o-mini" },
          "tts": { "model": "elevenlabs/eleven_turbo_v2_5" }
        }
      }'
    ```

    <Note>
      `opening_message` is required. An agent without one answers in silence, and we
      would rather ask than invent its first words.
    </Note>
  </Step>

  <Step title="Place a call">
    ```bash theme={null}
    curl .../v1/calls \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "to": "+14155551234",
        "agent_id": "ag_01HXYZ"
      }'
    ```

    <Warning>
      `Idempotency-Key` is required here. A network timeout tells you nothing about
      whether the call was placed — without the key your only options are retrying and
      dialling twice, or not retrying and losing the call.
    </Warning>
  </Step>
</Steps>

## See what it cost

Every micro debited against a call is explained by a usage row, so you never have
to reconcile a total by hand.

```bash theme={null}
curl ".../v1/usage/events?session_id=sip-4f2a"
```

| Component      | Model                           | Quantity    | Cost         |
| -------------- | ------------------------------- | ----------- | ------------ |
| `stt`          | deepgram/nova-3                 | 187 s       | \$0.0336     |
| `llm`          | openrouter/gpt-4o-mini          | 8.2k tokens | \$0.0031     |
| `tts`          | elevenlabs/eleven\_turbo\_v2\_5 | 1.4k chars  | \$0.0980     |
| `platform_fee` | orchestration                   | 4 min       | \$0.0480     |
|                |                                 | **Total**   | **\$0.2714** |

## Running out of credit

Credit is reserved before the call is placed, so an underfunded account is
refused with `402` before any resources are allocated.

Mid-call, the agent warns your caller about a minute out and speaks a closing
line before hanging up. It does not drop the line mid-sentence.