Outbound - Receiving SIP from Twilio

Expand image

With Programmable Voice SIP, there are a couple of ways to connect your Twilio application to your SIP communications infrastructure.

1. Your application can use Twilio's REST APIs to initiate a new SIP call towards your SIP communications infrastructure
2. An inbound PSTN or SIP call can invoke your application which can respond using the <Sip> noun of the <Dial> verb, to establish a call with your SIP endpoint.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Dial>
4
    <Sip>sip:jack@example.com</Sip>
5
  </Dial>
6
</Response>

To start receiving SIP from Twilio towards your communications infrastructure, there is one major step you need to follow:

To ensure that your communications infrastructure doesn't block communication, you must update your allowed list of IP Addresses. See here for details.

Now that Twilio's IPs are allowed in your system, your Twilio app can begin sending SIP traffic to your SIP communications infrastructure. If you are new to Twilio, it's best to start out with <Sip> noun of the <Dial> for your first app. See here for details.

Twilio allows you to send custom SIP headers as part of the outgoing initial INVITE request.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:jack@example.com?x-myotherheader=bar</Sip>
5
    </Dial>
6
</Response>

You can also send multiple param & value pairs as part of the same header, as well as combine multiple headers by separating them with & between each. For example,

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:+14158675309@your.domain?X-customName=Bob%2CShield%2BTitle%2DManager&amp;X-otherHeader=true</Sip>
5
    </Dial>
6
</Response>

Twilio allows you to pass the custom header as part of Dial action URL or the call screening URL. On a successful call setup (when a 200 OK SIP response is returned) any X-headers in the 200 OK message are posted in the format SipHeader_X-headername=headervalue and in the final SIP response message (any 4xx or 5xx message or the final BYE/200) are posted in the format DialSipHeader_X-headername=headervalue.

In order to pass the contextual information of the caller, customers use UUI (User-to-User Information) header in SIP request messages. Twilio allows you to pass UUI header as part of <Sip> request.

Note: For non X-headers like UUI action and call screening URL are not supported.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:jack@example.com?User-to-User=123456789%3Bencoding%3Dhex&amp;x-myotherheader=bar</Sip>
5
    </Dial>
6
</Response>

UUI headers can also send with "X-" prefix. See below...

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:jack@example.com?X-User-to-User=123456789%3Bencoding%3Dhex&amp;x-myotherheader=bar</Sip>
5
    </Dial>
6
</Response>

In order to pass other contextual information, Twilio allows you to pass the following standard SIP headers as part of an outbound SIP call:

• Remote-Party-ID
• P-Preferred-Identity
• P-Called-Party-ID

Note: For these headers, action and call screening URL are not supported.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:bob@example.com?x-foo%3Dbar&amp;User-To-User=foobar&amp;Remote-Party-ID=%3Csip%3Afoo%40example.com%3E%3Bparty%3Dcalling&amp;P-Preferred-Identity=%3Csip%3Afoo%40example.com%3E&amp;P-Called-Party-ID=%3Csip%3Afoo%40example.com%3E</Sip>
5
    </Dial>
6
</Response>

To specify the geographic edge from which Twilio will send SIP-out traffic towards your communication infrastructure, you must include the edge parameter in your SIP URI. For example, if the edge=frankfurt parameter is included in your SIP URI, Twilio will send the SIP traffic from the Frankfurt, Germany edge:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Sip>sip:alice@example.com;edge=frankfurt</Sip>
5
    </Dial>
6
</Response>

If the edge parameter is not specified, Twilio will send SIP-out traffic from the North America, Virginia edge.

Notes:

• You must make sure you allow the IP addresses of the Twilio edge for SIP signaling and RTP media traffic.
• The edge parameter is not supported when calling SIP registered endpoints, the parameter will be ignored if present. SIP-out traffic will always be sent from the Twilio edge the SIP endpoint registered with.

This guide teaches the basics required for the following use cases:

You can use this guide to create a programmatic outbound call center that dials customers or agents via SIP for telemarketing or support.

To learn more advanced features that you can use with outbound call centers, see Voice outbound call centers.

Together with the gather guide, you can use this guide to automate outbound SIP calls that gather user input using the keypad for self-service automation.

To learn more advanced features that you can use with self-service automation, see Voice self-service automation.

You can use this guide to capture the audio of your outbound SIP sessions for AI-driven analysis, allowing you to send raw audio to machine learning models for real-time transcription.

To learn more advanced features that you can use with AI or ML transcription, see Voice AI and ML transcription.

After following this guide, you can initiate a SIP session programmatically from Twilio to your existing communications infrastructure. You might also have customized your SIP INVITE requests with custom X-headers, UUI information, and specific geographic edge routing.

Explore the following guides to build on what you've learned in this guide:

• Gather user input: Use the <Gather> verb to collect DTMF tones during a SIP call.

Find reference documentation for the topics on this page.

• TwiML™ Voice: <Sip>
• TwiML™ Voice: <Dial>
• Twilio edge locations
• Programmable Voice SIP resource