twilnyx 0.3.0

Proxy for TwiML to TeXML

Twilnyx

A proxy that redirects Twilio SDK calls to use Telnyx's API. Keep using your existing Twilio code and webhook server - just add two lines to use Telnyx instead!

Installation

pip install twilnyx

Usage

Your existing Twilio code:

from twilio.rest import Client

client = Client('TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN')

call = client.calls.create(
    url='https://your-server.com/voice',  # Your webhook server
    to='[phone]',
    from_='[phone]'
)

To use TeXML, just add:

# Add these two lines at the start of your code
import twilnyx
twilnyx.use_telnyx(debug=True)  # Set to True for detailed logging

# Then use your existing Twilio code as-is!
from twilio.rest import Client
...

TeXML Mode

This package uses TeXML exclusively for all requests. No Telnyx API credentials are required, as all requests are handled via TeXML responses.

# Simple usage with TeXML - loads full mappings by default
import twilnyx
twilnyx.use_telnyx()  # No credentials needed, supports all TwiML verbs

# Your existing Twilio code works as-is
from twilio.rest import Client
client = Client('TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN')

Custom Mappings

You can customize the parameter mappings and TeXML templates by providing your own JSON file:

import twilnyx

# Option 1: Load custom mappings at initialization
twilnyx.use_telnyx(custom_mappings_file='my_mappings.json')

# Option 2: Load custom mappings at any time
twilnyx.load_custom_mappings('my_mappings.json')

# View current mappings
print(twilnyx.MAPPINGS)

Example custom mappings file:

{
  "parameter_mappings": {
    "To": "destination",
    "From": "source",
    "Body": "message_content"
  },
  "texml_templates": {
    "call": {
      "element": "CustomDial",
      "attributes": ["callerId"],
      "children": [
        {
          "element": "Number",
          "content": "destination"
        }
      ]
    }
  }
}

Using All TwiML Verbs

The package includes a full mapping for all TwiML verbs and loads it by default. You can use any TwiML verb by specifying it in the 'verb' parameter:

import twilnyx

# Initialize Twilnyx - full mappings are loaded by default
twilnyx.use_telnyx(debug=True)

# Now you can use any TwiML verb by specifying it in the 'verb' parameter
from twilio.rest import Client
client = Client('TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN')

# Example: Gather DTMF input
call = client.calls.create(
    to='[phone]',
    from_='[phone]',
    verb='gather',  # Explicitly request Gather verb
    finish_on_key='#',
    num_digits=4,
    prompt_text='Please enter your PIN'
)

See the examples/all_verbs_example.py file for examples of using all supported TwiML verbs, including:

• <Connect>, <Dial>, <Enqueue>, <Gather>, <Hangup>, <Leave>
• <Pause>, <Play>, <Record>, <Redirect>, <Refer>
• <Reject>, <Say>, <Siprec>, <Stream>, <Transcription>

How It Works

1. Basic Flow:

   Your Code -> Twilio SDK -> Twilnyx Proxy -> TeXML Response
                                    |
                                    v
                             Parameter Mapping
                             TeXML Generation
   

2. Complete Flow:

   +-------------+    +------------+    +-------------+    +-----------+
   |  Your Code  |    |Twilio SDK |    |Twilnyx Proxy|    |   TeXML   |
   |             |--->|           |--->|             |--->| <Response>|
   +-------------+    +------------+    +-------------+    +-----------+
                                            |
                                            v
                                    +---------------+
                                    | Map Params    |
                                    | Generate XML  |
                                    +---------------+
   

3. TeXML Flow:

   +-------------+    +------------+    +-------------+    +-----------+
   |  Your App   |    |Twilio SDK |    |Twilnyx Proxy|    |   TeXML   |
   |client.calls |    |           |    |             |    | <Response>|
   |             |--->|           |--->|             |--->|  <Dial>   |
   |             |    |           |    |             |    |  <Number> |
   |             |    |           |    |             |    |  <Play>   |
   +-------------+    +------------+    +-------------+    +-----------+
   

4. SMS Flow with TeXML:

   +-------------+    +------------+    +-------------+    +-----------+
   |  Your Code  |    |Twilio SDK |    |Twilnyx Proxy|    |   TeXML   |
   |client.msgs  |--->|           |--->|             |--->| <Response>|
   +-------------+    +------------+    +-------------+    |   <Say>  |
                                                           +-----------+
   

5. Parameter Mapping:

   # Twilio format
   {
       'To': '[phone]',
       'From': '[phone]',
       'Url': 'https://your-server.com/voice',
       'MediaUrl': 'https://example.com/audio.mp3'  # Media URL for TeXML
   }
   
   # Converted to Telnyx format
   {
       'to': '[phone]',
       'from': '[phone]',
       'webhook_url': 'https://your-server.com/voice',
       'voice_profile_id': 'your_profile_id',  # Added automatically
       'media_urls': 'https://example.com/audio.mp3'  # Used for TeXML generation
   }
   

6. Response Conversion:

   # Telnyx response
   {
       'call_control_id': 'xyz',
       'state': 'ringing'
   }
   
   # Converted to Twilio format
   {
       'sid': 'xyz',
       'status': 'ringing'
   }
   

Required Setup

1. No Telnyx API Credentials Required:

   • This version uses TeXML exclusively
   • No API keys or credentials needed
   • Just import and use

2. TeXML Support:

   • All requests are converted to TeXML responses
   • Supports calls, messages, and media playback
   • Compatible with Telnyx's XML format

3. Usage with Existing Code:

   • Keep using your existing Twilio code
   • No changes needed to your application logic
   • Just add the twilnyx.use_telnyx() call

Features

• Uses your existing Twilio code
• Uses your existing webhook server
• No code changes needed
• Automatic parameter mapping
• Proper response conversion
• Detailed logging for debugging
• Support for calls and messages
• Error handling and reporting
• Complete TeXML support for all TwiML verbs:
  • <Connect>, <Dial>, <Enqueue>, <Gather>, <Hangup>, <Leave>
  • <Pause>, <Pay>, <Play>, <Record>, <Redirect>, <Refer>
  • <Reject>, <Say>, <Siprec>, <Stream>, <Transcription>

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License