Give Your AI Agent a Phone Number

What you're building

A Spix call playbook — a reusable AI phone agent — that can call any number, introduce itself, and have a real conversation. You'll trigger the first call from the command line, watch the live transcript as it happens, and see the full summary when it ends.

$ spix --json call create +19175550123 --playbook plb_call_abc123 --sender +14155550101

{
  "status": "ok",
  "data": {
    "session_id": "cse_xyz789",
    "playbook_id": "plb_call_abc123",
    "playbook_name": "intro-agent",
    "to": "+19175550123",
    "sender": "+14155550101",
    "state": "dialing"
  }
}

Prerequisites

No API wrappers to install, no LLM API keys to configure — Spix handles the AI layer.

• A Spix account — sign up at app.spix.sh (free, no card required)
• Agent plan ($20/mo, 500 credits included) — the Sandbox plan is email-only; calls require a phone number, which is an Agent feature
• A phone to test with (your own mobile is fine)

Step 1: Install Spix

Spix installs as a single native binary. No package manager, no runtime dependencies.

curl -sf https://spix.sh/install | sh
spix --version

spix 0.9.x

Now authenticate. This opens your browser to app.spix.sh, where you approve the CLI session. Your API key is stored in ~/.spix/config.json.

spix auth login

# Verify the session:
spix --json auth whoami

{
  "status": "ok",
  "data": {
    "email": "[email protected]",
    "workspace": "your-workspace",
    "plan": "agent"
  }
}

Step 2: Rent a phone number

Your agent needs a caller ID — a real phone number that shows up when it dials. Rent one directly from the CLI. US local numbers are $3/month.

spix --json phone rent --area-code 415

{
  "status": "ok",
  "data": {
    "number": "+14155550101",
    "country": "US",
    "type": "local",
    "state": "active",
    "monthly_cost": "$3.00"
  }
}

You can confirm the number is in your inventory at any time:

spix --json phone list

Step 3: Understand the two-step model

Before writing anything, it helps to understand how Spix structures calls.

A Playbook is a reusable agent config: who the AI is, what it knows, what it's trying to achieve, what a successful call looks like. You create a playbook once.

A Call Session is a single invocation of that playbook against a specific phone number. You can run the same playbook against 1 number or 10,000.

This separation matters when you scale. Your sales playbook stays the same; only the target number and briefing data change per call.

Step 4: Create your first playbook

Let's create a simple intro agent — an AI that calls a prospect, introduces itself, and tries to book a 15-minute meeting.

spix --json playbook create --type call \
  --name "intro-agent" \
  --goal "Introduce Spix and book a 15-minute demo with the prospect" \
  --persona "Alex, a friendly SDR at Spix. Direct, not pushy. Respects the prospect's time." \
  --briefing "The prospect signed up for the Spix newsletter last week. First contact." \
  --success-criteria "Prospect agrees to a specific date and time for a demo"

{
  "status": "ok",
  "data": {
    "playbook_id": "plb_call_abc123",
    "type": "call",
    "name": "intro-agent",
    "goal": "Introduce Spix and book a 15-minute demo with the prospect",
    "persona": "Alex, a friendly SDR at Spix. Direct, not pushy. Respects the prospect's time.",
    "success_criteria": "Prospect agrees to a specific date and time for a demo"
  }
}

Note the playbook_id in the response — you'll use it in the next step and whenever you trigger calls.

Voice is optional. Spix defaults to a natural-sounding voice via Cartesia Sonic-3. You can browse and select a specific voice in the dashboard if you want a particular tone or gender.

Step 5: Bind your phone number to the playbook

This tells Spix which playbook should handle calls on this number. Binding is required for inbound calls, and it keeps your outbound workflow organized.

spix --json phone bind +14155550101 --channel call --playbook plb_call_abc123

Step 6: Place your first call

Call yourself first. Seriously — it's the best way to understand what your prospects will experience.

spix --json call create +1YOURNUMBER \
  --playbook plb_call_abc123 \
  --sender +14155550101

Your phone rings within a couple of seconds. Pick up. You'll notice three things:

• The voice sounds natural. Spix uses Cartesia Sonic-3 for synthesis, which handles prosody and pacing well. There's a subtle ambient office atmosphere in the background that makes the call feel less robotic.
• Response latency is fast. End-to-end, from when you stop talking to when the AI starts speaking, is around 500ms. Fast enough to feel like a real conversation rather than a phone tree.
• The AI actually listens. If you go off-script — say something unexpected, ask a question — it adapts. It is not reading from a decision tree.

Under the hood: your voice hits Deepgram Nova-3 for streaming speech-to-text, Claude processes the conversation context against your playbook's goal and persona, then Cartesia Sonic-3 synthesizes the response. That full cycle completes in ~500ms.

Step 7: Watch the live transcript

While the call is in progress, open a second terminal:

spix watch transcript cse_xyz789

[AGENT] Hi, this is Alex from Spix. I'm reaching out because you signed up for our
        newsletter last week — hope that's okay. Do you have two minutes?
[HUMAN] Uh, yeah, sure, what is this about?
[AGENT] Spix gives AI agents the ability to make real phone calls. I'm actually a demo
        of the product right now...

Step 8: Review the summary

After the call ends, Spix evaluates the conversation against your --success-criteria and generates a structured summary:

spix --json call summary cse_xyz789

{
  "status": "ok",
  "data": {
    "session_id": "cse_xyz789",
    "duration_seconds": 102,
    "outcome": "goal_not_met",
    "summary": "Prospect was interested but couldn't commit to a specific time. Asked to be called back Thursday afternoon.",
    "next_action": "Schedule follow-up call for Thursday."
  }
}

You can also pull the full transcript and download the recording:

spix call transcript cse_xyz789
spix call recording download cse_xyz789

Dry runs: test without spending credits

Before running calls against real prospects, validate your playbook config with --dry-run. Note that --dry-run is a global flag, so it goes before the command group:

spix --dry-run call create +19175550123 \
  --playbook plb_call_abc123 \
  --sender +14155550101

Pricing context

Outbound calls cost 10 credits per minute (minimum 10 credits for an answered call; 1 credit for an unanswered attempt). The Agent plan ($20/mo, 500 credits included) gives you roughly 50 answered call-minutes per month before top-ups.

For a prospecting workflow calling 20–30 leads/day, the Operator plan ($99/mo, 5,000 credits) is the right fit.

What's next

You've got a working call agent. But right now it's calling cold — it doesn't know anything about who it's calling beyond the static briefing you wrote.

Part 2 fixes that. We'll pull real data from a CRM (or a CSV if you don't have one), build a dynamic briefing per lead, and write the call outcome back when it ends. Your agent will go from cold-calling to warm outreach with 30 lines of Python.