Documentation

SIP integration

Point an IP-authenticated SIP trunk at the ingress host on your account, port 5060 over UDP or TCP, no registration, no credentials, G.711 in the INVITE. Open Voice Shield authorizes by source IP, anchors the media to record it, and relays the call to the destination you configure.

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 that carries your dialled number, caller ID and 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:

curl -s https://ovs.telecomsxchange.com/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.

Several sub-customers behind one IP#

If one switch carries traffic for several of your own customers, give each of them a dial prefix on the same IP. Your switch puts the prefix in front of the number it dials, we label the call with that sub-customer, remove the prefix and send the call on as usual. The Calls list then shows, and filters by, whose call it was.

curl -s -X POST https://ovs.telecomsxchange.com/api/customer/ips \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"cidr":"174.136.44.213/32","dial_prefix":"1234#","label":"Sub customer A"}'
curl -s -X POST https://ovs.telecomsxchange.com/api/customer/ips \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"cidr":"174.136.44.213/32","dial_prefix":"2222#","label":"Sub customer B"}'

# INVITE sip:1234#15551234567@...  is Sub customer A's call, relayed as  sip:15551234567@...

Trunk settings to enter on your switch#

Every switch has its own name for these (peer, trunk, carrier, gateway, endpoint), but the settings are the same. Create an IP-authenticated entry with no registration and route the traffic you want analyzed through it.

Step-by-step versions of this page exist for your Asterisk, FreeSWITCH, Kamailio, OpenSIPS or any other SIP-capable switch.

Firewall, both directions#

Signalling and media use different ports and the media leg is the one people forget. Media is plain RTP on UDP 30000–40000 at the ingress address.

If the destination is your own SBC or PBX, add the ingress host to its trusted peers or ACL before the first test call. Rejection by your own equipment is the 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 dialled 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 dialled 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 https://ovs.telecomsxchange.com/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 dialled number and the prefix that was applied.
• Clear it by sending an empty value.

Digest authentication towards the destination#

Some carriers and PBXs whitelist our IP and also challenge the INVITE with 401 or 407. Store the credential they gave you on the destination (auth_username, auth_password, optional auth_realm, or Network → the destination → Advanced → SIP authentication) and the proxy answers the challenge and re-sends the INVITE. Your switch never sees the challenge.

• Optional. Without a credential, a challenge from the destination reaches your switch as before.
• Write-only: stored sealed, never returned. The destination shows has_credential.
• Leave the realm blank to answer whatever realm the destination challenges with.
• A wrong credential ends the call with the destination's own reply, reported once.
• Only the INVITE is answered. A destination that also challenges BYE or re-INVITE is not supported.

Routing to a voice agent#

A destination of kind voice_ai is an AI voice agent reached as a SIP endpoint, so a screened call, or a caller diverted by an automation rule, goes to the agent instead of a human queue. Two providers are supported. Each has its own endpoint, identifier and connection rules, and GET /customer/voice-providers returns them exactly as the platform applies them.

curl -s -X POST https://ovs.telecomsxchange.com/api/customer/destinations \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"voice_ai","provider":"openai","host":"sip.api.openai.com","port":5061,"transport":"tls",
       "agent_id":"proj_abc123","label":"after-hours agent"}'

• The credential is write-only: it is stored sealed, never returned, and has_credential / needs_credential on the destination tell you where you stand. An xAI agent without one is flagged on the Network page.
• The agent leg is metered per second and shown on the call record as agent_seconds with the rate applied; the recording, transcript, verdict and per-leg quality are produced as for any other destination.
• A voice-agent destination is monitored with SIP OPTIONS like any other, and the destination-down alert applies.

OpenAI: the hosted webhook

OpenAI does not answer a SIP call on its own. Every call to a project raises an incoming-call event on the project's webhook, and the call connects only when that webhook accepts it with a session: the model, the voice, the instructions. The platform hosts that webhook for you, one URL per destination, so nothing of yours has to be online to take the call.

1. Create the destination (the request above, or Network → Add destination → Voice AI → OpenAI). The record comes back with its webhook_url, https://ovs.telecomsxchange.com/api/hooks/openai/<token>; the Network page shows it with a copy button.
2. In the OpenAI dashboard, Settings → Project → Webhooks: add that URL and subscribe it to the incoming-call event of the model family you want: live.transport.incoming for GPT-Live (the default, GPT-Live-1), or realtime.call.incoming for the Realtime models. Copy the signing secret OpenAI shows.
3. Create an API key in the same project (Settings → API keys).
4. Store both on the destination: webhook_secret and provider_api_key, in the portal or with a PATCH. They are write-only and stored sealed; has_webhook_secret and has_provider_key confirm they are there, and the Needs webhook setup flag clears.
5. Optionally set the agent: config takes model (default GPT-Live-1 for the GPT-Live event, a Realtime model for the Realtime event), voice and instructions; the portal has fields for the three.
6. Place a call. The destination records the last event (webhook_last_status accepted, or failed with the reason, for example an API key the project refuses), and the call record carries agent_call_ref, OpenAI's id for the call.

curl -s -X PATCH https://ovs.telecomsxchange.com/api/customer/destinations/$DEST \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"webhook_secret":"whsec_…","provider_api_key":"sk-…",
       "config":{"model":"gpt-live-1","voice":"marin","instructions":"You are the after-hours agent for Example Corp."}}'

• Every event is checked against the signing secret (the Standard Webhooks signature, five-minute tolerance); an unsigned, stale or mis-signed event is refused and the URL is a 32-byte secret of its own. rotate_webhook_token: true on a PATCH mints a new URL and retires the old one; clear_webhook_secret and clear_provider_key drop the secrets.
• GPT-Live requires encrypted media. The platform offers SRTP on the agent leg and keeps your side on plain RTP, as for any other destination, so there is nothing to configure on your switch.
• The API key is used for one thing: accepting or rejecting the call the event announces. It is never returned and never logged.

Putting an agent behind an existing switch, SBC or PBX that has no TLS or SRTP? The connect any SBC to a voice agent guide is the four-step version, and the voice agent gateway page explains what the platform does in between.

Destination monitoring#

Every destination is checked with a SIP OPTIONS request the moment it is saved, and again whenever its host, port or transport changes. A destination that answers is monitored from then on: one OPTIONS a minute from the ingress host, with the verdict, the last check time and the round-trip time shown next to it on the Network page and returned on the destination record. A destination that never answers is left alone (status unknown, "no reply") and tried again once a day, or whenever you press Check now.

curl -s -X POST https://ovs.telecomsxchange.com/api/customer/destinations/<destination id>/check \
  -H "Authorization: Bearer $TOKEN"
# {"id":"...","host":"sbc.example.net","port":5060,"transport":"udp", ...
#  "monitor_enabled":true,"monitor_supported":true,"monitor_status":"up",
#  "monitor_last_check_at":"2026-09-06T14:02:11Z","monitor_rtt_ms":38,"monitor_last_code":200,"monitor_last_error":null}

• The check comes from the ingress host, so a destination that only trusts that address still answers. If yours answers INVITE but not OPTIONS, allow OPTIONS from the ingress host and press Check now.
• Over TLS the certificate is not verified for the check; self-signed trunk certificates would otherwise read as down.
• Heartbeat alerts: an alert rule with the trigger Destination down emails its recipients, or posts to its Slack channel, when a monitored destination goes down, and again when it comes back. The rule's throttle applies.
• Agents get the same fields from list_destinations and can run a check with check_destination, see the agents guide.

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 fixed platform-wide and is not customer-configurable. Write to support@telecomsxchange.com 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 dialled 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 "https://ovs.telecomsxchange.com/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.

Frequently asked questions#

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.