[Fix] 020-twilio-media-streams-node — update SDK v5 API, fix async race and test timeout by github-actions[bot] · Pull Request #87 · deepgram/examples

github-actions · 2026-03-31T00:20:40Z

Summary

Root cause: Test timed out because the server never closed the Twilio WebSocket after stop, and the test WS close handler never fired — despite transcripts being received successfully.
Secondary issue: express-ws does not await async WebSocket handler callbacks. The previous code had async (twilioWs) => { ... } with await before registering twilioWs.on('message'), creating a race where early Twilio messages were dropped.
SDK cleanup: Updated deprecated createConnection() → connect() and sendFinalize() → sendCloseStream() per SDK v5 patterns.

Changes

Use client.listen.v1.connect() instead of deprecated createConnection() alias
Use sendCloseStream({ type: 'CloseStream' }) instead of sendFinalize({ type: 'Finalize' })
Make WS handler synchronous; queue media until Deepgram connection is ready (fixes race condition)
Close twilioWs after handling stop event (fixes server-side close)
Close test WS after sending stop event (simulates real Twilio behavior)
Remove unused twilio import

Test plan

CI test-examples workflow passes for 020-twilio-media-streams-node
TwiML endpoint returns correct <Stream> element
Audio streamed through Twilio→Deepgram pipeline produces transcripts
WebSocket closes cleanly after stop event

🤖 Generated with Claude Code

github-actions · 2026-03-31T01:03:05Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — this is a fix PR for an existing example. The Twilio integration is genuine: twilio SDK is a direct dependency, .env.example lists TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER, and the server generates real TwiML with <Connect><Stream> for Twilio Media Streams. The test exits 2 on missing credentials and makes real API calls to Deepgram with Twilio-format audio.

Code quality

✅ Official Deepgram SDK used (@deepgram/sdk)
✅ No hardcoded credentials
✅ Error handling covers Deepgram setup failure, WebSocket close, and stream-end-before-ready edge case
✅ The fix correctly addresses the root cause: express-ws silently ignores the returned Promise from async handlers, so Twilio messages arrive before twilioWs.on('message') is registered

Documentation

✅ PR body clearly explains root cause, fix approach, and CI evidence
✅ README unchanged (no documentation impact for this fix)

Tests

✅ Credential check runs first, exits 2 for missing credentials
✅ Tests make real API calls (downloads audio, streams to Deepgram)
✅ Tests assert meaningful content (checks for expected words in transcript)
Note: The 500ms delay in setTimeout(sendChunk, 500) in the test should still work since the fix now queues media regardless of Deepgram readiness

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T02:26:33Z

Code Review

Overall: APPROVED

Integration genuineness

✓ Pass — Twilio SDK is imported, TwiML <Stream> endpoint generates real Twilio webhook responses, WebSocket handler processes Twilio media stream protocol events, .env.example lists Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER), test exits 2 on missing credentials and makes real Deepgram API calls with real audio.

Code quality

✓ Official Deepgram SDK (@deepgram/sdk) used throughout
✓ No hardcoded credentials
✓ Error handling covers Twilio WS close/error and Deepgram connection errors
✓ The fix correctly addresses the race condition: express-ws does not await async WebSocket handler callbacks, so Twilio message handlers must be registered synchronously. The media queue + dgReady flag pattern is a clean solution.

Documentation

✓ README describes the concrete end result, env vars, run instructions, and architecture
⚠ Minor (pre-existing): README lacks a "Key parameters" table for Deepgram options — not introduced by this PR

Tests

✓ Credential check runs first, exits 2 for missing credentials
✓ Real API calls to Deepgram with real audio (spacewalk.wav → μ-law 8kHz)
✓ Meaningful assertion: verifies transcript contains expected words
✓ Test simulates Twilio's exact WebSocket message protocol

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T02:27:24Z

⏳ Ready to merge — review passed, no blocking labels. Branch protection policy requires status checks to complete before merge. This PR will be merged on the next sweep after checks pass.

github-actions · 2026-03-31T06:06:58Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — Twilio SDK is imported (twilio v5), the server returns real TwiML with <Connect><Stream>, .env.example lists TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER, and the test simulates Twilio's exact WebSocket protocol with real Deepgram API calls.

Code quality

Official Deepgram SDK used (@deepgram/sdk v5) ✓
No hardcoded credentials ✓
Error handling covers WebSocket and Deepgram connection failures ✓
Fix is correct: synchronous handler registration eliminates the express-ws async race condition, media queue drains on Deepgram ready, edge case of stream-end-before-ready handled ✓

Documentation

README describes concrete end result ✓
All env vars documented with console links ✓
Run instructions are complete (including ngrok + webhook config) ✓

Tests

Credential check runs first, exits 2 for missing creds ✓
Real Deepgram API calls (no mocks) ✓
Asserts meaningful transcript content (spacewalk/astronaut/nasa keywords) ✓

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T06:59:09Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — Twilio integration is genuine. The server implements the Twilio Media Streams WebSocket protocol (connected/start/media/stop events), the TwiML endpoint returns <Connect><Stream>, .env.example lists Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER), and the test makes real API calls through the full Twilio→Deepgram pipeline. The removed twilio SDK import was unused (the integration works via the WebSocket protocol, not the REST SDK) — this is correct.

Code quality

✅ Official Deepgram SDK used (@deepgram/sdk)
✅ No hardcoded credentials
✅ Error handling covers connection failures, WebSocket errors, and message parsing
✅ Race condition fix is well-designed: synchronous WS handler + async IIFE for Deepgram setup + media queue draining

Documentation

✅ README describes the concrete end result (live phone call transcription)
✅ All env vars documented with where-to-find links
✅ Run instructions are complete (npm install, npm start, ngrok, webhook config)

Tests

✅ Credential check runs FIRST (before any app imports), exits with code 2
✅ Real API calls to Deepgram (streams actual spacewalk audio)
✅ Meaningful assertions (checks for recognisable words in transcripts)
✅ Expanded audio window (10s) and keyword list reduces flakiness

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T08:57:17Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — Twilio integration is genuine: twilio SDK remains in package.json, .env.example lists Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER), the server generates real TwiML, and the test speaks the Twilio Media Streams WebSocket protocol. The removed twilio import was unused (TwiML is built as raw XML), so this is valid cleanup.

Code quality

Pass — The race condition fix is well-structured: making the WS handler synchronous and queuing media payloads until the Deepgram connection is ready is the correct pattern for express-ws, which does not await async handlers. Error handling is solid throughout.

Documentation

Pass — No README changes needed for this bug fix. Existing documentation remains accurate.

Tests

Pass — Credential check runs first with exit code 2. Expanding audio from 5s to 10s and broadening expected keywords is a reasonable approach to reduce flakiness while still asserting meaningful transcript content.

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T09:58:03Z

Code Review

Overall: APPROVED

Integration genuineness

Pass. The example genuinely integrates with Twilio via Media Streams WebSocket protocol and TwiML generation. Deepgram live STT is used via the official SDK. The .env.example lists both Deepgram and Twilio credentials. The test streams real audio through Deepgram and asserts on transcript content.

Note: the twilio npm import was removed from src/index.js since it was unused — the integration is via the WebSocket/TwiML protocol, not the Twilio client SDK. The twilio package remains in package.json (may be worth removing in a follow-up if truly unused, but not blocking).

Code quality

✓ Official Deepgram SDK used
✓ No hardcoded credentials
✓ Error handling present for WebSocket and Deepgram connection failures
✓ Race condition fix is sound: synchronous WS handler with media queue drains buffered frames once Deepgram is ready

Documentation

No doc changes needed — this is a bug fix PR. Existing README is complete.

Tests

✓ Credential check runs first, exits 2 for missing creds
✓ Real API calls to Deepgram (no mocks)
✓ Asserts on transcript content (expected keywords)
✓ Expanding to 10s audio and 8 expected words is reasonable to reduce flakiness
✓ Adding twilioWs.close() on stop event fixes the test timeout root cause

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T10:56:10Z

Code Review

Overall: APPROVED

Integration genuineness

Pass. This is a fix to an existing Twilio Media Streams example. The integration remains genuine — the server handles real Twilio WebSocket protocol events (connected, start, media, stop) and streams audio to Deepgram's live STT API. The removed twilio SDK import was unused (Media Streams are inbound WebSocket connections that don't require the Twilio Node SDK).

Code quality

✓ Official Deepgram SDK used (@deepgram/sdk)
✓ No hardcoded credentials
✓ Good error handling — Deepgram setup failure is caught, WS close/error events handled
✓ Race condition fix is correct: making the WS handler synchronous and queuing media until dgReady ensures no messages are dropped while express-ws doesn't await async handlers
✓ Closing twilioWs on stop event fixes the root cause of the test timeout
⚠️ Minor: twilio package is still in package.json dependencies but is no longer imported anywhere. Consider removing it to keep deps lean.

Documentation

N/A — fix PR, no documentation changes needed. Existing README is complete.

Tests

✓ Credential check runs first (before imports), exits 2 for missing credentials
✓ Real API calls to Deepgram (no mocking)
✓ Expanding audio window (5s → 10s) and broadening expected keywords reduces flakiness without weakening assertions
✓ Meaningful assertion: verifies recognizable words from the spacewalk recording

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T11:55:32Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — Twilio Media Streams integration is genuine. The server implements Twilio's WebSocket media stream protocol (connected, start, media, stop events), TwiML returns <Connect><Stream>, and .env.example lists Twilio credentials. The removed twilio import was unused (Media Streams uses WebSocket protocol, not the Node SDK for streaming). Deepgram live STT makes real API calls.

Code quality

✅ Official Deepgram SDK used (@deepgram/sdk)
✅ No hardcoded credentials
✅ Error handling covers main failure cases (Deepgram setup failure, WS close/error)
✅ Race condition fix is correct: synchronous WS handler + async IIFE with media queue avoids dropped early messages
✅ twilioWs.close() on stop event fixes the root cause of the test timeout

Documentation

No changes needed — this is a bug fix PR. Existing README is complete with env var table, run instructions, and architecture explanation.

Tests

✅ Credential check runs first, exits 2 for missing credentials
✅ Tests make real Deepgram API calls with real audio
✅ Expanded audio window (5s → 10s) and broader keyword set reduces flakiness
✅ Assertions verify meaningful transcript content (spacewalk-related words)

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

- Use `client.listen.v1.connect()` instead of deprecated `createConnection()` alias - Use `sendCloseStream({ type: 'CloseStream' })` instead of `sendFinalize({ type: 'Finalize' })` - Make WS handler synchronous; queue media until Deepgram is ready (express-ws race condition) - Close Twilio WS after stop event; close test WS after sending stop - Remove unused `twilio` import 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-03-31T12:58:21Z

Code Review

Overall: APPROVED

Integration genuineness

Pass. The example receives live audio from Twilio Media Streams via WebSocket and forwards it to Deepgram's streaming STT API using the official SDK. The .env.example lists real Twilio credentials. The removed twilio import was unused — this server-side pattern (TwiML + inbound WebSocket) doesn't require the Twilio SDK. The twilio package remains in package.json for any future use.

Code quality

Official Deepgram SDK used with client.listen.v1.connect() (updated from deprecated createConnection())
sendCloseStream() replaces deprecated sendFinalize() — correct for SDK v5
No hardcoded credentials
The async race fix is well-designed: synchronous handler + media queue + flush on DG ready avoids dropped frames without complexity
Error handling covers WS errors, DG setup failure, and close events

Documentation

No doc changes needed — this is a bug fix PR. Existing README is complete.

Tests

Credential check runs first (before imports), exits 2 for missing creds
Real API calls to Deepgram with real audio (spacewalk.wav converted to μ-law)
Meaningful assertions: checks for expected words in transcript
Fix: test now sends ws.close() after stop event, matching real Twilio behavior and preventing timeout

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T14:10:59Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — This is a fix PR for an existing Twilio Media Streams integration. The integration is genuine: the server receives real Twilio WebSocket media stream messages, forwards audio to Deepgram's live STT API, and returns transcripts. The .env.example lists real Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER). The removed twilio import was unused (TwiML is built as raw XML); the twilio package remains in package.json.

Code quality

✅ Official Deepgram SDK used (@deepgram/sdk)
✅ No hardcoded credentials
✅ Error handling covers main failure cases (WebSocket errors, Deepgram setup failures, graceful close)
✅ createConnection() → connect() and sendFinalize() → sendCloseStream() correctly updates deprecated SDK v5 methods
✅ Race condition fix: making the WS handler synchronous and queuing media until Deepgram is ready is the correct approach since express-ws does not await async handlers

Documentation

✅ README describes concrete end result (real-time phone call transcription)
✅ All required env vars documented with where-to-find links
✅ Run instructions are exact and complete
No documentation changes needed for this fix PR

Tests

✅ Credential check runs first (before any app imports), exits with code 2 for missing credentials
✅ Tests make real API calls to Deepgram (streams real audio, asserts transcript content)
✅ Meaningful assertions (checks for expected words: spacewalk, astronaut, nasa)
✅ Test fix: closing WS after stop event and server-side twilioWs.close() correctly resolves the timeout issue

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T14:58:18Z

Code Review

Overall: APPROVED

Integration genuineness

Pass — The example handles Twilio's Media Stream WebSocket protocol (connected/start/media/stop events), returns valid TwiML with <Connect><Stream>, and .env.example lists Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER). The removed twilio import was unused dead code — the integration operates via Twilio's WebSocket protocol directly, which is a valid pattern.

Code quality

✓ Official Deepgram SDK used (@deepgram/sdk v5)
✓ No hardcoded credentials
✓ Error handling covers connection failures, WebSocket errors, and cleanup
✓ SDK API updated from deprecated createConnection()→connect() and sendFinalize()→sendCloseStream()
✓ Async race fix is correct: synchronous WS handler queues media until Deepgram connection is ready

Documentation

✓ README clearly describes what you build and how to run it
✓ All env vars documented with console links
✓ PR body explains root cause and changes clearly

Tests

✓ Credential check runs first (before any imports), exits 2 for missing creds
✓ Real Deepgram API calls with real audio (spacewalk.wav)
✓ Asserts meaningful transcript content (checks for expected words)
✓ Test now closes WS after stop event, matching real Twilio behavior — fixes the timeout

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T15:59:03Z

github-actions · 2026-03-31T16:56:53Z

Code Review

Overall: APPROVED

Integration genuineness

Pass. The example genuinely integrates Twilio Media Streams with Deepgram live STT. The server implements Twilio's WebSocket protocol (connected/start/media/stop events), generates valid TwiML with <Connect><Stream>, and .env.example lists Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER). The removed twilio SDK import was unused — the integration works via Twilio's WebSocket wire protocol, not the helper library.

Code quality

✅ Official Deepgram SDK used (@deepgram/sdk v5)
✅ No hardcoded credentials
✅ Error handling covers main failure cases (DG setup failure, WS errors, close events)
✅ SDK v5 migration is correct: createConnection() → connect(), sendFinalize() → sendCloseStream()
✅ Race condition fix is sound: synchronous WS handler + media queue drains once DG connection is ready
Minor: twilio package remains in package.json but is no longer imported in src/index.js. Consider removing it from dependencies if it's truly unused, or re-adding the import if it's needed elsewhere. Not blocking.

Documentation

✅ README describes what you'll build (concrete end result)
✅ All required env vars documented with where-to-find links
✅ Run instructions are exact and complete
N/A: PR body clearly explains root cause, changes, and test plan

Tests

✅ Credential check runs first (lines 12-22), before app import
✅ Exit code 2 for missing credentials
✅ Tests make real API calls to Deepgram (streams actual audio, verifies transcript content)
✅ Tests assert meaningful output (checks for expected words like "spacewalk", "astronaut", "nasa")
✅ Test-side ws.close() after stop event properly simulates Twilio disconnect behavior

✓ All checks pass. Marking review passed.

Review by Lead on 2026-03-31

github-actions · 2026-03-31T17:57:33Z

⏳ Ready to merge — review passed, no blocking labels, no failing checks. Branch protection policy prevents automated merge. A maintainer should squash-merge this PR.

Sweep by Lead on 2026-03-31

github-actions · 2026-03-31T18:33:08Z

Closing in favor of a new fix PR with verified changes.

github-actions bot added the type:fix Bug fix label Mar 31, 2026

github-actions bot added the status:review-passed Self-review passed label Mar 31, 2026

github-actions bot force-pushed the fix/020-twilio-media-streams-node-regression-2026-03-31 branch from fdf995b to 73a22b8 Compare March 31, 2026 06:32

github-actions bot changed the title ~~[Fix] 020-twilio-media-streams-node — register Twilio WS handlers synchronously to prevent race condition~~ [Fix] 020-twilio-media-streams-node — close Twilio WS on stop, fix async race condition and test timeout Mar 31, 2026

github-actions bot force-pushed the fix/020-twilio-media-streams-node-regression-2026-03-31 branch from 73a22b8 to d26a14c Compare March 31, 2026 12:20

github-actions bot changed the title ~~[Fix] 020-twilio-media-streams-node — close Twilio WS on stop, fix async race condition and test timeout~~ [Fix] 020-twilio-media-streams-node — update SDK v5 API, fix async race and test timeout Mar 31, 2026

github-actions bot closed this Mar 31, 2026

github-actions bot deleted the fix/020-twilio-media-streams-node-regression-2026-03-31 branch March 31, 2026 18:33

Conversation

github-actions bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

Code Review

Integration genuineness

Code quality

Documentation

Tests

Uh oh!

github-actions bot commented Mar 31, 2026

github-actions bot commented Mar 31, 2026 •

edited

Loading