> ## 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.

# Twilio Connector

> Stream Twilio call audio into a Zero Runtime room over Twilio Media Streams. Create the connector with the Server SDK, configure Twilio, and receive bidirectional audio.

A Twilio connector streams live audio from a Twilio call into a Zero Runtime room using [Twilio Media Streams](https://www.twilio.com/docs/voice/media-streams). You point your Twilio number's voice webhook at the connector, and Twilio opens a bidirectional WebSocket that carries the call audio into the room. No SIP trunk is required.

Setup takes three steps: create the connector, configure your Twilio number, and route the call to a room. If you are new to connectors, read the [Connectors Overview](/telephony/connectors/overview) first.

## How It Works

1. A caller dials your Twilio number.

2. Twilio sends a voice webhook to your connector's webhook URL.

3. Zero Runtime resolves routing and responds with TwiML that tells Twilio where to stream the audio:

   ```xml theme={null}
   <?xml version="1.0" encoding="UTF-8"?>
   <Response>
     <Connect>
       <Stream url="wss://ingest.videosdk.live/twilio?ref=<callRef>" />
     </Connect>
   </Response>
   ```

4. Twilio opens that WebSocket and streams audio. Zero Runtime claims the call, joins the room, and bridges audio in both directions.

You do not implement the WebSocket protocol; Twilio handles it. Audio is G.711 μ-law (PCMU) at 8 kHz, in 20 ms frames of 160 bytes, and the call is identified by Twilio's `CallSid`.

## Prerequisites

* A Zero Runtime account with an **API key and secret** from the [Zero runtime Dashboard](https://app.zeroruntime.ai/api-keys). The Server SDK signs and attaches its own management token on every request, so you never set an `Authorization` header yourself.
* An active Twilio phone number.
* Your Twilio Account SID and Auth Token, from the Twilio Console.

Install the Server SDK for your language:

<CodeGroup>
  ```bash Node.js theme={null}
  npm install @videosdk.live/server-sdk
  ```

  ```bash Go theme={null}
  go get github.com/videosdk-live/videosdk-server-sdk-go
  ```

  ```bash Rust theme={null}
  cargo add videosdk-server-sdk
  cargo add tokio --features rt-multi-thread,macros
  ```
</CodeGroup>

<Note>
  The Server SDK requires Node.js 18+, Go 1.23+, or Rust 1.75+. Keep your secret on the server — it signs tokens, so it must never reach a browser or mobile app.
</Note>

## Step 1: Create a Connector

Create the connector with a single Server SDK call. Setting the fallback `roomId` here is the fastest path to a working call, since every call then joins that room.

<CodeGroup>
  ```ts Node.js theme={null}
  import { VideoSDK } from "@videosdk.live/server-sdk";

  const client = new VideoSDK({
    apiKey: process.env.VIDEOSDK_API_KEY!,
    secret: process.env.VIDEOSDK_SECRET!,
  });

  const connector = await client.connectors.create({
    provider: "twilio",
    roomId: "abcd-efgh-ijkl",
  });

  console.log(connector.webhookUrl); // set this at the provider
  ```

  ```go Go theme={null}
  client, err := videosdk.NewClient(
  	videosdk.WithAPIKey(os.Getenv("VIDEOSDK_API_KEY")),
  	videosdk.WithSecret(os.Getenv("VIDEOSDK_SECRET")),
  )
  if err != nil {
  	log.Fatal(err)
  }
  ctx := context.Background()

  connector, err := client.Connectors.Create(ctx, videosdk.CreateConnectorParams{
  	Provider: videosdk.ConnectorTwilio,
  	RoomID:   "abcd-efgh-ijkl",
  })
  if err != nil {
  	log.Fatal(err)
  }

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

  ```rust Rust theme={null}
  use videosdk::{Client, ConnectorProvider, CreateConnectorParams};

  let client = Client::builder()
      .api_key("YOUR_API_KEY")
      .secret("YOUR_SECRET")
      .build()?;

  let connector = client
      .connectors()
      .create(CreateConnectorParams {
          provider: Some(ConnectorProvider::TWILIO),
          room_id: Some("abcd-efgh-ijkl".into()),
          ..Default::default()
      })
      .await?;

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

`connectors.create` accepts the following options.

| Option          | Required | Description                                                                                                                                      |
| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`      | Yes      | Must be Twilio: `"twilio"` in Node.js, `videosdk.ConnectorTwilio` in Go, `ConnectorProvider::TWILIO` in Rust.                                    |
| `name`          | No       | A label to help you recognize the connector later.                                                                                               |
| `roomId`        | No       | Fallback room that calls join when no routing rule matches. Set this for the simplest setup. It is returned on the connector as `defaultRoomId`. |
| `defaultRuleId` | No       | Fallback [routing rule](/telephony/call-routing/setting-up-routing-rules) ID, for dynamic routing.                                               |
| `region`        | No       | Pins the media and ingest region (e.g., `us002` or `in002`). When omitted, the region is derived from the caller.                                |

The call returns the connector, including the `webhookUrl` you need for the next step.

| Field           | Type   | Description                                                                                     |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------- |
| `id`            | string | Connector ID, prefixed with `cn_`. Use it to fetch, rotate, or delete the connector.            |
| `provider`      | string | Telephony provider — `twilio` here.                                                             |
| `name`          | string | Display name.                                                                                   |
| `webhookUrl`    | string | The URL you configure in Twilio in the next step. It embeds the secret webhook key (`whk_...`). |
| `defaultRoomId` | string | Fallback room used when no routing rule resolves.                                               |
| `defaultRuleId` | string | Routing rule applied by default.                                                                |
| `region`        | string | Region call ingestion is pinned to.                                                             |
| `createdAt`     | string | Creation timestamp (ISO-8601).                                                                  |

**Copy the `webhookUrl`.** You will paste it into Twilio in Step 2.

<Warning>
  **Keep the webhook URL private.** Anyone who has the webhook URL can route calls into your room, because the key is part of the URL. If it leaks, [rotate the key](#rotate-the-webhook-key) to invalidate the old URL.
</Warning>

## Step 2: Configure Twilio

Give the `webhookUrl` from Step 1 to your Twilio number, so Twilio calls Zero Runtime whenever the number rings.

<Steps>
  <Step title="Open your Twilio number">
    In the [Twilio Console](https://console.twilio.com/), go to **Phone Numbers > Manage > Active numbers** and select the number you want to use.
  </Step>

  <Step title="Point the voice webhook at the connector">
    Under **Voice Configuration > A call comes in**, choose **Webhook**, paste the `webhookUrl`, and set the method to **HTTP POST**.
  </Step>

  <Step title="Save">
    Save your changes.
  </Step>
</Steps>

That is the entire provider-side setup. From now on, when the number rings, Twilio posts to the webhook and Zero Runtime replies with the `<Connect><Stream>` TwiML automatically.

<Tip>
  If your number is wired to a TwiML App instead of a number-level webhook, set the same `webhookUrl` as the app's Voice Request URL, with the method set to HTTP POST.
</Tip>

## Step 3: Route the Call

Routing decides which room a call joins. You have three options, from simplest to most flexible:

* **Connector default.** The `roomId` you set in Step 1 sends every call to one fixed room. Best for a single destination or for testing.
* **Per-call override.** Append a `roomId` query parameter to the webhook URL in Twilio (`...whk_xxx?roomId=<roomId>`) to target a specific room for that number.
* **Routing rules.** For different callers or numbers landing in different rooms, or to attach an AI agent, create a [routing rule](/telephony/call-routing/setting-up-routing-rules) and reference it with `defaultRuleId`.

If you set `roomId` in Step 1, you can skip this step and move straight to testing.

## Step 4: Test an Inbound Call

1. Add a participant or [AI agent](/telephony/call-routing/ai-agent-routing) to the target room, so there is audio to exchange.
2. Call your Twilio number from any phone.
3. Confirm that the caller hears the room and the room hears the caller.

If you registered [lifecycle webhooks](#lifecycle-webhooks), you will see `call-started`, then `call-answered`, and finally `call-hangup` when the call ends. These are the quickest way to confirm the flow end to end.

## Manage the Connector

List your connectors, or fetch a single one by ID:

<CodeGroup>
  ```ts Node.js theme={null}
  await client.connectors.list();
  await client.connectors.get(connectorId);
  ```

  ```go Go theme={null}
  client.Connectors.List(ctx)
  client.Connectors.Get(ctx, connectorID)
  ```

  ```rust Rust theme={null}
  client.connectors().list().await?;
  client.connectors().get(connector_id).await?;
  ```
</CodeGroup>

### Rotate the Webhook Key

Rotating the key invalidates the current webhook URL immediately and returns a new one. Update Twilio with the new URL right after, or calls will stop reaching Zero Runtime.

<CodeGroup>
  ```ts Node.js theme={null}
  await client.connectors.rotateKey(connectorId); // invalidates the old webhook URL
  ```

  ```go Go theme={null}
  client.Connectors.RotateKey(ctx, connectorID) // invalidates the old webhook URL
  ```

  ```rust Rust theme={null}
  client.connectors().rotate_key(connector_id).await?; // invalidates the old webhook URL
  ```
</CodeGroup>

### Delete a Connector

<CodeGroup>
  ```ts Node.js theme={null}
  await client.connectors.delete(connectorId);
  ```

  ```go Go theme={null}
  client.Connectors.Delete(ctx, connectorID)
  ```

  ```rust Rust theme={null}
  client.connectors().delete(connector_id).await?;
  ```
</CodeGroup>

## Lifecycle Webhooks

To track calls on your server, register a webhook URL and listen for events such as `call-started`, `call-answered`, and `call-hangup`. Each request carries a `videosdk-signature` header (a base64 RSA-SHA256 signature of the body) so you can verify it. Connectors use the same webhook system as SIP, so see [SIP Webhooks](/telephony/managing-calls/webhooks) for the full event list, payloads, and registration.

## Troubleshooting

| Symptom                                                | Likely cause and fix                                                                                                                                        |
| :----------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Call connects but there is no audio                    | No one is in the target room, or the fallback `roomId` is wrong. Add a participant or agent and verify the room ID.                                         |
| Twilio reports an application error                    | The webhook URL is wrong or the method is not POST. Re-copy the URL from the connector and set the method to HTTP POST.                                     |
| The stream never starts, or the call drops immediately | The claim expired (more than 90 seconds), or routing resolved no room. Confirm the number points at the current webhook URL and that a room is resolved.    |
| Connector calls fail with 401 or 403                   | The API key or secret passed to the Server SDK client is missing or wrong. Check them in the [Zero runtime Dashboard](https://app.zeroruntime.ai/api-keys). |
| Audio works but quality is low                         | Telephony audio is 8 kHz narrowband μ-law by design. This is expected for PSTN calls.                                                                       |

## Reference

* [Create a connector](https://docs.videosdk.live/api-reference/realtime-communication/connectors/create-connector)
* [List connectors](https://docs.videosdk.live/api-reference/realtime-communication/connectors/fetch-all-connectors)
* [Get a connector](https://docs.videosdk.live/api-reference/realtime-communication/connectors/fetch-connector)
* [Rotate the webhook key](https://docs.videosdk.live/api-reference/realtime-communication/connectors/rotate-connector-key)
* [Delete a connector](https://docs.videosdk.live/api-reference/realtime-communication/connectors/delete-connector)