[Example] 021 — Twilio Voice Agent Telephony Integration (Node.js)

[github-actions]

New example: Twilio Voice + Deepgram Voice Agent — AI Phone Agent

Integration: Twilio Voice | Language: Node.js | Products: Voice Agent (STT + LLM + TTS)

What this shows

• Express server bridging Twilio Media Streams to Deepgram's Voice Agent WebSocket API (wss://agent.deepgram.com/v1/agent/converse)
• Bidirectional audio: caller speech → Deepgram STT → LLM → Deepgram TTS → caller
• Function calling (tool use) within the voice agent — demo "pizza shop" order status lookup
• Inbound call handling via TwiML webhook + outbound call initiation via Twilio REST API
• μ-law 8 kHz audio throughout — no server-side format conversion needed
• Barge-in support: clears Twilio audio buffer when the user interrupts the agent

Required secrets

• DEEPGRAM_API_KEY
• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER

Closes #26

---

Built by Engineer on 2026-04-01

[github-actions]

Code Review

Overall: APPROVED

Tests ran ✅

PASS: AGENT_SETTINGS has all required fields
PASS: check_order_status function returns expected shape
Downloading test audio...
Converting to mulaw 8 kHz mono...
Audio ready: 207466 bytes of mulaw 8 kHz
Server started on :3098
PASS: POST /voice returns TwiML with correct <Stream>
Streaming audio through server → Deepgram Agent (up to 45s)...
[agent] Connected to Deepgram Voice Agent
[agent] Settings applied
[assistant] Thanks for calling Deepgram Pizza! How can I help you today?
[user] Yeah. As as much as, um, it's worth
PASS: Voice Agent pipeline produced conversation text
All tests passed

Integration genuineness

Pass — Twilio SDK (twilio npm package) is imported and used for TwiML generation (twilio.twiml.VoiceResponse) and outbound calls (client.calls.create). Real WebSocket connection to wss://agent.deepgram.com/v1/agent/converse with live Deepgram API key. .env.example lists all four required credentials (DEEPGRAM_API_KEY, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER). Test exits with code 2 when credentials are missing.

Code quality

• Official Deepgram Voice Agent WebSocket API used — no raw HTTP to Deepgram
• No hardcoded credentials anywhere; all sourced from environment variables
• Error handling on all WebSocket events (open, message, error, close) for both Twilio and Agent connections
• Credential check runs first in src/index.js (line 91) before any SDK usage, and in tests/test.js (lines 9–20) before imports
• Clean WebSocket lifecycle: proper close propagation, keep-alive interval cleanup, media queue for pre-ready audio
• Barge-in support with Twilio clear event
• Function calling (tool use) properly implemented with FunctionCallRequest/FunctionCallResponse pattern

Documentation

• README includes "What you'll build" section, prerequisites, all env vars with console links, install/run instructions, outbound call usage, key parameters table, and architecture walkthrough
• .env.example present and complete with comments linking to each console

---

✓ All checks pass. Ready for merge.

---

Review by Lead on 2026-04-02