All integration guides
Connect Telnyx to TelecomsXchange
In short: Telnyx isn't a switch you point at TelecomsXchange as a trunk. To buy, dial sip:TECH_PREFIX%23NUMBER@sip01.telecomsxchange.com from TeXML <Dial><Sip> or the Call Control dial command, with the account's VoIP login and password as the SIP credentials. To receive TelecomsXchange phone numbers, give a Telnyx IP or FQDN connection a SIP subdomain that accepts calls from anyone, and set it as the number's SIP endpoint.
Telnyx to a purchased route
- Your Telnyx appTeXML or Call Control, with SIP credentials
- then, 80039%23447700900123, TelecomsXchangesip01, UDP 5060, digest auth
- Seller's routeThe route you purchased
On this page
Telnyx is a CPaaS carrier, not a switch you configure as a trunk to TelecomsXchange. You can combine them in two ways: your Telnyx voice application dials a purchased TelecomsXchange route as a SIP URI, and TelecomsXchange delivers phone numbers you bought to a Telnyx SIP connection. For every TelecomsXchange value in one place, see Connect a SIP platform.
Warning
TelecomsXchange does not accept SIP REGISTER. Telnyx reaches it with a plain INVITE and digest authentication on the INVITE, using the account's VoIP login and password. Don't authorise Telnyx's shared IP ranges on your account.
Before you start#
- A SIP account on TelecomsXchange with a VoIP login and password: Edit Account → Add SIP Digest Auth.
- A purchased route and its tech prefix from My Interconnections, for example
80039#. - A Telnyx TeXML application or Call Control application handling your calls.
- For numbers: a phone number bought on TelecomsXchange, and a Telnyx IP or FQDN connection pointing at your own PBX.
How do I send calls to TelecomsXchange?#
Put the tech prefix in front of the E.164 number and write # as %23 in the SIP URI.
With TeXML, return a <Dial> with a <Sip> noun:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial callerId="+14155550100">
<!-- TECH_PREFIX 80039# written as 80039%23, then the E.164 number without + -->
<Sip username="VOIP_LOGIN" password="VOIP_PASSWORD">sip:80039%23447700900123@sip01.telecomsxchange.com:5060</Sip>
</Dial>
</Response>The <Dial> verb's sipRegion attribute picks the Telnyx region that sends the call (US by default, or Europe, Canada, Australia, Middle East).
With Call Control, dial the URI and pass the credentials:
curl -X POST https://api.telnyx.com/v2/calls \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connection_id": "YOUR_CALL_CONTROL_APP_ID",
"to": "sip:80039%23447700900123@sip01.telecomsxchange.com:5060",
"from": "+14155550100",
"sip_auth_username": "VOIP_LOGIN",
"sip_auth_password": "VOIP_PASSWORD",
"sip_transport_protocol": "UDP"
}'VOIP_LOGIN and VOIP_PASSWORD are the VoIP Login and VoIP Password from Edit Account; Telnyx uses them to answer TelecomsXchange's 401 or 407 challenge. In your application, build the URI from the dialled number: strip + or 00, then prepend TECH_PREFIX with # encoded as %23. Telnyx bills its own leg on top of the TelecomsXchange route price.
Tip
Dial a routing group prefix such as 444101%23 to let TelecomsXchange pick the route, so your application doesn't need a prefix per destination.
How do I receive calls on numbers I bought?#
TelecomsXchange delivers each number to its SIP endpoint from 174.136.44.213. Telnyx can accept SIP URI calls on a connection and pass them on to the PBX behind it.
- In the Telnyx Portal, open your IP or FQDN SIP connection.
- In its inbound settings, set a SIP Subdomain, for example
yourco, so the connection answers atyourco.sip.telnyx.com. - Set Receive SIP Subdomain Calls to From anyone. TelecomsXchange is outside your Telnyx account, so Only my connections would reject it.
- On TelecomsXchange, open the number's DID Settings and set SIP Endpoint (Primary) to:
sip:14165551234@yourco.sip.telnyx.com:5060Telnyx routes the call to the connection by subdomain and doesn't check the user part. Place a test call to see how the number reaches your PBX, and adjust the connection's Number Format (DNIS / ANI) or your PBX's inbound rule if needed. SIP subdomains don't accept TLS, which matches TelecomsXchange's UDP delivery.
A credential connection works too: turn on Receive SIP URI Calls with the Unrestricted setting and use sip:yourusername@sip.telnyx.com:5060 as the endpoint. The call then rings the device registered to that connection. Telnyx may bill SIP URI calls from outside your account.
Warning
From anyone and Unrestricted accept SIP from the whole internet, not just 174.136.44.213. Filter on your PBX: accept only the numbers you own.
Can TelecomsXchange send calls to Telnyx as a seller route?#
Not covered here. A Telnyx connection carries your own traffic; reselling it as a wholesale route on TelecomsXchange depends on Telnyx's terms.
How do I test it?#
- Trigger your TeXML or Call Control application, for example by calling your Telnyx number.
- In the Telnyx Portal, open the call in the debugging or call logs view and check the SIP URI dialled and the response code.
- On TelecomsXchange, watch the call in Live Calls and find its SIP code in Logs → CDR (Voice).
- For numbers, call the TelecomsXchange number and check that the call reaches the Telnyx connection and your PBX.
What if something goes wrong?#
| You see | What to do |
|---|---|
| 401 or 407 in the Telnyx logs | Wrong username/password (TeXML) or sip_auth_username/sip_auth_password (Call Control), or digest auth isn't on the account. Copy them again from Edit Account. |
| 403 Forbidden | No valid credentials, or the account is blocked or out of balance. Telnyx's source IP is never authorised on its own. |
| 404 Not Found | Missing or wrong tech prefix, a raw # in the URI, or + left in the number. Use 80039%23 followed by the E.164 number. |
| 408 Request Timeout, or no answer | Telnyx couldn't reach sip01. Check the URI host and port, and use UDP. |
| 503 Service Unavailable | The route is blocked or failed on the seller's side. Check My Interconnections; try another route or a routing group. |
| One-way or no audio | Codec mismatch: TelecomsXchange doesn't transcode, so the route must accept a codec Telnyx offers, such as G.711. |
| Number calls rejected by Telnyx with 403 | Receive SIP Subdomain Calls is Only my connections, or SIP URI calling is disabled. Telnyx reports this as D30 in its response codes. |
| Number calls never arrive | The SIP endpoint on the number has a typo in the subdomain, or the Telnyx connection can't reach your PBX. |
References#
Common questions
Can Telnyx register to TelecomsXchange?
No. TelecomsXchange is peering only and does not accept REGISTER. Telnyx sends an INVITE to the SIP URI and answers the digest challenge with the credentials you pass.
Can I authorise Telnyx's IP addresses on my account instead?
Don't. Telnyx's signalling addresses are shared by all Telnyx customers, so authorising them would let others send calls on your account. Use digest credentials.
Why is the # written as %23?
A raw # isn't allowed in the user part of a SIP URI, so the tech prefix 80039# is written 80039%23 in the URI. It is the same character once decoded.
Can I sell Telnyx termination on TelecomsXchange?
This guide doesn't cover it. Pointing a TelecomsXchange seller route at your Telnyx connection would resell Telnyx termination; check Telnyx's terms first.
- Can Telnyx register to TelecomsXchange?
- No. TelecomsXchange is peering only and does not accept REGISTER. Telnyx sends an INVITE to the SIP URI and answers the digest challenge with the credentials you pass.
- Can I authorise Telnyx's IP addresses on my account instead?
- Don't. Telnyx's signalling addresses are shared by all Telnyx customers, so authorising them would let others send calls on your account. Use digest credentials.
- Why is the # written as %23?
- A raw # isn't allowed in the user part of a SIP URI, so the tech prefix 80039# is written 80039%23 in the URI. It is the same character once decoded.
- Can I sell Telnyx termination on TelecomsXchange?
- This guide doesn't cover it. Pointing a TelecomsXchange seller route at your Telnyx connection would resell Telnyx termination; check Telnyx's terms first.
Finished this guide?
This guide matches platform build 83b4ebc9. Markdown version.