feat: add Telnyx as telephony provider for voice assistants

[a692570]

Add Telnyx as a Telephony Provider Integration

Summary

This PR adds Telnyx as a telephony provider for the TEN Framework, enabling inbound and outbound voice calls via Telnyx SIP trunking. The integration follows the existing Twilio SIP pattern, providing a complete voice assistant pipeline (STT → LLM → TTS) over Telnyx's programmable voice infrastructure.

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update

Motivation and Context

Telnyx is a CPaaS provider offering SIP trunking, programmable voice, and AI voice capabilities. Adding Telnyx as a provider:

1. Expands telephony options for TEN Framework users
2. Provides an alternative to Twilio for users with existing Telnyx infrastructure
3. Supports the growing demand for multi-provider voice AI deployments
4. Maintains consistency with the existing extension architecture

How Has This Been Tested?

• Existing Twilio SIP integration tests adapted for Telnyx patterns
• Manual testing with Telnyx Mission Control Portal
• Integration with Deepgram (ASR), OpenAI (LLM), and ElevenLabs (TTS)

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing tests pass with my changes

Documentation

The README includes:

• Prerequisites (Telnyx, Deepgram, OpenAI, ElevenLabs credentials)
• Environment variable configuration
• Setup instructions
• API usage examples
• Configuration reference

Breaking Changes

None. This is an additive feature following existing patterns.

Related Issues

None.

Additional Context

This integration uses Telnyx's Media Streams feature for real-time audio processing, similar to Twilio's Media Streams API. The architecture consists of:

1. Python Extension (main_python): Handles call control, audio forwarding, and TEN Framework integration
2. FastAPI Server: Provides REST API for call management and WebSocket endpoint for media streams
3. Property Configuration: Maps Telnyx credentials to extension properties

The implementation leverages Telnyx's Python SDK for call management and their XML Connection API for establishing media streams.

Files Changed

ai_agents/agents/examples/voice-assistant-sip-telnyx/
├── Dockerfile
├── README.md
├── Taskfile.yml
├── Taskfile.docker.yml
├── ngrok.yml
├── start-with-ngrok.sh
├── frontend/           # Next.js frontend (copy from Twilio example)
├── server/             # Telnyx-specific server implementation
│   ├── main.py
│   ├── telnyx_server.py
│   └── requirements.txt
└── tenapp/             # TEN app with Telnyx extension
    ├── manifest.json
    ├── property.json
    ├── go.mod
    ├── main.go
    └── ten_packages/extension/main_python/
        ├── extension.py      # Telnyx-specific extension
        ├── config.py        # Telnyx configuration model
        ├── server.py        # Telnyx WebSocket server
        ├── manifest.json
        ├── property.json
        └── ...

Environment Variables

# Telnyx (required for call handling)
TELNYX_API_KEY=your_telnyx_api_key_here
TELNYX_CONNECTION_ID=your_telnyx_connection_id_here
TELNYX_FROM_NUMBER=+1234567890
TELNYX_PUBLIC_SERVER_URL=your-domain.com:9000

# Deepgram (required for speech-to-text)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI (required for language model)
OPENAI_API_KEY=your_openai_api_key_here

# ElevenLabs (required for text-to-speech)
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

[github-actions]

PR #2046 Code Review: Telnyx Telephony Provider Integration

Thank you for this comprehensive integration! The implementation follows the existing Twilio pattern well and provides a solid foundation. I've reviewed the code and have feedback across several areas.

---

✅ Strengths

Architecture & Code Quality:

• Excellent consistency with the Twilio SIP implementation - maintains architectural patterns
• Clean separation of concerns (extension.py, server.py, telnyx_server.py, config.py)
• Proper async/await usage throughout
• Good use of Pydantic models for configuration validation
• Comprehensive README with clear setup instructions

Documentation:

• Well-documented environment variables and prerequisites
• Clear API usage examples
• Good architectural overview in PR description

---

🔴 Critical Issues (Should Fix Before Merge)

1. CORS Misconfiguration (Security Risk)

Files: server/telnyx_server.py:255-260, tenapp/ten_packages/extension/main_python/server.py:36-39

Issue: allow_origins=["*"] with allow_credentials=True is a critical security vulnerability enabling CSRF attacks from any website.

Fix: Use allow_origins=[os.getenv("ALLOWED_ORIGINS", "http://localhost:3000").split(",")]

Note: This same issue exists in the Twilio implementation and should be fixed there as well.

---

2. Missing Webhook Signature Verification (Security Risk)

File: server/telnyx_server.py:240-260

Issue: Telnyx sends X-Telnyx-Signature-TL-Timestamp and X-Telnyx-Signature-TL-Body-SHA256 headers for webhook verification, but the code doesn't validate them. Anyone can send fake webhooks to your server.

Recommendation: Implement webhook signature verification using Telnyx's signing secret.

---

3. API Key Exposure in Logs

Issue: Config logging may expose API keys. Mask sensitive fields before logging.

---

4. Missing Input Validation on Phone Numbers

File: server/telnyx_server.py:103-113

Issue: Phone numbers are used directly in API calls without E.164 format validation.

---

🟡 High Priority Issues

5. Race Condition in Call Cleanup

Issue: No synchronization when accessing/modifying active_call_sessions dictionary. Use asyncio.Lock() to protect shared state.

---

6. Memory Leak - Audio Dump Files

Issue: Audio dump files in /tmp/telnyx_audio_dumps are only cleaned up on explicit call end. If a call crashes, files accumulate indefinitely.

Recommendation: Implement background cleanup task with TTL or disable audio dumps by default in production.

---

7. Unvalidated WebSocket Message Size

Issue: No max message size validation. Malicious clients could send massive messages causing server to hang or run out of memory.

---

8. Missing Required Configuration Validation

Issue: No validation that telnyx_from_number and telnyx_connection_id are non-empty before using them in API calls.

---

🟠 Medium Priority Issues

9. Code Duplication with Twilio

Audio processing methods (_downsample_audio, _dump_pcm_audio) are identical copies. Extract to shared utility module.

---

10. Hardcoded Magic Numbers

audio_frame.set_property_int("stream_id", 54321) should be configurable.

---

11. Inconsistent Error Responses

Some error responses return str(e), exposing internal error details to clients.

---

📋 Production Recommendations

1. Add Rate Limiting
2. Add API Authentication
3. Implement Webhook Signature Verification
4. Add Observability (metrics, tracing)
5. Add Health Checks
6. Disable Debug Features by default
7. Add Integration Tests with Telnyx sandbox

---

📝 Documentation Suggestions

1. Add security best practices section (webhook verification, CORS config, API auth)
2. Add troubleshooting section
3. Document production deployment considerations

---

Summary

This is a solid implementation that follows good patterns from the existing Twilio integration. The main concerns are security-related (CORS, webhook verification, input validation) which should be addressed before merging.

Recommendation: Address the critical security issues, then this is ready to merge. Medium/low priority issues can be addressed in follow-up PRs.

Great work on this integration! 🚀

[plutoless]

Thank you for the PR! merged.