Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
AI Voice Agents via sip_forward

You can point an Orbit DID at any third-party AI voice platform that exposes a SIP endpoint — callers.ai, Retell, Vapi, and most other agent providers do. Orbit handles the carrier termination, billing, and recording; the AI provider runs the conversation logic. This guide walks through wiring up an inbound sip_forward route end to end. The same shape works for self-hosted PBX targets — see the SIP trunk reference for the trunk-mode alternative.

​
How it works

  1. Orbit owns the DID and accepts the inbound INVITE from the carrier.
  2. Orbit’s SBC (Jambonz) re-INVITEs the call to the AI provider’s SIP URI on your behalf, terminating TLS at our edge.
  3. RTP media is bridged through RTPengine — the AI provider never sees the carrier directly, and the carrier never sees the AI provider.
  4. Hangup, DTMF, and recording are surfaced over the same Orbit webhook contract regardless of which AI vendor terminates the call.

​
Step 1 — Buy a number

Pick a number for the agent. Toll-free numbers tend to work better for contact-center scenarios because A2P 10-DLC restrictions don’t apply to inbound voice. 
curl -X POST https://orbit-api.devotel.io/api/v1/numbers \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "type": "toll-free",
    "capabilities": ["voice"]
  }'
The response carries the number_id you’ll use in the next step.

​
Step 2 — Configure inbound routing → sip_forward

curl -X PUT https://orbit-api.devotel.io/api/v1/numbers/$NUMBER_ID/routing \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sip_forward",
    "config": {
      "mode": "inline",
      "sipUri": "sip:agent_xyz@sip.vapi.ai",
      "sipUsername": "your-trunk-user",
      "sipPassword": "your-trunk-secret"
    }
  }'
You can omit sipUsername / sipPassword if the AI provider doesn’t require digest auth on the inbound INVITE — most do not.

​
Provider URI examples

Each AI provider publishes a slightly different SIP URI shape. Use the example for your vendor verbatim — only the token / agent ID changes.

​
callers.ai

sip:<token>@callers.ai
The <token> is the agent token from your callers.ai dashboard (Settings → Phone → SIP).

​
Retell

sip:<agent_id>@<retell-sip-host>
<retell-sip-host> is the host published in your Retell dashboard under “Phone Numbers → BYO SIP” — it’s region-specific (5t4n6j0wnrl.sip.livekit.cloud is one current example, but check your dashboard).

​
Vapi

sip:<assistant_id>@sip.vapi.ai
The <assistant_id> is the assistant’s ID from the Vapi dashboard (Assistants → ID → Copy). Vapi’s SIP endpoint accepts unauthenticated INVITEs by default; configure an inbound credential under “SIP Trunks” if your security posture requires digest auth.

​
DTMF

Orbit forwards DTMF events to the AI provider as RFC 4733 in-band RTP. All three providers above support this out of the box — no extra configuration needed. SIP INFO DTMF is not forwarded; if your agent only supports SIP INFO, contact support and we’ll enable the DTMF translator on your account.

​
Audio codec compatibility

Orbit’s SBC re-negotiates codecs on the way out, so the AI provider sees only the codec it’s comfortable with even if the carrier offered something exotic.
CodecOrbit ↔ CarrierOrbit ↔ AI ProviderNotes
G.711 µ-law✅✅Default for US carriers, all AI providers
G.711 A-law✅✅EU carriers; transcoded only when AI requires µ-law
Opus✅✅ (Vapi, Retell)Lowest latency; not all carriers offer it
G.729✅❌Transcoded to G.711 — adds ~10ms latency

​
Troubleshooting

​
Signature 401 on inbound INVITE

The AI provider’s SIP gateway rejected your INVITE with a 401 Unauthorized and you don’t see the call in your provider dashboard. The two common causes:
  1. Wrong token / agent_id. Re-copy from the provider dashboard; tokens are case-sensitive.
  2. Trunk auth required. Some providers (Retell on production tier, Vapi if “Allow only authorized SIP origins” is on) need digest auth. Set sipUsername and sipPassword on the route config to credentials issued by the provider — Orbit stores them encrypted at rest.

​
Audio one-way

You can hear the caller, but the caller can’t hear the agent (or vice versa). This is almost always a codec mismatch on the AI provider side — the AI is sending Opus but Orbit re-INVITEd as G.711. Open a ticket with the provider and ask them to advertise G.711 µ-law in their SDP answer; Orbit will negotiate down to whatever both ends agree on.

​
Calls drop at exactly 32 seconds

Classic NAT keep-alive timeout: the carrier or RTPengine isn’t seeing media in one direction, so the SBC tears the call down at the 32s default. The fix lives on the AI provider’s side — they need to send RTP keep-alives during periods of silence (e.g. while waiting on the LLM). All three providers above support this; check their “send RTP during silence” setting. If the drop happens earlier (< 5s), it’s usually the carrier rejecting the re-INVITE — open a support ticket with your call SID and we’ll pull the SBC trace.

​
See also

  • SIP Trunks — the trunk-mode alternative to inline sip_forward. Use this when one trunk fans out to many DIDs.
  • Inbound routing — full reference for the five route types (webhook, agent, flow, sip_forward, voicemail).
  • Webhooks — receive call.initiated, call.answered, and call.completed events for calls forwarded to an AI agent.