# Source: https://docs.ultravox.ai/telephony/sip.md

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

# SIP Guide

> Create incoming & outgoing SIP calls with Ultravox agents.

<Danger>
  <b>SIP Billing Starts November 10, 2025</b>

  <br />

  Calls via the SIP medium will start to incur additional charges on Monday, November 10, 2025.

  See [https://ultravox.ai/pricing](https://ultravox.ai/pricing) for details.
</Danger>

Session Initiation Protocol (SIP) enables Ultravox agents to connect with your existing phone systems and SIP clients. This guide explains how to set up both incoming and outgoing SIP calls with Ultravox agents.

## SIP Quickstart

The fastest way to start using SIP with Ultravox:

<Steps>
  <Step title="Create an Agent">Create an agent using the [Ultravox Realtime console](https://app.ultravox.ai/agents).</Step>
  <Step title="Create a SIP Call">Create an agent call using the [Create Agent Call](/api-reference/agents/agents-calls-post) API and use the `sip` medium.</Step>
</Steps>

<Note>
  <b>API Key Required</b>

  <br />

  Make sure you have an Ultravox API key. You can create one in the [console](https://app.ultravox.ai/settings/).
</Note>

## Incoming SIP Calls

For incoming calls, you can configure Ultravox to accept calls from your SIP system then send a sip invite directly to your agent. The SIP invite will create an Ultravox call and connect to it, no other requests required.

Ultravox supports two setups for incoming SIP calls: IP allowlisting and SIP registration. IP allowlisting works well with dedicated PBX systems, while SIP registration is recommended for cloud PBX setups.

In either setup, you can choose to allow incoming calls to all of your agents or to specific agents only. Calls will be created automatically from your agent's call template when a SIP invite is received.

By default, calls must be directed to the sip user `agent_{agent_id}` to reach your agent, but you can override this with your own regex matching. The regex for your agents will be checked in order with the first matching agent used for the call. If none match, the global `agent_{agent_id}` will be used if allowAllAgents is enabled. Otherwise (or if that doesn't match either), the call will be rejected.

### IP Allowlisting

To set up IP Allowlisting, use the [sip configuration API](/api-reference/sip/sip-partial-update) to add your SIP system's public IP addresses to the `allowedCidrRanges` list. Entries in this list must be IPv4 [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges, e.g. `0.0.0.0/0` for any IP address (not recommended) or `91.200.160.14/32` for the single `91.200.160.14` IP address.

Once your SIP system's IP address(es) are allowed, you can have them send SIP invites to your agents using the pattern `agent_{agent_id}@{your_account_sip_domain}` by default. The value for `{your_account_sip_domain}` is available when you [view your SIP configuration](/api-reference/sip/sip-get). The user portion of the SIP address may be overridden by setting your own per-agent regex.

### SIP Registration

In the registration model, Ultravox acts as a SIP client (similar to a softphone) and registers with your SIP server as the user you specify. To set this up, you'll need to create a user in your PBX, configure your PBX to send relevant calls to that user, and then [create a registration](/api-reference/sip/sip-registrations-create) for that user in Ultravox.

When creating a registration, you'll need to provide the following information:

* `username`: The username of the user you created in your PBX.
* `password`: The password for that user.
* `proxy`: The domain or IP address of your SIP server.

In this case, you'll most likely want to alter the regex for your agents since the to address on invites is unlikely to be `agent_{agent_id}`.
For example, if your PBX sends calls to `sip:sales@your_sip_domain`, you could set the regex for your sales agent to `^sales$`. Similarly, if your SIP server interacts with PSTN, you could have your agent answer calls to +1-555-123-4567 and +1-555-765-4321 by setting the regex to `^15551234567$|^15557654321$`.

### Personalizing the Call

Many parts of an agent can use context to personalize a call. (See [Call Template Configuration](/agents/building-and-editing-agents#call-template-configuration).) You can use SIP headers to populate template context for incoming SIP calls. Each header value is interpretted as JSON to allow for complex values.

For example including the headers `X-Customer-Name: Bob` and `X-Complex-Value: {"subkey": "value"}` becomes `{"customer_name": "Bob", "complex_value": {"subkey": "value"}}`.

In addition to headers you send, Ultravox will automatically add the following context values for incoming SIP calls, provided they are allowed by your agent's context schema:

* `ultravox.sip.caller_id`: The caller id presented for the incoming call, typically a phone number.
* `ultravox.sip.from_display_name`: The display name of the caller, often the name of a person or business if known and a phone number otherwise.
* `ultravox.sip.from_uri`: The full SIP URI of the caller.

If your agent's context allows additional properties (or allows these properties explicitly), the added context will be structured as:

```json  theme={null}
{
  "ultravox": {
    "sip": {
      "caller_id": "<caller_id>",
      "from_display_name": "<from_display_name>",
      "from_uri": "<from_uri>"
    }
  }
}
```

## Outgoing SIP Calls

For outgoing calls, you can create a SIP call with Ultravox Realtime [Create Agent Call](/api-reference/agents/agents-calls-post) or [Create Call](/api-reference/calls/calls-post) endpoints using the `sip` medium with `outgoing` property.

```js  theme={null}
medium: {
  sip: {
    outgoing: {
      to: "sip:<destination>@<sip_domain>",
      from: "<your_identifier>",
      username: "<authentication_username>",
      password: "<authentication_password>"
    }
  }
}
```

When you create the call, Ultravox will automatically send a SIP invite using the properties provided.

### Outgoing SIP Parameters

<ParamField body="to" type="string" required>
  The target SIP URL to which the Ultravox call will connect.

  Examples:
  `sip:username@domain`, `sip:+15551234567@carrier.com`
</ParamField>

<ParamField body="from" type="string" required>
  The caller identifier. Must conform to what your SIP trunk allows.
</ParamField>

<ParamField body="username" type="string">
  Optional. Username for connecting to your SIP trunk.
</ParamField>

<ParamField body="password" type="string">
  Optional. Password for connecting to your SIP trunk.
</ParamField>

### Examples

```js Example: Creating an Outgoing SIP Call to Linphone theme={null}
    medium: {
      sip: {
        outgoing: {
          to: "sip:<username>@sip.linphone.org",
          from: "<company_name>"
        }
      }
    }
```

```js Example: Creating an Outgoing SIP Call using a Twilio trunk theme={null}
    medium: {
      sip: {
        outgoing: {
          to: "+15551234567@trunkname.pstn.twilio.com",
          from: "+15557654321",  // Some phone number you've purchased from Twilio
          username: "authorized_user",  // A user you've created in Twilio allowed to use this number
          password: "password_for_authorized_user"
        }
      }
    }
```

## Supported Transport Protocols

By default, UDP is used as the SIP transport protocol. You may optionally use TCP and/or TLS by explicitly adding a port and transport parameter to the target SIP URL.

| Protocol | How to Use in SIP URL                               |
| -------- | --------------------------------------------------- |
| UDP      | Default. No action required.                        |
| TCP      | `sip:<destination>@<sip_domain>:5060;transport=tcp` |
| TLS      | `sip:<destination>@<sip_domain>:5060;transport=tls` |

## Supported Codecs

Ultravox Realtime supports wideband (AKA "HD audio") and narrowband SIP via various codecs:

| Codec              | Audio Quality      |
| ------------------ | ------------------ |
| G.722              | HD (16kHz)         |
| G.722.1            | HD (16kHz)         |
| G.722.2            | HD (16kHz)         |
| Opus               | Premium HD (48kHz) |
| G.711 (PCMU/u-law) | Standard (8kHz)    |
| G.711 (PCMA/a-law) | Standard (8kHz)    |
| iLBC               | Standard (8kHz)    |

Using any other codec will cause calls to fail.

## Logs

Once a call has ended, you can see SIP logs for the call using the [sip logs](/api-reference/calls/calls-sip-logs-get) endpoint.