SIP and TwiML interaction
Learn how SIP calls interact with TwiML, allowing Twilio to pass SIP headers as parameters to your application and execute instructions based on SIP response codes. This interaction acts as the bridge between your SIP infrastructure and Twilio's programmable logic.
You can use this guide for self-service automation, inbound and outbound contact centers, and PSTN connectivity.
See Related reference documentation to learn more about the TwiML and SIP elements used in this guide.
When requesting your TwiML, Twilio will pass several parameters to your application from the original SIP call:
| Parameter Name | Description | |
|---|---|---|
| To | The URI of the INVITE | |
| From | "From" header passed in the INVITE | |
| SipDomain | The Twilio SIP Domain to which the INVITE was sent | |
| SipDomainSid | The Originating Twilio SIP Domain SID | |
| SipCallId | The Call-Id of the incoming INVITE | |
| SipSourceIp | The IP Address the incoming INVITE came from. | |
| SipHeader_<name> | X- headers in the incoming INVITE are passed as SipHeader_<name> parameters, where <name> is the header key. You can receive multiple of these. |
Upon receiving a response with valid TwiML, Twilio begins executing the instructions contained within the TwiML. If the instructions are <Say>, <Play>, <Record>, <Dial>, or <Gather>, Twilio sends a 200 OK SIP response code to your endpoint and establishes the call.
If your application passes back a <Redirect> verb, the redirect document is requested and Twilio continues in the 180 Ringing state.
If your application sends back a <Reject reason="busy">, Twilio returns a 486 Busy SIP response code and the call setup is denied. If your application sends back a <Reject reason="rejected">, Twilio returns a 404 Not Found response code and the call setup is denied.
If your TwiML instructions use <Refer>, Twilio will generate a SIP REFER toward the customer's PBX and handle any NOTIFY messages. The transfer is entirely handled by the customer's PBX.
Note: If <Refer> is the last verb and has no action URL the call leg will be ended, otherwise, TwiML execution continues as normal.
Interested in learning more about SIP REFER see here.
In order to better integrate with remote SIP applications, Twilio's SIP connections can read headers in the initial INVITE and pass them to your application. Twilio will read any headers beginning with the X- prefix and pass them in the TwiML HTTP callback in the format SipHeader_X-headername=headervalue. This allows your application to make programmatic decisions about what to do with a call.
This guide covers a feature that can support the following use cases:
You can use the interaction between SIP and TwiML to automate outbound calls that gather user input from your SIP endpoint. For example, you can use the <Gather> verb to collect DTMF tones from a caller and route them through your PBX.
To learn more advanced features that you can use with self-service automation, see Voice self-service automation.
You can use SIP and TwiML to manage incoming calls to your Twilio SIP domain, using headers to make programmatic routing decisions for your agents.
To learn more advanced features that you can use with inbound contact centers, see Voice inbound contact center.
You can use TwiML instructions like <Dial> and <Refer> to manage call flows originating from your SIP-based outbound dialers.
To learn more advanced features that you can use with outbound call centers, see Voice outbound contact center.
You can use SIP and TwiML to bridge your existing SIP network with the public switched telephone network (PSTN), passing critical headers between the two environments.
To learn more advanced features that you can use with PSTN connectivity, see Voice PSTN connectivity.
Explore the following guides to build on what you've learned in this guide:
- Gather user input via keypad (DTMF tones): Learn more about collecting input from callers during a SIP session.