WIP - Add Telnyx voice provider by whoiskatrin · Pull Request #1461 · cloudflare/agents

whoiskatrin · 2026-05-04T20:30:25Z

Summary

Adds first-class Telnyx support for the Cloudflare voice pipeline, addressing #1367.

This PR introduces a new @cloudflare/voice-telnyx provider package under voice-providers/telnyx and a phone/PSTN-focused examples/telnyx-voice-agent app that demonstrates the browser-side Telnyx WebRTC bridge model.

What changed

`@cloudflare/voice-telnyx`

Adds a Telnyx provider package following the existing voice-providers/* conventions.
Supports subpath imports so users can import only what they need:
- @cloudflare/voice-telnyx
- @cloudflare/voice-telnyx/stt
- @cloudflare/voice-telnyx/tts
- @cloudflare/voice-telnyx/telephony
Ports Telnyx STT support implementing Transcriber / TranscriberSession:
- Workers fetch-upgrade WebSocket connection
- 16 kHz mono PCM16 streaming
- WAV header emission for Telnyx's streaming API
- interim and final transcript callbacks
Ports Telnyx TTS support implementing TTSProvider and StreamingTTSProvider:
- REST backend by default
- Workers-only WebSocket streaming backend
Adds Telnyx telephony helpers:
- TelnyxCallBridge
- TelnyxPhoneTransport
- TelnyxPhoneClient
- TelnyxJWTEndpoint
- createTelnyxVoiceConfig
Keeps STT/TTS subpaths independent from telephony imports.
Adds README docs covering environment variables, subpath imports, browser voice usage, and PSTN/telephony setup.

Example app

Adds examples/telnyx-voice-agent, focused on the phone/PSTN path:
- phone call → Telnyx WebRTC bridge in the browser
- browser bridge → Cloudflare Agent WebSocket
- Telnyx STT → Workers AI LLM → Telnyx TTS
- response audio injected back into the same phone call
Uses createTelnyxVoiceConfig and TelnyxPhoneClient from @cloudflare/voice-telnyx/telephony.
Uses the browser as a control panel/WebRTC bridge, not as a microphone/speaker voice demo.
Includes .env.example with:
- TELNYX_API_KEY
- TELNYX_CREDENTIAL_CONNECTION_ID
Documents the local-demo JWT endpoint and calls out replacing allowUnauthenticated: true with an authorize() callback in production.

Attribution / dependency metadata

Adds @telnyx/webrtc for telephony support.
Updates NOTICE to document that parts of this provider are adapted from Telnyx's @telnyx/voice-cloudflare package, whose npm metadata declares MIT licensing.

Validation

Passed:

npm run build -w @cloudflare/voice-telnyx
npm run build -w @cloudflare/agents-telnyx-voice-agent
npm run check

npm run check reports existing sherif warnings for unrelated workspace paths without package.json, then completes successfully: export checks, formatting, oxlint, and all 82 TypeScript projects pass.

Notes for reviewers

The example now intentionally demonstrates the provider's distinctive phone/PSTN bridge value instead of a browser microphone/speaker STT/TTS flow.
The phone example leaves the voice agent's default declared audio format in place because TelnyxTTS currently returns MP3 by default and TelnyxPhoneClient can decode non-PCM server audio before playing into the phone bridge.
For production, the JWT endpoint should use an authorize() callback instead of allowUnauthenticated: true.

Refs #1367

changeset-bot · 2026-05-04T20:30:31Z

🦋 Changeset detected

Latest commit: 69870fb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

pkg-pr-new · 2026-05-04T21:20:34Z

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1461

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1461

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1461

hono-agents

npm i https://pkg.pr.new/hono-agents@1461

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1461

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1461

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1461

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1461

commit: 69870fb

Oliver-Zimmerman

Nice port overall — I think you’ve preserved the core architecture well, especially the split between STT/TTS/telephony and the browser-side PSTN bridge model. My main ask would be to swap the example for one that better shows the real value of the provider: the current example reads mostly like a browser STT/TTS demo, while the distinctive bit here is the phone/PSTN path. I’d suggest porting one of the original phone/hybrid examples instead, e.g. examples/phone-voice-agent: https://github.com/team-telnyx/voice-cloudflare/tree/main/examples/phone-voice-agent”

Oliver-Zimmerman · 2026-05-11T10:52:59Z

Hey @whoiskatrin any update on this?

cjol · 2026-05-18T08:10:30Z

@Oliver-Zimmerman I've picked this up and ported over the tests for future maintenance. At first glance the new example works but I wasn't able to verify the phone call working -- possibly because I've only got a freemium account. Could you validate from your side?

Oliver-Zimmerman · 2026-05-18T15:03:49Z

@cjol I just tested, it is working as expected. I was able to call the genCred and have a conversation, the transcript was present.

devin-ai-integration

Devin Review found 1 new potential issue.

View 11 additional findings in Devin Review.

devin-ai-integration · 2026-05-19T11:12:48Z

+import { streamText } from "ai";
+import { createWorkersAI } from "workers-ai-provider";
+
+const VoiceAgent = withVoice(Agent);


🔴 Example server sends MP3 audio instead of required pcm16 for phone bridge

The example's withVoice(Agent) call at examples/telnyx-voice-agent/src/server.ts:8 does not pass { audioFormat: "pcm16" } as the second argument. The voice pipeline defaults to audioFormat: "mp3" (see packages/voice/src/voice.ts:540), so the server will send MP3-encoded audio to the client. The TelnyxPhoneClient and TelnyxCallBridge.playAudio() expect 16kHz mono Int16 LE PCM — when MP3 arrives, it falls through to decodeAndPlay() which uses AudioContext.decodeAudioData(). This path adds latency, may fail on streaming chunks if the websocket TTS backend is used, and creates an AudioContext at 16kHz that might not decode MP3 correctly. The package's own README explicitly documents this: "Configure your server agent with withVoice(Agent, { audioFormat: "pcm16" }) when routing agent responses to Telnyx PSTN through the bridge."

Suggested change

const VoiceAgent = withVoice(Agent);

const VoiceAgent = withVoice(Agent, { audioFormat: "pcm16" });

Was this helpful? React with 👍 or 👎 to provide feedback.

Add Telnyx voice provider

d3f7168

whoiskatrin added 2 commits May 4, 2026 21:34

Fix npm ci lockfile sync

1485849

Add empty changeset for Telnyx provider

3033f5d

This comment was marked as resolved.

Sign in to view

whoiskatrin added 3 commits May 4, 2026 21:46

Address Telnyx provider review feedback

cfc3c43

Add Tailwind Linux native binding to lockfile

cd451b6

Fix Telnyx example typecheck

decfb0d

This comment was marked as resolved.

Sign in to view

whoiskatrin and others added 2 commits May 4, 2026 22:09

Update voice-providers/telnyx/src/transport/phone-transport.ts

a5c0ab1

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Normalize Telnyx lockfile updates

994f090

whoiskatrin mentioned this pull request May 4, 2026

Add Telnyx as a voice provider (STT, TTS, telephony adapter) #1367

Open

whoiskatrin changed the title ~~Add Telnyx voice provider~~ WIP - Add Telnyx voice provider May 6, 2026

Oliver-Zimmerman reviewed May 6, 2026

View reviewed changes

Refocus Telnyx example on phone bridge

96ff3b3

threepointone assigned cjol May 14, 2026

cjol and others added 4 commits May 15, 2026 10:16

Merge branch 'main' into feat/telnyx-voice-provider

728a691

dependency version pinning

7a28a78

port telnyx tests

a93cf31

Merge branch 'main' into feat/telnyx-voice-provider

69870fb

cjol approved these changes May 19, 2026

View reviewed changes

cjol marked this pull request as ready for review May 19, 2026 11:06

devin-ai-integration Bot reviewed May 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP - Add Telnyx voice provider#1461

WIP - Add Telnyx voice provider#1461
whoiskatrin wants to merge 13 commits into
mainfrom
feat/telnyx-voice-provider

whoiskatrin commented May 4, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 4, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

pkg-pr-new Bot commented May 4, 2026 •

edited

Loading

Uh oh!

Oliver-Zimmerman left a comment

Uh oh!

Oliver-Zimmerman commented May 11, 2026

Uh oh!

cjol commented May 18, 2026

Uh oh!

Oliver-Zimmerman commented May 18, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	const VoiceAgent = withVoice(Agent);
	const VoiceAgent = withVoice(Agent, { audioFormat: "pcm16" });

Conversation

whoiskatrin commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

@cloudflare/voice-telnyx

Example app

Attribution / dependency metadata

Validation

Notes for reviewers

Uh oh!

changeset-bot Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

pkg-pr-new Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Oliver-Zimmerman left a comment

Choose a reason for hiding this comment

Uh oh!

Oliver-Zimmerman commented May 11, 2026

Uh oh!

cjol commented May 18, 2026

Uh oh!

Oliver-Zimmerman commented May 18, 2026

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

whoiskatrin commented May 4, 2026 •

edited

Loading

`@cloudflare/voice-telnyx`

changeset-bot Bot commented May 4, 2026 •

edited

Loading

pkg-pr-new Bot commented May 4, 2026 •

edited

Loading