# Vobiz

> Bring a Vobiz SIP trunk and Indian DIDs onto FirstByte. Register or IP-auth the trunk in the console. Route each DID to any agent, native or external. Then go live.

Vobiz is an Indian SIP trunk and DID provider. Unlike the app-platform
integrations (Twilio, Plivo, Telnyx), there is no API surface to port. Vobiz
is a **carrier**, and the integration is a trunk. You point your Vobiz trunk
at FirstByte. The platform terminates the SIP legs. Every DID routes to the
agent that you select. This architecture is **in production today for Indian
DIDs**.

Everything downstream of the trunk is ordinary FirstByte. The engine
decodes the carrier leg to the 8 kHz `pcm16` audio bus. The DID can point at a
**native agent** or an **external agent**. A native agent is the managed
runtime: prompt and STT/LLM/TTS in the console. An external agent is your own
worker process. The worker holds one outbound QUIC/WebTransport session. It
registers under an agent handle, and a `VENDOR_BRIDGE` config routes calls to
it.

## What maps to what

| You have from Vobiz | On FirstByte |
| --- | --- |
| A SIP trunk (registration credentials, or a static IP to allowlist) | A trunk object in the console: registration **or** IP auth |
| Indian DIDs on the trunk | Numbers routed per-DID to any agent |
| Inbound calls to the DID | The engine answers, decodes to the 8 kHz bus, and dispatches to the routed agent |
| Outbound calls through the trunk | `voice.calls.originate {to, trunkId, agent?}` on the management API |
| Carrier-side call records | Platform CDRs, MOS scoring, recordings, and `voice.*` webhooks |

## Bring the trunk up

  1. **Create the trunk in the console**
In the console (`agent.firstbyte.fast`), add a SIP trunk. Select the auth
    mode that your Vobiz service uses:

    - **Registration**: enter the SIP username/password from Vobiz. The
      platform registers to their registrar and keeps the binding alive.
    - **IP auth**: exchange static IPs instead. Allowlist Vobiz's signaling
      IPs on the trunk. Give Vobiz the platform's SIP host as the call
      target.

    See [SIP Trunking](/modalities/voice/transport-telephony/sip-trunking)
    for trunk fields, codecs, and failover.

  2. **Route each DID to an agent**
Attach your Vobiz DIDs to the trunk. Point each DID at an agent. Both
    kinds are first-class targets:

    - **Native agent**: the managed runtime runs the conversation (cascade or
      speech-to-speech) with your provider keys. You run no servers.
    - **External agent**: your own process gets the call. The console's
      **External agents** create flow reserves the agent handle. It mints the
      media app key/secret that your worker authenticates with. It writes the
      `VENDOR_BRIDGE` config:

    ```json agent-config.json
    {
      "entry_node": "bridge",
      "pipeline": {
        "bridge": {
          "node_type": "VENDOR_BRIDGE",
          "vendor_provider": "clutchcall",
          "vendor_room": "my-worker"
        }
      }
    }
    ```

    The worker side is the same seam as every other external-agent
    integration: `pip install "clutchcall-agents[quic]"`, plus a handler that
    reads `call.audio()` and writes `call.send_audio()`. Start from the
    [external-agent recipe](/modalities/voice/recipes/livekit-transport).

  3. **Place a test call in each direction**
Dial the DID from a mobile phone. The engine answers on the Vobiz leg and
    dispatches to the routed agent. Then originate outbound through the same
    trunk with an `mpk_` management key (portal → Settings → API Keys):

```python
from clutchcall_agents.api import ClutchCallAPI

api = ClutchCallAPI(base_url="https://app.firstbyte.fast",
                   api_key=os.environ["CLUTCHCALL_API_KEY"],  # mpk_...
                   org_id="org_abc")

api.call("voice.calls.originate",
         {"to": "+91XXXXXXXXXX", "trunkId": "trunk_vobiz",
          "agent": "my-worker"})
```

  4. **Wire up lifecycle events**
Register a signed webhook for call lifecycle, CDRs, recordings, and
    transcripts. Use `webhooks.create {vertical:'voice', url, eventTypes}`
    with events such as `voice.call.answered`, `voice.cdr.created`, and
    `voice.recording.ready`. Check the `X-Clutchcall-Signature` header
    (`t=<epoch>,v1=<hmac_sha256(secret, "t.body")>`) with
    `clutchcall_agents.webhooks.verify_signature` before you trust a delivery.

## Troubleshooting

  **Inbound calls never reach the platform**

On registration trunks, check the registration state on the trunk page.
    Wrong credentials or a Vobiz-side block shows there first. On IP-auth
    trunks, check that the allowlist covers **all** of Vobiz's signaling IPs,
    not only the IP that you saw traffic from.

  **The call connects but audio is one-way**

This is a classic SIP/NAT symptom on carrier trunks. Check the media (RTP)
    path in both directions. Check any address rewriting between Vobiz and the
    platform.
    [SIP & RTP debugging](/modalities/voice/observability/sip-rtp-debugging)
    shows both legs of a live call.

  **An external agent answers with silence**

The trunk is good, but the worker is not. Check that the worker is
    registered under the exact handle in `vendor_room`. Check that it has
    outbound UDP/443 to `engine.firstbyte.fast`. Media rides QUIC datagrams. A
    TCP-only network registers correctly and then stalls audio.

## Related

  - **[SIP Trunking](/modalities/voice/transport-telephony/sip-trunking)** — Trunk auth modes, codecs, and failover in full.
  - **[Number Provisioning](/modalities/voice/transport-telephony/number-provisioning)** — DIDs, routing, and per-number agent assignment.
  - **[LiveKit integration](/modalities/voice/integrations/livekit)** — Run an existing LiveKit agent behind your Vobiz DIDs.
  - **[Run a LiveKit Agent on the Transport](/modalities/voice/recipes/livekit-transport)** — The end-to-end external-agent recipe for the worker side.