Documentation

Connect Twilio to Open Voice Shield

One routing change per direction. Inbound: point the trunk's Origination URI, or your TwiML Dial, at sip.ovs.telecomsxchange.com port 5060, with your platform as the destination on the Network page. Outbound: send calls to the same ingress with the trunk's Termination SIP URI as the destination, and add the Network page's egress address to the trunk's IP Access Control List.

Before you start#

• An Open Voice Shield account. Signup is self-serve and starts you with US$5 of credit.
• A Twilio account with Elastic SIP Trunking or Programmable Voice. This guide covers both.
• For outbound calls, the public IP address your platform sends SIP from, the egress address after any NAT, not the one on its interface.
• Firewall: UDP or TCP 5060 to the ingress, and UDP 30000–40000 open in both directions for the RTP your media endpoints exchange with our relay. See the firewall rules.

One relay, two directions#

Open Voice Shield sits between Twilio and the rest of your platform, and each direction is one configuration. Inbound, a call from the PSTN reaches your Twilio number, Twilio sends it to the ingress, and we analyze it and relay it on to the destination you configure on the Network page: your application or switch. Outbound, your platform sends the call to the ingress, and we relay it on to Twilio for termination; Twilio must then accept calls arriving from our egress address, which the Network page shows you.

A platform built on Twilio gets fraud and route monitoring, sampled or full, in one routing change, without touching its application architecture.

Step 1: whitelist the sending addresses#

Open the Network page in the portal and add the addresses that will send SIP to the ingress as CIDR entries. The whitelist is the authentication: there are no credentials, and an INVITE from any other address is answered 403. For inbound calls that means Twilio's published signalling IP ranges for your region, taken from Twilio's current documentation. For outbound calls it means your own platform's public egress address (a single host is a /32).

Step 2: point inbound calls at the ingress#

On Elastic SIP Trunking, origination is where Twilio sends the calls your numbers receive. Point it at the ingress. The dialled number and caller ID pass through unchanged, and we relay each accepted call on to the destination you set on the Network page, your own platform.

Names follow Twilio's documentation. Consoles change, so check Twilio's current docs.

On Programmable Voice the same hop is one line of TwiML: your application answers the number and dials on through the ingress:

<Response>
  <Dial><Sip>sip:{number}@sip.ovs.telecomsxchange.com</Sip></Dial>
</Response>

• The INVITE must carry SDP, an early offer. An INVITE without SDP is answered 488.
• Offer G.711 (PCMU or PCMA) first, Twilio carries it, and leave secure media (SRTP) off towards the ingress: plain RTP. Anything else is relayed but produces no transcript and no verdict.
• Send no REGISTER at the ingress, it is answered 403. Calls are authorized by source IP alone.

Step 3: send outbound calls through the ingress#

Outbound is the mirror image: your platform routes its calls to sip.ovs.telecomsxchange.com:5060 over UDP or TCP, and the destination you set on the Network page becomes the trunk's Termination SIP URI, so each analyzed call is relayed on to Twilio for the PSTN. One more setting makes Twilio accept the hop: the trunk must allow calls from our egress address.

Names follow Twilio's documentation. Consoles change, so check Twilio's current docs.

Or route a sample#

You do not have to move all your traffic. Sampling is a supported pattern, and Twilio gives you two ways in. On trunking, origination takes several URIs: give the analyzed hop and a direct URI to your platform the same priority and split the weight between them. One call in ten through the ingress is a common start. In code, it is one if around the dial:

if random(10) = 1                # one call in ten takes the analyzed hop
  dial sip:{number}@sip.ovs.telecomsxchange.com
else
  dial {number}                  # your existing direct route

Both paths deliver the call: the analyzed share reaches the same destination through one extra hop, and every sampled call comes back with a recording, per-channel transcript and verdict.

Step 4: place a test call#

Send a real call through each direction you configured and keep both parties talking for at least 30 seconds. A leg that never speaks produces a one-sided transcript. After hang-up the call appears in Calls in the console with its recording, per-channel transcript and verdict, usually within a minute.

• Rejected 403? The source address is not whitelisted. Compare the sending address with the CIDR entries on the Network page.
• Rejected 488? The INVITE carried no SDP, or offered SRTP. Send an early offer as plain RTP.
• One-way audio? A firewall rule on UDP 30000–40000 between your media endpoints and the ingress, not a signalling problem.

Anything else: Troubleshooting lists every rejection code and the check that clears it.

Frequently asked questions#

Ready to try it? Create an account. Signup is self-serve and comes with US$5 of credit, enough to analyze your first test calls.