Voice channels — Twilio, Vapi, Sonetel

Beamdesk supports three voice providers: Twilio for PSTN calls, Vapi for AI voice with KB lookup, and Sonetel for international phone routing. Each provider integrates via webhook and follows the same persona, guardrails, and escalation rules as other channels.

During a call, AI retrieves knowledge snippets, generates responses, and uses text-to-speech to speak to the customer. When confidence is low or escalation triggers, the call is handed off to a human agent.

Twilio integration uses a webhook URL to receive call events, a configured account SID for authentication, and TwiML for call flow. Beamdesk generates AI responses and returns them as TwiML instructions for text-to-speech.

Twilio configuration in Beamdesk:
Provider: Twilio
Account SID: ACxxxxxxxxxxxxx
Auth Token: your_auth_token
Webhook URL: https://beamdesk.preview.softblaze.net/api/voice/twilio

Twilio number: +1-555-123-4567
Persona: Support
KB lookup: enabled
TTS voice: female
TTS language: en-US

Configure TwiML in your Beamdesk voice settings to control call flow: gather customer input with <Gather>, send transcription to Beamdesk webhook, and receive AI response as <Say>.

Vapi provides AI voice with built-in knowledge base lookup and function calling. Map Beamdesk personas to Vapi assistants, configure tool access, and set handoff triggers. Vapi handles ASR, TTS, and conversation context.

Vapi configuration in Beamdesk:
Provider: Vapi
API Key: sk-xxxxxxxxxxxxxxxxxx
Assistant ID: asst_xxxxxxxxxxxxxx
Webhook URL: https://beamdesk.preview.softblaze.net/api/voice/vapi

Persona mapping:
  - Support: asst_support_v3
  - Billing: asst_billing_v2
  - Tech: asst_tech_v4

Tool access:
  - get_customer
  - list_orders
  - check_refund_policy

Handoff conditions:
  - confidence < 0.7
  - refund request
  - angry sentiment
  - manual escalation request

Vapi assistants run on the Beamdesk persona system prompt. When a handoff triggers, Vapi transfers the call to a configured phone number or queues the call for agent pickup.

Sonetel provides PSTN routing with international numbers and local presence in multiple countries. Configure country-specific numbers, route calls to Beamdesk webhook, and use TTS for AI responses.

Sonetel configuration in Beamdesk:
Provider: Sonetel
API Key: sonetel_xxxxxxxxxxxxx
Webhook URL: https://beamdesk.preview.softblaze.net/api/voice/sonetel

Phone numbers:
  US: +1-800-555-0123
  UK: +44-20-7123-4567
  DE: +49-30-12345-67

Call routing:
  - By country: US → US support, UK → UK support
  - By time: after-hours → voicemail
  - By queue: billing → billing team
  - By escalation: high-risk → manager queue

Sonetel supports call recording, transcription, and analytics. Enable recording in Beamdesk settings for compliance and training.

When AI speaks during a call, it retrieves knowledge snippets and reads them to the customer. TTS citation mode announces when a response comes from a specific source: "According to our pricing page...".

KB lookup configuration:
Enable: true
Max snippets per turn: 3
Min confidence: 0.8
Citation mode: announce
  - template: "According to {{source}}, {{snippet}}"
  - voice: neutral

Example call flow:
Customer: "What's your refund policy?"
AI retrieves: [policy_kb_123, confidence: 0.92]
AI speaks: "According to our refund policy, you can request a refund within 30 days of purchase..."
TTS: "According to our refund policy, you can request a refund within thirty days of purchase..."

KB lookup improves accuracy for factual questions: pricing, SLA, features, and policy. For complex troubleshooting, AI may still need to hand off to a human.

Voice handoff transfers the call to a human agent when AI cannot resolve, confidence is low, or customer requests escalation. Configure handoff triggers per persona and per provider.

Handoff configuration:
Triggers:
  - confidence_below: 0.7
  - keywords: ['manager', 'supervisor', 'speak to human']
  - sentiment: angry
  - max_turns: 8

Handoff action:
  Twilio: transfer to +1-555-999-8888
  Vapi: transfer to assistant asst_human_escalation
  Sonetel: transfer to queue "human_support"

Customer notification:
  - Message: "Connecting you with a specialist..."
  - TTS: enabled
  - Music: hold_music.wav

During handoff, Beamdesk captures the full transcript and sends context to the receiving agent. The agent sees the AI's retrieved knowledge, draft responses, and escalation reason.

Test voice integration by calling your configured number from a phone. Verify that TTS sounds natural, KB lookup works for common questions, and handoff triggers correctly for escalation scenarios.

• Call a test number and ask a pricing question → verify KB lookup
• Ask for a refund → verify escalation triggers
• Request a manager → verify handoff to human
• Ask a complex technical question → verify TTS clarity
• Check transcript in Beamdesk for accuracy