RonanCodes/voice-telephony

Voice telephony: outbound AI calls

Give an app a real phone call: an AI assistant (e.g. "Saar") dials a user's number, talks, and you get live transcription + a summary. There are three viable paths; build a thin provider abstraction so an admin can switch between them.

The three paths (pick per cost / control)

| Path | Vendors / keys | Outbound call API | Best for | |---|---|---|---| | B. Telnyx-native | One (Telnyx KEY...) | POST /v2/texml/ai_calls/{texml_app_id} with {From, To, AIAssistantId} | Fewest moving parts, single vendor | | A. Vapi + Telnyx carrier | Vapi key + Telnyx key | POST api.vapi.ai/call with {assistantId, phoneNumberId, customer.number} | Best-documented live-transcription webhooks | | C. Vapi + Twilio carrier | Vapi key + Twilio SID/token | same as A, number imported from Twilio | If Twilio is already wired (e.g. WhatsApp) |

Cost: Vapi orchestration ~$0.05/min; "$0 with BYO key" means $0 markup, not $0 total (all-in ~$0.15-0.36/min with your own LLM/TTS/STT). Telnyx EU outbound is low single-digit cents/min, cheaper than Twilio.

The number reality (read first)

• A free Vapi number is US-only and cannot call internationally — useless for a +31 (Dutch) target.
• A Dutch (+31) number needs regulatory docs (company incorporation cert / KVK, proof of allocation, address proof; ~72h). Not same-day.
• Fastest same-day: buy a US or UK Telnyx number (instant, programmatic, low regulatory friction) as the From, enable the target country (NL) as a destination on an Outbound Voice Profile, and call. Swap to a real +31 caller-ID later once paperwork clears.

Path A: Vapi + Telnyx (recommended when you want live transcription)

# 1. Buy a US number on Telnyx (instant)
curl "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[features][]=voice" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
curl -X POST https://api.telnyx.com/v2/number_orders -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" -d '{"phone_numbers":[{"phone_number":"+1XXXXXXXXXX"}]}'
# 2. On Telnyx: an Outbound Voice Profile with the Netherlands enabled as a destination,
#    and add Vapi as a Connection (Connections & Applications). (Dashboard step.)
# 3. Store the Telnyx key as a Vapi credential, then import the number:
curl -X POST https://api.vapi.ai/phone-number -H "Authorization: Bearer $VAPI_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"telnyx","number":"+1XXXXXXXXXX","credentialId":"<telnyx-credential-uuid>","assistantId":"<assistant>","name":"Saar line"}'
# 4. Place the call (assistantOverrides + schedulePlan optional)
curl -X POST https://api.vapi.ai/call -H "Authorization: Bearer $VAPI_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistantId":"<assistant>","phoneNumberId":"<pn_id>","customer":{"number":"+31647305600"}}'

Schedule a future call: add "schedulePlan": { "earliestAt": "<iso>" }.

Live call webhooks (same serverUrl as web calls): transcript (live chunks), status-update (queued/ringing/in-progress/ended), end-of-call-report (summary + full transcript + recording URL). Drive the live-transcription panel + post-call summary off these.

SIP gotchas (only if using the BYO SIP-trunk path, provider: byo-phone-number): use Telnyx signaling IP addresses in gateways (FQDN sip.telnyx.com returns 400), and whitelist all Telnyx signaling IPs (else 401 on inbound).

Path B: Telnyx-native (fewest steps, one key)

curl -X POST https://api.telnyx.com/v2/texml/ai_calls/{texml_app_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"From":"+1XXXXXXXXXX","To":"+31647305600","AIAssistantId":"assistant-..."}'

Telnyx AI Assistants support Webhook tools, Handoff/Transfer, DTMF, and an MCP server. Weak spot: the real-time transcription webhook contract is less explicitly documented than Vapi's, so verify it in the AI Assistant settings before committing a live-transcript UI to Path B.

App-side: provider abstraction + admin switch

Build a calls provider interface so the app picks the path at runtime:

type CallProvider = "telnyx-native" | "vapi-telnyx" | "vapi-twilio";
async function placeCall(provider: CallProvider, to: string, opts): Promise<{id}> { /* dispatch */ }

Store the chosen provider in an admin setting; expose a small admin panel with the three options + a "Run & Talk" test. The assistant/tools layer stays the same across providers; only the carrier + call-placement call differs.

SMS from the same number (Telnyx Messaging)

Once you own a number, it can do SMS too — bill it as a second channel on the same line and route by destination country (mirror the call routing: +31 → your Telnyx number, else Twilio/other).

# 1. A messaging profile is REQUIRED and MUST list whitelisted destinations
#    (country codes) or creation 400s ("missing whitelisted destinations").
MPID=$(curl -s -X POST https://api.telnyx.com/v2/messaging_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"<app> NL","enabled":true,"whitelisted_destinations":["NL"]}' | jq -r .data.id)
# 2. Assign it to the number via the MESSAGING sub-resource (PATCH on the number
#    root with messaging_profile_id silently no-ops — use /messaging):
curl -X PATCH "https://api.telnyx.com/v2/phone_numbers/<NUM_ID>/messaging" \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d "{\"messaging_profile_id\":\"$MPID\"}"
# 3. Send: POST /v2/messages { from: <your E.164>, to, text }. data.id is the sid.

App side: a sendSmsTelnyx(to, body) (server-only fetch to /v2/messages) + route in your generic sendSMS: if countryFromPhone(to)==="NL" && telnyxConfigured() → Telnyx, else Twilio. Env: TELNYX_API_KEY, TELNYX_SMS_FROM=<E.164>.

Verified working (Makely, 2026-06-29 — +3197010285652)

The Vapi+Telnyx import is genuinely two API calls, no manual SIP trunk:

# a. register the Telnyx key as a Vapi credential
CRED=$(curl -s -X POST https://api.vapi.ai/credential -H "Authorization: Bearer $VAPI_PRIVATE_KEY" \
  -H "Content-Type: application/json" -d "{\"provider\":\"telnyx\",\"apiKey\":\"$TELNYX_API_KEY\"}" | jq -r .id)
# b. import the number — Vapi AUTO-CREATES the Telnyx voice connection on import
#    (the number's "Required for calls" warning clears itself; no dashboard step)
curl -s -X POST https://api.vapi.ai/phone-number -H "Authorization: Bearer $VAPI_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"provider\":\"telnyx\",\"number\":\"+31...\",\"credentialId\":\"$CRED\",\"name\":\"<app> NL\"}"
# → returns { id: <phoneNumberId>, status: "active" } → set VAPI_PHONE_NUMBER_ID_NL

Gotchas confirmed: (1) messaging-profile creation needs whitelisted_destinations; (2) assign the profile via /phone_numbers/{id}/messaging, not the number root; (3) the Vapi Telnyx import provisions the voice connection for you — don't hand-build a SIP trunk for this path; (4) route SMS + calls by destination country off one client-safe helper so adding a market is one edit.

Checklist

• [ ] Same-day test uses an instantly-provisioned US/UK number, NL enabled on the outbound profile; +31 caller-ID deferred to regulatory paperwork.
• [ ] Provider is switchable (admin setting), not hardcoded.
• [ ] Live transcription + summary driven off transcript / end-of-call-report (Path A) or the verified Telnyx event (Path B).
• [ ] Keys server-side only (TELNYX_API_KEY, VAPI_PRIVATE_KEY, TWILIO_*). No keys in client.

Sources

Vapi: docs.vapi.ai/api-reference/calls/create, /calls/outbound-calling, /free-telephony, /telnyx, /advanced/sip/telnyx, /advanced/sip/twilio, /server-url/events. Telnyx: developers.telnyx.com/docs/numbers/phone-numbers/buy-phone-number, /docs/inference/ai-assistants, support.telnyx.com NL DID requirements. Pricing: vapi.ai/pricing.