> ## 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. 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. ## Incoming SIP Calls In the default, easy setup for incoming SIP, Ultravox will automatically create calls on your behalf in response to SIP INVITE requests. To facilitate this, you'll need to create an agent to receive calls before you set up incoming SIP. ### Authentication Ultravox supports two setups for authenticating 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. #### 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. See [Routing Calls](#routing-calls) for how to customize this. #### 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. Registrations are not associated with a particular agent, so you'll also need to configure routing rules as described [below](#routing-calls). ### Routing Calls You can configure how calls get routed between your agents using regex matching on the to address of incoming SIP invites. By default, all calls to `agent_{agent_id}@{your_account_sip_domain}` will be routed to the specified agent as long as that agent is allowed to receive calls (including via `allowAllAgents`). If you'd like one of your agents to receive calls using some other address, add an entry to `allowedAgents` with an appropriate regex (or update the existing entry for your agent). For example: * `^sales$` matches calls sent to `sales@your_sip_domain`. (This is especially useful when using registration-based authentication.) * `^15551234567$|^15557654321$` matches calls sent to the phone numbers `+1-555-123-4567` and `+1-555-765-4321`. * `.*` matches calls sent to any address, allowing for a simple catch-all agent. Such an agent could be used with [transfers](/telephony/call-transfers) for in-call routing. The `allowedAgents` list of regexes is applied in order, with an implicit entry for `allowAllAgents` applied at the end if set. The call will use whichever agent is specified by the first matching regex and will be created automatically on your behalf. If no regexes match, the call will be sent to your [fallback handler](#fallback-handler) if configured and rejected otherwise. #### Fallback Handler For fully customized call routing, you can configure a fallback handler webhook on your [SIP configuration](/api-reference/sip/sip-partial-update) to make dynamic per-call routing decisions. This is an advanced feature and requires more configuration and maintenance than the default routing behavior, but gives you maximum control over how incoming SIP calls are handled. When Ultravox receives an incoming SIP invite that does not match any of your agent allowances (including `allowAllAgents` if it is set), it will POST to your fallback handler URL with the following body: ```json theme={null} { "callerId": "", "fromDisplayName": "", "fromUri": "", "toUri": "", "sipHeaders": { "": "", ... } } ``` The request is signed using the same HMAC-SHA256 scheme as outbound webhooks; see [Securing Webhooks](/webhooks/securing-webhooks) for how to verify it. The shared secrets for your fallback handler are configured alongside its URL (a strong secret is generated for you if you don't supply one). Your handler must respond promptly with HTTP 200 and a JSON body matching the [SIP Fallback Handler Response](/api-reference/schema/sip-fallback-handler-response) schema. Exactly one of the following fields must be set: * `startAgentCall`: Creates the call using one of your agents. The body has the same shape as the [Create Agent Call](/api-reference/agents/agents-calls-post) request, with an additional required `agentId` field identifying which agent to use. Any `templateContext` you provide is merged with the SIP-derived context (see [below](#personalizing-the-call)), with your values taking precedence over the header-derived context. The `ultravox` key in `templateContext` is reserved for Ultravox-provided context (such as `ultravox.sip.caller_id`) and will be overwritten if you set it. * `startCall`: Creates the call inline without an agent. The body has the same shape as the [Create Call](/api-reference/calls/calls-post) request. * `reject`: Rejects the call. `sipRejectCode` defaults to `603` (Decline) if omitted; `message` is optional and used only for logging. In either call creation case, any `medium` set will be replaced with incoming SIP. If your handler times out, is unreachable, returns a non-2XX status, or returns a malformed/invalid response, Ultravox will reject the SIP call (with code `504` for timeouts and `502` otherwise). Even when your handler returns a valid response, the call may still be rejected if Ultravox is unable to create it. For example, an invalid call configuration is rejected with `488` and a temporary lack of capacity or rate limit is rejected with `503`. ### 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 interpreted 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": "", "from_display_name": "", "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:@", from: "", username: "", password: "" } } } ``` When you create the call, Ultravox will automatically send a SIP invite using the properties provided. ### Outgoing SIP Parameters The target SIP URL to which the Ultravox call will connect. Examples: `sip:username@domain`, `sip:+15551234567@carrier.com` The caller identifier. Must conform to what your SIP trunk allows. Optional. Username for connecting to your SIP trunk. Optional. Password for connecting to your SIP trunk. ### Examples ```js Example: Creating an Outgoing SIP Call to Linphone theme={null} medium: { sip: { outgoing: { to: "sip:@sip.linphone.org", from: "" } } } ``` ```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" } } } ``` ## SIP Billing Serving SIP calls requires additional infrastructure (provided by our SIP partner, Voximplant). Consequently, SIP calls incur costs for SIP minutes in addition to the regular cost of call minutes. Like call minutes, SIP minutes are billed per-deciminute (i.e. six second increments), rounded up to the nearest deciminute. Unlike call minutes, **SIP minutes can be billed even when your agent is not connected to a user** — for example, transfer legs that keep running after your agent leaves the call. **Ringing time is not billed** though: an outgoing call only begins accruing SIP minutes once it is answered, so a call that is never answered incurs no SIP minutes. See [https://ultravox.ai/pricing](https://ultravox.ai/pricing) for current rates for SIP minutes. The examples below illustrate how different call scenarios affect SIP billing. Red blocks correspond to segments of the call that count toward the SIP duration, grey blocks (ringing) are not billed, and the blue block shows when your agent is connected (i.e. regular call minutes). ```mermaid theme={null} gantt title Typical outgoing call dateFormat x axisFormat %M:%S.%L section SIP Call Ringing :done, 0, 20000ms Talking to Agent :crit, 120000ms section Agent Connected :active, 20000, 120000ms ``` ```mermaid theme={null} gantt title Typical incoming call dateFormat x axisFormat %M:%S.%L section SIP Call Talking to Agent :crit, 0, 120000ms section Agent Connected :active, 0, 120000ms ``` ### Transfers Transfers often involve additional call legs that may increase the effective SIP duration of your call at double speed or extend your call duration well beyond the duration during which your agent is active. Some examples follow: * **Cold transfer with SIP REFER**: If the REFER is successful, all Ultravox infrastructure is removed from the call, so the SIP clock stops immediately. The SIP billing clock never runs at double rate for REFER cold transfers. ```mermaid theme={null} gantt title Referred cold transfer (outgoing) dateFormat x axisFormat %M:%S.%L section SIP Call Ringing :done, 0, 20000ms Talking to Agent :crit, 60000ms Refer ringing :crit, 10000ms Talking to Transfer Target -> :crit, 0ms section Agent Connected :active, 20000, 70000ms ``` * **Bridged cold transfer**: A second call leg is created for the transfer target, so SIP minutes accumulate at double the normal rate while both calls are active. If the transfer is accepted, both legs remain active and continue billing even after the agent leaves the call. ```mermaid theme={null} gantt title Bridged cold transfer (outgoing) dateFormat x axisFormat %M:%S.%L section Initial Call Ringing :done, 0, 20000ms Talking to Agent :crit, 30000ms On Hold :crit, 10000ms Talking to Transfer Target :crit, 300000ms section Transfer Call Ringing :done, 50000, 10000ms Talking to Initial User :crit, 300000ms section Agent Connected :active, 20000, 40000ms ``` * **Warm transfer with REFER**: During the warm transfer process, a second call leg is created to connect the agent with the human operator and thus SIP minutes temporarily accumulate at double the normal rate. If the REFER is successful, all Ultravox infrastructure is removed from the call and thus the SIP clock stops immediately. If the REFER fails (and bridge fallback is not selected), the agent reconnects with the original user and continues the conversation as if the transfer were rejected. The SIP clock goes back to running at the normal rate as there is only one call leg remaining. ```mermaid theme={null} gantt title Referred warm transfer (outgoing) dateFormat x axisFormat %M:%S.%L section Initial Call Ringing :done, 0, 20000ms Talking to Agent :crit, 30000ms On Hold :crit, 50000ms Talking to Transfer Target -> :crit, 0ms section Transfer Call Ringing :done, 50000, 10000ms Talking to Agent :crit, 40000ms Talking to Initial User -> :crit, 0ms section Agent Connected :active, 20000, 80000ms ``` ```mermaid theme={null} gantt title Rejected warm transfer (outgoing) dateFormat x axisFormat %M:%S.%L section Initial Call Ringing :done, 0, 20000ms Talking to Agent :crit, 30000ms On Hold :crit, 50000ms Talking to Agent :crit, 30000ms section Transfer Call Ringing :done, 50000, 10000ms Talking to Agent :crit, 40000ms section Agent Connected :active, 20000, 110000ms ``` * **Bridged warm transfer**: A second call leg is created to connect the agent with the human operator, so SIP minutes accumulate at double the normal rate while both calls are active. If the transfer is accepted, both legs remain active and continue billing even after the agent leaves the call. ```mermaid theme={null} gantt title Bridged warm transfer (outgoing) dateFormat x axisFormat %M:%S.%L section Initial Call Ringing :done, 0, 20000ms Talking to Agent :crit, 30000ms On Hold :crit, 50000ms Talking to Transfer Target :crit, 300000ms section Transfer Call Ringing :done, 50000, 10000ms Talking to Agent :crit, 40000ms Talking to Initial User :crit, 300000ms section Agent Connected :active, 20000, 80000ms ``` * **Warm transfer with TRY\_REFER**: This will attempt to behave as in the REFER case, but will fallback to the bridged case (and thus cause additional SIP costs) if the REFER fails. Ringing is no longer billed
The SIP clock for a given call leg only starts once that leg is answered, so ringing time (shown in grey above) is never counted toward your SIP minutes. This applies to both the initial call and any transfer legs. However ring time for the initial call leg used to be billed, so you may see that on invoices through July 2026. Unfortunately we cannot apply this cost reduction retroactively. ## 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:@:5060;transport=tcp` | | TLS | `sip:@: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.