Documentation
Connect any SBC or SIP switch to an AI voice agent
Ask AI about this page
Any switch that can send a plain SIP call to a next hop can put a caller in front of an OpenAI GPT-Live-1 or xAI voice agent: whitelist the switch's IP, add a Voice AI destination (for OpenAI, register its webhook URL and secrets), route a prefix at it. The platform handles TLS, SRTP, the webhook and the session.
What the switch needs#
The same as any route through Open Voice Shield. If your equipment can send an initial INVITE with SDP to a next hop of your choosing over UDP or TCP, and keep its media symmetric and unencrypted, it can send calls to an AI voice agent. TLS, SRTP, the webhook the agent provider requires and the session it keeps are all done by the platform, per destination. The vendor-neutral connection guide lists the trunk parameters in any vendor's vocabulary; the same values apply here.
Step 1: whitelist your switch's IP#
Open the Network page in the portal and add the public address your switch sends from as a CIDR entry (a single host is a /32). That is the authentication: there are no credentials on the trunk, and an INVITE from any other address is answered 403.
Step 2: add the Voice AI destination#
Under Add destination, pick kind Voice AI and the provider. The host, port and transport fill in with what the provider expects; you supply the identifier and the agent's personality.
| Provider | Agent ID | Secrets | Agent settings |
|---|---|---|---|
| OpenAI | your project id (proj_…) | webhook signing secret and a project API key, after step 3 | voice, instructions, optional model and reasoning model |
| xAI | the agent's Direct SIP number | the digest username and password xAI gave the agent | configured on xAI's side |
Write the instructions the way you would brief a receptionist, and say whether the agent should speak first. An agent told only to "help the caller" waits for the caller to speak; "Answer the call immediately by saying: Hello?" makes it greet.
The dialog also has a Call handling setting. Full analysis, the default, records, transcribes and scores every call to the agent. Record only keeps the recording and the SIP log and skips the analysis. Relay only is pure gateway mode: the call is bridged and metered, and nothing is recorded, transcribed, analyzed or traced. Pick it when the agent's own logs are all you need.
Step 3: register the webhook (OpenAI)#
OpenAI only connects a call when a webhook accepts it. The platform hosts that webhook for you: once the destination is saved, it shows a webhook URL with a copy button.
- In your OpenAI project, under Settings → Webhooks, add the destination's URL and subscribe it to the GPT-Live incoming-call event (live.transport.incoming). Copy the signing secret OpenAI shows.
- Create an API key in the same project.
- Back on the destination, paste the signing secret and the API key. They are stored sealed and never shown again, and the Needs webhook setup flag clears.
xAI has no webhook step: the digest credential on the destination is all it needs.
Step 4: route calls at the destination#
Under Routing rules, send a prefix to the destination, or make it the default so every call from the whitelisted switch reaches the agent. On the switch, the route is the ordinary one:
The trunk, in any vendor's vocabulary
trunk / peer / gateway "ovs-agent"
host sip.ovs.telecomsxchange.com
port 5060
transport UDP or TCP
register no # a REGISTER is answered 403
credentials none # authorization is your whitelisted source IP
codecs PCMU, PCMA # G.711; the platform offers the agent G.711 and G.722
sdp early offer, in the initial INVITE
dtmf RFC 2833 telephone-event, relayed to the agent
media plain RTP; ours arrives from UDP 30000-40000What the switch gets back is plain: a 200 OK with G.711, one Record-Route hop on port 5060 and a Contact that is the platform. A B2BUA that ignores route sets, sends its ACK to the Contact host or refuses a sips: URI completes the call anyway, because everything it sends lands on the platform, which re-targets it to the agent over TLS. This was verified against a carrier softswitch with none of those features.
Step 5: place a call#
Dial the prefix from the switch, say a sentence, and pause. The agent answers after the pause, or immediately if its instructions say so. When either side hangs up, the other is released at once. Then read the call record: recording, transcript, verdict, the SIP ladder and per-leg quality, and the agent leg's seconds and rate. The destination shows the last webhook event and the agent's own transcript of what it heard and said.
If something is off#
- The agent leg answers 400 Bad Request
- The project id is not one OpenAI knows for that webhook. Check the Agent ID against Settings → Project → General in the OpenAI dashboard.
- The destination shows "Needs webhook setup"
- The signing secret or the API key is missing. Until both are stored, OpenAI's webhook events are refused and calls are not accepted.
- The call connects, the agent stays silent
- Look at the destination's last event. "Heard" empty means the agent got no speech, so check the caller's audio. "Heard" filled and "said" empty means the agent is waiting, so add a greeting instruction.
- The caller hears nothing although the agent spoke
- The media relay counts packets per leg on every call. If the agent leg carried audio and the switch leg did not, the switch is not sending or accepting RTP to the platform's advertised address. Check its NAT and media settings as for any route.
Provider details, the API calls and the full parameter list are in the SIP integration guide. Why the gateway exists, and who it is for, is on the voice agent gateway page.
Frequently asked questions#
Does my switch need TLS or SRTP to reach an AI voice agent?
No. The switch sends plain SIP over UDP or TCP with plain RTP to the ingress. Open Voice Shield originates TLS signalling and SRTP media towards the agent and keeps your leg exactly as it was.
My switch ignores Record-Route or refuses sips: URIs. Will it work?
Yes. On a call to a voice agent the switch receives one plain route hop and a Contact that is the platform, so its ACK, re-INVITEs and BYE always land on the platform, which re-targets them to the agent over TLS. This was verified with a carrier softswitch that sends in-dialog requests to the Contact host and drops any secure hop.
The call connects but the agent says nothing. Why?
Most often the agent is waiting for the caller: say a sentence and pause, or add an instruction such as 'Answer the call immediately by saying: Hello?'. The destination shows the last webhook event and what the agent heard and said, which tells apart an agent that cannot hear the caller from one that chose to stay quiet.
The agent leg fails with 400 Bad Request. Why?
The project id on the destination is not one OpenAI knows, or the webhook is not registered for that project. Check the Agent ID against Settings, Project, General in the OpenAI dashboard, and the destination's webhook status.
Is DTMF passed to the agent?
RFC 2833 telephone-event is offered on the agent leg and accepted by the provider, so keypad presses from the caller are relayed to the agent.