https://www.twilio.com/docs/sip/sip-twiml
SIP and TwiML Interaction
SIP calls interact with TwiML in virtually the same way as inbound phone calls and Client. When Twilio receives an incoming INVITE to your Twilio SIP domain and authenticates it, it passes a 180 Ringing SIP response code to your SIP endpoint. Twilio then looks up the URLs associated with your SIP domain and makes an HTTP request to the VoiceUrl.
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
SipUsername The username given when authenticating the request, if Credential List is the authentication method.
SipCallId The Call-Id of the incoming INVITE
SipSourceIp The IP Address the incoming INVITE came from.
SipHeader_ X- headers in the incoming INVITE are passed as SipHeader_ params, where 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 , , , , or , Twilio sends a 200 OK SIP response code to your endpoint and establishes the call.
If your application passes back a verb, the redirect document is requested and Twilio continues in the 180 Ringing state.
If your application sends back a , Twilio returns a 486 Busy SIP response code and the call setup is denied. If your application sends back a , Twilio returns a 603 Rejected SIP response code and the call setup is denied.
Passing SIP Headers to your TwiML application
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.
Receiving SIP from Twilio
Overview
With Twilio SIP, it’s simple connect to your SIP endpoints from a Twilio app. You can use TwiML or the REST API to initiate SIP sessions into your existing SIP gateways and IP PBXs. Take an inbound phone call and turn into a SIP call with TwiML. If you don’t have an existing phone call, use the REST API to start a new SIP call to your system.
How it works
To receive SIP from Twilio, use the noun of the verb to initiate a connection to your system. Twilio will send an INVITE to the URI you set in the noun and attempt to establish a SIP session. Use this to take any existing phone call in Twilio and route it to your SIP endpoint.
To initiate a SIP connection without having an existing call, you can use the REST APIto make SIP calls. This is just like making regular phone calls on Twilio, but instead of passing a phone number to dial, you just pass the URI to which we should send an INVITE.
Getting Started
To start receiving SIP to Twilio, you need to go through these steps:
Whitelist Twilio’s SIP and Media IPs on your SIP Endpoint
Twilio’s SIP IPs need to be whitelisted by you so that we can send SIP traffic back to your endpoint. You will also need to whitelist port 10000 to 20000 for RTP traffic so that the audio of the calls can reach your system.
2. Start receiving SIP from Twilio
Now that Twilio’s IPs are whitelisted in your system, your Twilio app can begin sending SIP traffic to your endpoints. If new to Twilio, it’s best to start out with noun of the verb for your first app.
SIP Headers
The following headers will always be added by Twilio to the outgoing initial INVITE request:
X-Twilio-CallSid: A unique identifier for this call, generated by Twilio. It is 34 characters long, and always starts with the letters CA.
X-Twilio-AccountSid: Your Twilio account SID. It is 34 characters long, and always starts with the letters AC.
X-Twilio-ApiVersion: The Twilio API version being used for this call session.
SIP X-Headers passed back from your SIP Endpoint
In order to better integrate with remote SIP applications, Twilio's SIP connections can read headers that are returned in the response messages. Twilio will read any headers beginning with the X- prefix and copy them to either the Dial action URL or the call screening URL, in the format DialSipHeader_X-headername=headervalue.
On a successful call setup (when a 200 OK SIP response is returned) any X-headers on the 200 OK message are posted to the call screening URL. Headers on the final SIP response message (any 4xx or 5xx message or the final BYE/200) are posted to the Dial action URL.