> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Connector

> Stream live telephony audio into Zero Runtime rooms over a media WebSocket using connectors for Twilio, Plivo, and Telnyx.

A connector bridges live call audio into a Zero Runtime room over a media WebSocket, without a SIP trunk. You create a connector, point your telephony provider's webhook at it, and the provider streams the call audio straight into a room. Audio flows both ways, so the caller hears the room and the room hears the caller.

Use a connector when you want to keep your phone numbers and call control in your provider account, and bridge only the audio into Zero Runtime.

## Connectors vs SIP Connect

Connectors and [SIP Connect](/telephony/integrations/twilio) are two different ways to bring the same providers into Zero Runtime. A connector streams audio over a WebSocket and leaves your number in the provider's account. SIP Connect imports the number into Zero Runtime and carries audio over SIP.

|              | Connector                                          | SIP Connect                                            |
| :----------- | :------------------------------------------------- | :----------------------------------------------------- |
| Setup        | Create a connector, point a provider webhook at it | Import a phone number into Zero Runtime                |
| Transport    | Media WebSocket                                    | SIP / RTP to `sip:$YOUR_ORG_ID.sip.videosdk.live`      |
| Phone number | Stays in your provider account                     | Imported and managed by Zero Runtime                   |
| Best for     | Bridging only the audio into a room                | A managed SIP setup with inbound and outbound gateways |

## Key Concepts

Three things make up a connector. Knowing how they relate makes the rest of the flow easy to follow.

| Term                  | What it is                                                                                                                                                                                                                                                                                  |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connector**         | The per-provider configuration you create with `connectors.create` in the [Server SDK](#create-a-connector). It generates a **webhook URL** that you set as the voice webhook in your provider console. The URL embeds a secret **webhook key** (`whk_...`), so treat it like a credential. |
| **Socket URL**        | The WebSocket endpoint the provider streams audio to, for example `wss://ingest.videosdk.live/twilio`. It carries a single-use reference (`ref`) that Zero Runtime uses to **claim** the waiting call. The reference expires 90 seconds after the webhook response.                         |
| **Lifecycle webhook** | Server-to-server events such as `call-started` and `call-hangup` that Zero Runtime posts to your registered URLs, signed with `videosdk-signature`.                                                                                                                                         |

## Supported Providers

Pick a provider to jump to its setup guide. The connector flow is the same across providers; only the console steps and the audio markup differ. Support for more providers is added over time.

| Provider | Guide                                  | Connect markup                     | Codec               |
| :------- | :------------------------------------- | :--------------------------------- | :------------------ |
| Twilio   | [Twilio](/telephony/connectors/twilio) | TwiML `<Connect><Stream>`          | μ-law (PCMU), 8 kHz |
| Plivo    | [Plivo](/telephony/connectors/plivo)   | Plivo XML `<Stream bidirectional>` | μ-law, 8 kHz        |
| Telnyx   | [Telnyx](/telephony/connectors/telnyx) | TeXML `<Start><Stream>`            | PCMU, 8 kHz         |

## Create a Connector

Connectors are created with the VideoSDK Server SDK, available for Node.js, Go, and Rust. The provider-specific guides below walk through the full setup; this is the call at the center of it.

<CodeGroup>
  ```ts Node.js theme={null}
  const connector = await client.connectors.create({ provider: "twilio", roomId });

  connector.webhookUrl; // set this at the provider
  ```

  ```go Go theme={null}
  connector, err := client.Connectors.Create(ctx, videosdk.CreateConnectorParams{
  	Provider: videosdk.ConnectorTwilio,
  	RoomID:   roomID,
  })

  fmt.Println(connector.WebhookURL) // set this at the provider
  ```

  ```rust Rust theme={null}
  let connector = client.connectors().create(videosdk::CreateConnectorParams {
      provider: Some(videosdk::ConnectorProvider::TWILIO),
      room_id: Some(room_id),
      ..Default::default()
  }).await?;

  println!("{:?}", connector.webhook_url); // set this at the provider
  ```
</CodeGroup>

Options: `provider` (required, one of `twilio`, `plivo`, or `telnyx`), `name`, `roomId` (fallback room), `defaultRuleId`, `region`.

## How It Works

A call passes between three parties: your provider, Zero Runtime, and the room. The flow is the same for inbound and outbound calls, and each step below hands off to the next.

1. **A call is placed.** The provider handles the call (an inbound call to your number, or an outbound call you initiate) and sends a voice webhook to the connector's webhook URL.
2. **Zero Runtime resolves routing.** It decides which room the call joins, and optionally which agent, from the connector's `defaultRoomId` or `defaultRuleId`, a matching phone-number routing rule, or a `roomId` query parameter.
3. **Zero Runtime returns connect markup.** The response (TwiML, Plivo XML, or TeXML) tells the provider to open a media WebSocket to the socket URL, carrying a single-use `ref` that identifies the call.
4. **The provider opens the WebSocket.** Zero Runtime claims the call using the `ref`, joins the room, and bridges audio in both directions.
5. **Zero Runtime emits lifecycle events.** As the call progresses, Zero Runtime posts signed webhooks (`call-started`, `call-answered`, `call-hangup`) to your server.

<Note>
  **Single-use claim window.** The `ref` is valid for 90 seconds after Zero Runtime returns the markup. The provider must open the WebSocket within that window, or the claim expires and the call fails. Providers normally connect within a second, so this only matters when a webhook is misconfigured.
</Note>

## Lifecycle Webhooks

Connectors use the same webhook system as [SIP Connect](/telephony/managing-calls/webhooks). Zero Runtime posts call events such as `call-started`, `call-answered`, and `call-hangup` to your registered URLs, each signed with a `videosdk-signature` header so you can verify it.

For the full event list, payloads, signature verification, and registration, see [SIP Webhooks](/telephony/managing-calls/webhooks).

## Next Steps

<CardGroup cols={3}>
  <Card title="Twilio Connector" icon="phone" href="/telephony/connectors/twilio">
    Stream Twilio Media Streams audio into a room.
  </Card>

  <Card title="Plivo Connector" icon="phone" href="/telephony/connectors/plivo">
    Stream Plivo Audio Streaming into a room.
  </Card>

  <Card title="Telnyx Connector" icon="phone" href="/telephony/connectors/telnyx">
    Stream TeXML media into a room.
  </Card>
</CardGroup>
