SIP Guide

​

Incoming SIP Calls

​

Authentication

​

IP Allowlisting

​

SIP Registration

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

​

Routing Calls

• ^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 for in-call routing.

​

Fallback Handler

{
  "callerId": "<caller_id>",
  "fromDisplayName": "<from_display_name or null>",
  "fromUri": "<from_uri>",
  "toUri": "<to_uri>",
  "sipHeaders": { "<header_name>": "<header_value>", ... }
}

• startAgentCall: Creates the call using one of your agents. The body has the same shape as the Create Agent Call 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), 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 request.
• reject: Rejects the call. sipRejectCode defaults to 603 (Decline) if omitted; message is optional and used only for logging.

​

Personalizing the Call

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

{
  "ultravox": {
    "sip": {
      "caller_id": "<caller_id>",
      "from_display_name": "<from_display_name>",
      "from_uri": "<from_uri>"
    }
  }
}

​

Outgoing SIP Calls

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

​

Outgoing SIP Parameters

​

Examples

    medium: {
      sip: {
        outgoing: {
          to: "sip:<username>@sip.linphone.org",
          from: "<company_name>"
        }
      }
    }

    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

​

Transfers

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

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

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

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

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

​

Supported Transport Protocols

​

Supported Codecs

​

Logs