All docs

Voice Quickstart

Buy a voice number, point a persona at it, and take your first AI-answered call.

The Voice API is a paid add-on to your messaging subscription. Voice answers inbound calls in your business voice, transfers to a human when asked, and dials outbound from your code. Inbound and outbound share the same persona and intent configuration.

Step 1: Subscribe to a voice tier

curl -X POST https://api.senderz.com/v1/billing/voice/subscribe \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier":"growth"}'

Tiers: starter (30 min), growth (200 min), scale (500 min). Overage is $0.24 per minute. Voice is excluded from the messaging trial — billing for voice begins immediately.

Step 2: Buy a voice number

curl -X POST https://api.senderz.com/v1/voice/numbers \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","area_code":"619"}'

Response includes the id you’ll use to assign a persona, and the phone_number callers will dial.

Step 3: Set the persona handoff number

The persona’s voice_handoff_number is the only place the AI can transfer a call to. Setting it is what lets the talk_to_human intent work — and the AI cannot dial any other number, no matter what the caller asks.

curl -X PUT https://api.senderz.com/v1/ai/persona \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_default_language": "en",
    "voice_handoff_number": "+16195551234",
    "voice_greeting": "Hi, thanks for calling Bella Cafe. How can I help?"
  }'

voice_default_language accepts en, es-MX, or tr-TR. The AI auto-detects the caller’s language and switches mid-call regardless of the default.

Step 4: Assign the persona to the number

curl -X PATCH https://api.senderz.com/v1/voice/numbers/<number_id> \
  -H "Authorization: Bearer tf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_persona_id":"<persona_id>"}'

You can change the assignment any time — the next inbound call uses the new persona.

Step 5: Place a test call

Dial the number from any phone. You should hear:

  1. The TCPA recording disclosure (in the detected language).
  2. The persona greeting.
  3. A natural conversation. Try asking the AI for hours, to take a message, or to transfer you.

Within 30 seconds of hangup, your iPhone receives an iMessage with the caller’s number, the AI summary, the detected intent, and a lead score.

Common next steps