Documentation

SIP integration

Point an IP-authenticated SIP trunk at the ingress host shown on your account, port 5060 over UDP or TCP, with no registration and no credentials, offering G.711 in the initial INVITE. Open Voice Shield authorizes the call by source IP, anchors the media so the audio can be recorded, and relays the INVITE on to a destination you configure — your own SBC, PBX or carrier.

The shape of the connection#

Open Voice Shield is a SIP proxy in the path of calls you choose to send through it. Your switch sends an INVITE to our ingress; we check the source address, anchor the media, and forward the same call to a destination you have configured. There is no B2BUA, no media injection and no re-origination — the far end sees your call, not ours.

• Signalling is a normal SIP hop. Your dialed number, your caller ID, your headers.
• Media is relayed through us in both directions, which is what makes the recording possible.
• The final response your switch sees is the far end's own response, unless we refused the call ourselves — see what your switch gets back.

Where to send the INVITE#

The ingress address is per account. Read it from the Network page in the portal, or from the API:

API=https://your-ovs-host.example

curl -s $API/api/customer/network-info -H "Authorization: Bearer $TOKEN"
# {"ingress_host":"192.0.2.10","ingress_port":5060,"transports":["udp","tcp"]}

The same host is the source address of everything we send onward, so your destination has to trust it. TCP is the safer choice when your INVITEs carry large SDP.

Authentication is by source IP#

There is no SIP account, no password and no registrar. A REGISTER is answered 403 Registration Not Supported. An INVITE is accepted only when its source address falls inside a CIDR entry on your whitelist, so add the public address your switch sends from — the address after NAT, not the private one on its interface.

Trunk settings to enter on your switch#

Every switch calls these something different — peer, trunk, carrier, gateway, endpoint. The settings are the same. Create an IP-authenticated entry with no registration and route the traffic you want analyzed through it.

Firewall, both directions#

Signalling and media use different ports and the media leg is the one people forget. Media is plain RTP on a UDP range at the ingress address — 30000–40000 unless your operator tells you otherwise.

If the destination is your own SBC or PBX, add the ingress host to its trusted peers or ACL before the first test call. Being rejected by your own equipment is the single most common first-call failure.

Codecs and media#

The ingress does not transcode. Whatever your switch and the far end agree on is what gets relayed — and what gets recorded.

The media is anchored: the SDP your switch receives points at the ingress media address, in both directions, for the whole call. ICE is stripped, the origin and connection lines are rewritten, and the audio is captured while it is relayed. Nothing is injected into the audio and neither party hears anything added.

Where the call goes next#

A destination is a host, port and transport we relay the accepted call to — your SBC, PBX or carrier. Up to 20 per account, with udp, tcp or tls outward, independent of the transport you use towards us.

The destination for a given call is chosen in this order, first match wins:

1. an active divert control on the caller's ANI, placed by one of your automation rules;
2. a routing rule whose prefix is the longest leading match of the dialed number;
3. the destination attached to the whitelist entry that matched the source IP;
4. your default destination;
5. failing all of those, back to the source address on 5060/udp.

Prefix routing#

A routing rule maps a leading digit string on the dialed number to one of your destinations. Use it to send a test range, a country, or a voice-agent number somewhere other than the default while everything else follows the normal path.

curl -s -X POST $API/api/customer/routing-rules \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"prefix":"1800","destination_id":"<destination id>","priority":100,"label":"toll-free to SBC B"}'

Tech prefix#

Carriers that identify a trunk by a leading digit string want that string on the number they receive, not on the number you dial. Set tech_prefix on the destination and we prepend it to the Request-URI user before relaying: dialling 15551234567 through a destination with tech prefix 009 leaves us as 00915551234567.

• Characters 0-9, * and # only, up to 32 of them.
• It is a property of the destination, so every call routed there gets it.
• The call record keeps both the dialed number and the prefix that was applied.
• Clear it by sending an empty value.

Carrying your own reference on the call#

Two SIP headers on the initial INVITE are captured and stored on the call record, so a verdict can be joined back to the campaign, agent or ticket that produced it: X-Customer-ID and X-Customer-Name. Values are trimmed to 256 characters and appear as external_id and external_name on the call. The captured set is a platform setting — ask your operator if you need different headers.

What your switch gets back#

If we refuse the call, the response comes from us and comes fast, before any INVITE is sent onward. If we accept it, everything your switch sees after that — 180, 183, 200, a busy, a rejection — is the far end's own response, relayed unchanged.

A malformed request is dropped without a reply. A retransmitted INVITE — same Call-ID and same From-tag — gets the answer already given to the original and does not consume a second port or a second balance check.

How a call ends#

A BYE from either side ends the call normally and is relayed. Two limits can also end it from our side, and both send BYE to both parties:

Run a test call#

1. OPTIONS. Send SIP OPTIONS from the switch to sip:ping@<ingress_host>:5060. A 200 OK proves the path and the port.
2. Confirm the source address. Place one call and, if it is rejected 403, compare the address in your own SIP trace with the CIDR entries on the account.
3. Place a real call over the new route with at least 30 seconds of two-way speech, and talk on both legs — a leg that never speaks produces a one-sided transcript.
4. Check the media. Both parties should have audio in both directions. One-way audio is a firewall rule on the RTP range, not a signalling problem.
5. Read the call record a minute after hang-up: the dialed number, the destination that was chosen, the route prefix and tech prefix applied, the SIP log and the verdict are all on it.

curl -s "$API/api/calls?limit=1" -H "Authorization: Bearer $TOKEN"
# {"total":1,"items":[{"id":"...","ani":"15550001111","dialed":"15551234567",
#   "dest_host":"203.0.113.10","dest_port":5060,"dest_transport":"udp",
#   "route_prefix":"1800","dest_tech_prefix":null,"status":"completed",
#   "sip_code":200,"end_reason":"bye","billsec":42,"analysis_status":"done"}]}

Before you send production traffic#

• The public egress address of every switch that will send to us is whitelisted.
• The ingress host is a trusted peer on your destination, for SIP and for RTP.
• UDP 30000–40000 is open outbound and inbound between you and the ingress.
• The trunk offers PCMA and PCMU, sends SDP in the INVITE, and does not register.
• A default destination exists, and any prefix rule you added resolves to the right one.
• The account has credit, and the plan has enough ports for your busy hour.
• Your fallback route is still in place for 503.

Next: Concepts explains what happens to the call after the BYE and how to read the verdict. If something is being rejected, Troubleshooting lists each code and the check that clears it.