Add Telnyx as an Upstream Carrier in dSIPRouter (Inbound + Outbound) with Failover

This hands-on guide walks you through configuring Telnyx as an upstream carrier in dSIPRouter. By the end, you'll have working inbound and outbound trunks with a failover pattern you can reuse for any carrier.

Prerequisites

• A running dSIPRouter installation (v0.74+)
• A Telnyx account with:
• At least one DID (phone number)
• A SIP Connection configured
• Your SIP credentials or IP authentication ready
• Access to the dSIPRouter web GUI

Part 1: Telnyx Portal Configuration

Before configuring dSIPRouter, ensure your Telnyx SIP Connection is set up correctly.

Step 1: Create a SIP Connection in Telnyx

1. Log into the Telnyx Mission Control Portal
2. Navigate to Voice → SIP Connections
3. Click Create SIP Connection
4. Configure the connection:
5. Connection Name: dSIPRouter-Primary
6. Connection Type: Credentials or IP Authentication (we'll cover both)

Option A: IP Authentication (Recommended for Production)

1. Select IP Authentication
2. Add your dSIPRouter public IP address
3. Note the SIP Server: sip.telnyx.com
4. Outbound calls will use port 5060 (UDP/TCP) or 5061 (TLS)

Option B: Credentials Authentication

1. Select Credentials
2. Create a username and password
3. Note these for dSIPRouter configuration:
4. Username: Your chosen username
5. Password: Your chosen password
6. SIP Server: sip.telnyx.com

Step 2: Assign DIDs to Your SIP Connection

1. Go to Numbers → My Numbers
2. Select the DID(s) you want to route to dSIPRouter
3. Click Edit and set the Connection to your new SIP Connection
4. Save changes

Part 2: Configure Telnyx Gateway in dSIPRouter

Now let's add Telnyx as a carrier gateway in dSIPRouter.

Step 3: Add the Carrier Gateway

1. Log into dSIPRouter GUI
2. Navigate to Carrier Groups & Gateways
3. Click Add Gateway
4. Fill in the gateway details:

Basic Settings:
| Field | Value |
|-------|-------|
| Name | Telnyx-Primary |
| IP Address/Hostname | sip.telnyx.com |
| Port | 5060 |
| Protocol | UDP (or TCP/TLS) |
| Enabled | Yes |

Authentication (if using Credentials):
| Field | Value |
|-------|-------|
| Auth Username | Your Telnyx SIP username |
| Auth Password | Your Telnyx SIP password |
| Auth Domain | sip.telnyx.com |

1. Click Save

Step 4: Create a Carrier Group

Carrier Groups allow you to organize gateways and implement failover.

1. Navigate to Carrier Groups & Gateways
2. Click Add Carrier Group
3. Configure:
4. Name: Telnyx-Group
5. Type: Carrier
6. Click Save
7. Edit the group and add Telnyx-Primary gateway to it

Part 3: Configure Inbound Routing

Set up dSIPRouter to receive calls from Telnyx.

Step 5: Add Inbound DID Mapping

1. Navigate to Inbound Mappings
2. Click Add Inbound Mapping
3. Configure the mapping:

Field	Value
DID	5551234567

The DID field accepts:
- The entire number (e.g., 5551234567 or 15551234567)
- The first part of a number for prefix matching (e.g., 555123 to match all DIDs starting with that prefix)

1. Click Save

Step 6: Configure Telnyx Inbound SIP Profile

In Telnyx, ensure calls are sent to dSIPRouter:

1. Go to your SIP Connection settings
2. Under Inbound, configure:
3. SIP URI: sip:yourdomain.com or your dSIPRouter IP
4. Primary IP: Your dSIPRouter public IP
5. Port: 5060

Part 4: Configure Outbound Routing

Set up dSIPRouter to send calls through Telnyx.

Step 7: Create Outbound Route

1. Navigate to Outbound Routes
2. Click Add Outbound Route
3. Configure:

Field	Value
Name	US-PSTN-Telnyx
Prefix	1 (for US/Canada)
Carrier Group	Telnyx-Group
Priority	1

For international routing, add another route:

Field	Value
Name	International-Telnyx
Prefix	`` (empty for catch-all)
Carrier Group	Telnyx-Group
Priority	10

1. Click Save

Step 8: Test Outbound Calls

1. From your PBX or SIP endpoint, dial an external number
2. Check the Kamailio logs for routing:

tail -f /var/log/kamailio/kamailio.log

Or use journalctl if using systemd:

journalctl -u kamailio -f

Part 5: Implement Failover

Here's where it gets interesting—setting up automatic failover to a backup carrier.

Step 9: Add a Secondary Gateway

First, add your backup carrier gateway (e.g., Telnyx secondary region or different provider):

1. Navigate to Carrier Groups & Gateways
2. Click Add Gateway
3. Configure your backup:

Field	Value
Name	Telnyx-Secondary
IP Address/Hostname	sip-west.telnyx.com (or backup provider)
Port	5060
Enabled	Yes

Step 10: Configure Gateway Priorities in Carrier Group

1. Edit your Telnyx-Group Carrier Group
2. Add both gateways with priorities:

Gateway	Priority	Weight
Telnyx-Primary	1	100
Telnyx-Secondary	2	100

How it works:
- Lower priority number = tried first
- If primary fails (timeout, 5xx error), secondary is attempted
- Weight distributes load among gateways with same priority

Part 6: Common Gotchas & Troubleshooting

DID Format Issues

Problem: Inbound calls not matching your DID rules.

Solution: Telnyx sends DIDs in E.164 format (+15551234567). Make sure your inbound mapping matches the format Telnyx sends. You may need to include or exclude the country code depending on how Telnyx formats the number.

Codec Mismatch

Problem: One-way audio or call quality issues.

Solution: Ensure codec alignment:

1. In Telnyx Portal → SIP Connection → Codecs
2. Order codecs by preference:
3. G.711 µ-law (PCMU)
4. G.711 A-law (PCMA)
5. G.729 (if licensed)

6. Opus (for WebRTC)

7. In dSIPRouter, ensure your PBX/endpoints support these codecs

SIP Authentication Failures

Problem: 401/407 errors in logs.

Solutions:
1. Verify credentials are correct
2. Check Auth Domain matches Telnyx requirements
3. Ensure IP is whitelisted in Telnyx if using IP auth

NAT/Firewall Issues

Problem: Calls connect but drop after 30 seconds.

Solution:
1. Enable SIP ALG bypass on your firewall
2. Ensure RTP ports are open (10000-20000 UDP)
3. Verify NAT settings in dSIPRouter configuration

Failover Not Working

Problem: Calls fail instead of trying secondary gateway.

Solutions:
1. Check gateway priorities (lower = tried first)
2. Verify secondary gateway is enabled
3. Check failover timeout settings
4. Review logs for specific error codes

Quick Reference: Telnyx SIP Settings

Setting	Value
Primary SIP Server	sip.telnyx.com
Ports	5060 (UDP/TCP), 5061 (TLS)
Codec Support	G.711, G.729, Opus
DID Format	E.164 (+15551234567)
DTMF	RFC 2833 (default)

Reusable Failover Pattern

Here's a pattern you can apply to any carrier pair:

1. Create two gateways: Primary and Secondary
2. Add both to one Carrier Group with different priorities
3. Point your Outbound Routes to the Carrier Group (not individual gateways)
4. Test failover by temporarily disabling the primary gateway

This pattern works for:
- Multi-region redundancy (US-East + US-West)
- Multi-provider failover (Telnyx + Twilio)
- Cost-based routing with fallback

Summary

You now have:
- ✅ Telnyx configured as an upstream carrier
- ✅ Inbound routing for your DIDs
- ✅ Outbound routing through Telnyx
- ✅ Automatic failover to a secondary gateway

Next Steps

• Set up monitoring and alerting for gateway health
• Configure rate limiting to prevent toll fraud
• Add more carriers to your failover chain

---

This is part of the dSIPRouter Tuesday series. Have questions? Join our community!