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

# Telephony Integration

> Add a phone number, connect it to your agent with a routing rule, and place your first call.

Connecting your agent to the phone network takes three steps:

1. **Add a phone number**: import one you own, or bring your own SIP trunk.
2. **Create a routing rule**: link the number to your agent.
3. **Place a call**: call the agent, or have it call out.

<Warning>
  **Deploy first.** A routing rule only sends calls to the agent, so the agent must be running to answer them. [Commit and deploy](/agent-builder/deploy) your agent before you test telephony.
</Warning>

## 1. Add a phone number

<Tabs>
  <Tab title="Import number">
    Import a number you already own from a supported provider (Twilio or Plivo). The video uses Twilio.

    <Frame>
      <video controls className="w-full aspect-video" src="https://cdn.zeroruntime.ai/zrt/website-content/telephony/integration-twilio.mp4" />
    </Frame>

    <Steps>
      <Step title="Open Telephony">
        In the dashboard, open **Telephony** and select **Add Number** → **Import Number**.
      </Step>

      <Step title="Choose a provider">
        Select **Twilio** or **Plivo**.
      </Step>

      <Step title="Enter the details">
        Enter a **Name For Phone Number**, your provider credentials (Account SID and Auth Token for Twilio, or Auth ID and Auth Token for Plivo), and the phone number.
      </Step>

      <Step title="Import">
        Select **Import Number**. The number is active and ready to use.
      </Step>
    </Steps>

    <Tip>
      Don't have a number? Select **Add Number** → **Buy Number** to buy one in the dashboard.
    </Tip>
  </Tab>

  <Tab title="Bring your own SIP (BYOS)">
    Connect numbers from your own SIP trunk or carrier through an inbound and an outbound SIP gateway.

    <Tabs>
      <Tab title="Dashboard">
        This video uses Telnyx as the SIP carrier. The steps are the same for any carrier.

        <Frame>
          <video controls className="w-full aspect-video" src="https://cdn.zeroruntime.ai/zrt/docs-resource/integration_telnyx.mp4" />
        </Frame>

        <Steps>
          <Step title="Open SIP configuration">
            Open **Telephony** and select **Add Number** → **Configure SIP**.
          </Step>

          <Step title="Basic information">
            Enter a **Name** and add your phone numbers in E.164 format, for example `+14155550100`. Turn on **Shared Gateway** to use one gateway pair for all the numbers.
          </Step>

          <Step title="Inbound">
            Choose a **SIP Region**, then copy the **Inbound Gateway URL** into your carrier's settings, so calls to your numbers reach Zero Runtime.
          </Step>

          <Step title="Outbound">
            Enter your carrier's **Outbound Gateway Address** (for example `sip.my-carrier.com`), the **Transport**, and the **SIP Username** and **SIP Password** if your carrier needs them.
          </Step>

          <Step title="Activate">
            Optionally turn on **Media Encryption**, then select **Save & Activate**.
          </Step>
        </Steps>
      </Tab>

      <Tab title="API">
        ```bash theme={null}
        curl -X POST 'https://api.zeroruntime.ai/v2/sip/phone-numbers' \
          -H 'Authorization: YOUR_API_TOKEN' \
          -H 'Content-Type: application/json' \
          -d '{
            "name": "Support SIP",
            "phoneNumbers": ["+14155550100"],
            "inbound": { "sipRegion": "auto" },
            "outbound": {
              "address": "sip.my-carrier.com",
              "sipRegion": "us002",
              "transport": "tls",
              "auth": { "username": "sip-user", "password": "s3cr3t" }
            }
          }'
        ```

        See [Create number with SIP gateways](/api-reference/phone-numbers/create-number-with-sip-gateways) for every field.
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## 2. Create a routing rule

A **routing rule** links your phone numbers to an agent:

* **Inbound**: calls to the number are answered by the agent.
* **Outbound**: the agent places calls from the number, one at a time or through [batch calls](/agent-builder/telephony/batch-calls).

You need your agent's ID (for example `ag_7l0yt8`). Copy it from the chip next to **Agent** on the Agent tab, or with **Copy Agent ID** in the **⋯** menu.

<Tabs>
  <Tab title="Dashboard">
    <Frame>
      <video controls className="w-full aspect-video" src="https://cdn.zeroruntime.ai/zrt/docs-resource/routing_rules.mp4" />
    </Frame>

    <Steps>
      <Step title="Create the rule">
        Open **Telephony** → **Routing Rules** and select **Create Routing Rule**. Choose **Inbound** or **Outbound**, enter a **Routing Rule Name**, and select your phone numbers.
      </Step>

      <Step title="Add your agent">
        Under **Agent Configuration**, enter your agent's ID in **Agent Name or ID**, then select **Verify Agent ID**.
      </Step>

      <Step title="Save">
        Select **Create Rule**.
      </Step>
    </Steps>

    You can also assign existing rules from the builder. On the **Pipeline** tab, select **Phone Number**, choose the rules, and select **Assign**.

    <Note>
      Assigning a routing rule takes effect **immediately** and applies to the whole agent. It isn't part of the draft and doesn't need a commit.
    </Note>
  </Tab>

  <Tab title="API">
    Create a routing rule with your agent's ID in `agentId`:

    ```bash theme={null}
    curl -X POST 'https://api.zeroruntime.ai/v2/sip/routing-rule' \
      -H 'Authorization: YOUR_API_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "Support inbound",
        "type": "inbound",
        "phoneNumbers": ["+14155550100"],
        "agentId": "ag_7l0yt8"
      }'
    ```

    * `type` is `inbound` or `outbound`, and can't be changed later.
    * `phoneNumbers` must already be on your account.

    To point an existing rule at your agent, update only its `agentId`:

    ```bash theme={null}
    curl -X PATCH 'https://api.zeroruntime.ai/v2/sip/routing-rule/rr_8k2m1x' \
      -H 'Authorization: YOUR_API_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{ "agentId": "ag_7l0yt8" }'
    ```

    See [Create routing rule](/api-reference/routing-rules/create-routing-rule) and [Update routing rule](/api-reference/routing-rules/update-routing-rule) for every field.
  </Tab>
</Tabs>

## 3. Place a call

<Tabs>
  <Tab title="Inbound">
    Call your number from any phone. The agent answers with its [welcome message](/agent-builder/agent/system-instructions-and-greeting#welcome-message).

    If the call isn't answered, check that:

    * The agent is deployed.
    * The number has an **inbound** routing rule with your agent's ID.
    * For BYOS, your carrier sends calls to the **Inbound Gateway URL**.
  </Tab>

  <Tab title="Outbound">
    Have the agent call a number. The call uses the agent on your number's **outbound** routing rule.

    ```bash theme={null}
    curl -X POST 'https://api.zeroruntime.ai/v2/sip/call' \
      -H 'Authorization: YOUR_API_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
        "sipCallFrom": "+14155550100",
        "sipCallTo": "+14155550199",
        "routingRuleId": "rr_2554md"
      }'
    ```

    * `sipCallFrom` is your number, and `sipCallTo` is the number to call. Both are in E.164 format.
    * Leave out `routingRuleId` to use the first outbound rule on `sipCallFrom`.

    See [Make an outbound call](/api-reference/calls/make-an-outbound-call) for every field. To call a list of numbers, use [batch calls](/agent-builder/telephony/batch-calls).
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.