Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

SIP Domains

Overview

A SIP domain is a custom DNS hostname that can accept SIP traffic for your account. If anyone makes a SIP request to that domain, for example, to “sip:alice@example.sip.twilio.com”, it will route to Twilio. When that request hits Twilio, it’s authenticated, and then Twilio requests TwiML from your server. The VoiceUrl of the SIP domain tells Twilio what URL to request.

Twilio has two built-in authentication methods for your SIP Domain: IpAccessControlLists and CredentialLists. You must have at least one mapped to your Domain or else all requests will be blocked. You may apply one or multiple of each type to each SIP Domain.

The IpAccessControlListMappings and CredentialListMappings subresources of the SIP Domain show which lists are mapped to your SIP Domain.

Resource Properties

A Domain instance resource has the following properties:

account_sid
sid<AC> Not PII

The unique id of the Account that sent this call.

api_version
string Not PII

The version of the Twilio API used to process the call.

auth_type
string Not PII

The types of authentication you have mapped to your domain. The possible values are "IP_ACL" and "CREDENTIAL_LIST". If you have both set up for your domain, both will be returned comma delimited. If you do not, have one setup for your domain, it will not be able to receive any traffic.

date_created
date_time<rfc2822> Not PII

The date that this resource was created, given as GMT in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date that this resource was last updated, given as GMT in RFC 2822 format.

domain_name
string Not PII

The unique address you reserve on Twilio to which you route your SIP traffic. Domain names can contain letters, digits, and "-".

friendly_name
string Not PII

A human readable descriptive text, up to 64 characters long.

sid
sid<SD> Not PII

A 34 character string that uniquely identifies the SIP domain in Twilio.

sip_registration
boolean Not PII

This boolean can be enabled to allow SIP Endpoints to register with this domain to receive calls.

uri
uri Not PII

The URI for this resource, relative to https://api.twilio.com

voice_fallback_method
http_method Not PII

The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.

voice_fallback_url

The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.

voice_method
http_method Not PII

The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

voice_status_callback_method
http_method Not PII

The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.

voice_status_callback_url

The URL that Twilio will request to pass status parameters (such as call ended) to your application.

voice_url

The URL Twilio will request when this domain receives a call.

Domain List Resource

The list resource allows you to view the domains in an account as well as create new domains.

List Resource URI

/2010-04-01/Accounts/{AccountSid}/SIP/Domains

List HTTP GET

GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains

Get a List of all Domains

Returns a paged list of the domains for an account.

Loading Code Sample...
      
      
          
          
          
          
        

      List HTTP POST

      Creates a new Domain and returns its instance resource. You must pick a unique domain name that ends in “.sip.twilio.com”. After creating a Domain, you must map it to an authentication method before the domain is ready to receive traffic.

      POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains
      

      You must POST at least the required DomainName to create a new Domain. We also recommend that you at least set the VoiceUrl of your Domain when creating it.

      DomainName
      Required
      post string Not PII

      The unique address you reserve on Twilio to which you route your SIP traffic. Domain names can contain letters, digits, and "-".

      AuthType
      Optional
      post string Not PII

      The types of authentication you have mapped to your domain

      FriendlyName
      Optional
      post string Not PII

      A human readable descriptive text, up to 64 characters long.

      VoiceFallbackMethod
      Optional
      post http_method Not PII

      The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.

      VoiceFallbackUrl
      Optional
      post url Not PII

      The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by VoiceUrl.

      VoiceMethod
      Optional
      post http_method Not PII

      The HTTP method Twilio will use when requesting the above Url. Either GET or POST.

      VoiceStatusCallbackMethod
      Optional
      post http_method Not PII

      The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.

      VoiceStatusCallbackUrl
      Optional
      post url Not PII

      The URL that Twilio will request to pass status parameters (such as call ended) to your application.

      VoiceUrl
      Optional
      post url Not PII

      The URL Twilio will request when this domain receives a call.

      Loading Code Sample...
          
          
              
              
              
              
            

          List HTTP PUT

          Not supported.

          List HTTP DELETE

          Not supported.

          Domain Instance Resource

          The SIP/Domain instance resource allows you to view, modify and delete a single domain.

          The instance resource is represented by the properties above.

          Instance Resource URI

          /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
          

          Instance HTTP GET

          Return a specific instance by Sid.

          GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
          

          Get an Instance of a SIP Domain

          Loading Code Sample...
              
              
                  
                  
                  
                  
                

              Instance HTTP POST

              Update the attributes of a domain.

              POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
              

              Update a SIP Domain

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    

                  Instance HTTP PUT

                  Not supported.

                  Instance HTTP DELETE

                  Delete a domain. If you have created subdomains of a domain, you will not be able to delete the domain until you first delete all subdomains of it.

                  If successful, Twilio will return an HTTP 204 response with no body.

                  DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}
                  

                  Delete a SIP Domain Instance

                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        

                      Note: IpAccessControlListMapping and CredentialListMapping API path has changed. We suggest you use new resource path going forward.

                      IpAccessControlListMappings Subresource

                      The IpAccessControlListMappings subresource contains the list of IpAccessControlList instances associated with this domain. If an INVITE is received for a domain, the source IP address must be in one of the mapped lists for the INVITE to be accepted.

                      IpAccessControlListMappings Resource URI

                      /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/Auth/Calls/IpAccessControlListMappings
                      

                      IpAccessControlListMappings Resource Properties

                      An IpAccessControlListMappings resource is represented by the following properties:

                      Property Description
                      Sid A 34 character string that uniquely identifies an IpAccessControlList you have mapped to the domain
                      AccountSid The unique id of the Account that responsible for this resource.
                      FriendlyName A human readable descriptive text, up to 64 characters long.
                      DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
                      DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
                      Uri The URI for this resource, relative to https://api.twilio.com

                      IpAccessControlListMappings HTTP GET

                      Return the IpAccessControlListMappings that are associated with this domain.

                      GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/Auth/Calls/IpAccessControlListMappings
                      

                      Return a specific instance by Sid.

                      Get a Specific SIP Domain Instance

                      Loading Code Sample...
                          
                          
                              
                              
                              
                              
                            

                          IpAccessControlListMappings HTTP POST

                          Map an IpAccessControlList to this domain.

                          POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/Auth/Calls/IpAccessControlListMappings
                          

                          POST Parameters

                          The following parameters are required in your POST to IpAccessControlListMappings:

                          Parameter Description
                          IpAccessControlListSid The Sid of the IpAccessControlList that you want to associated with this domain. Once associated, Twilio will start authenticating access to the domain against this list.
                          Loading Code Sample...
                              
                              
                                  
                                  
                                  
                                  
                                

                              IpAccessControlListMappings HTTP PUT

                              Not supported.

                              IpAccessControlListMappings HTTP DELETE

                              Remove a mapping from this domain.

                              DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{DomainSid}/Auth/Calls/IpAccessControlListMappings/{ALSid}
                              

                              Delete IpAccessControlList Mapping

                              Loading Code Sample...
                                  
                                  
                                      
                                      
                                      
                                      
                                    

                                  CredentialListMappings List Subresource

                                  The CredentialListMappings subresource represents the CredentialLists instances associated with this domain. You can associate different CredentialLists for calls and registrations. In case of calls, if an INVITE is received for a domain with a Credential List mapped to it, Twilio will challenge the request. Your system will need to authenticate with a username and password. The username and password must be in one of the mapped lists for the INVITE to be accepted.

                                  It's a similar case with registration. If a REGISTER is received for a domain with a Credential List mapped to it, Twilio will challenge the request. Your system will need to authenticate with a username and password. The username and password must be in one of the mapped lists for the REGISTER to be accepted.

                                  Resource URI for Calls

                                  /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Calls/CredentialListMappings

                                  Resource URI for Registrations

                                  /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Registrations/CredentialListMappings
                                  

                                  CredentialListMappings Resource Properties

                                  A CredentialListMappings resource is represented by the following properties:

                                  Property Description
                                  Sid A 34 character string that uniquely identifies a CredentialList you have mapped to the domain.
                                  AccountSid The unique id of the Account that responsible for this resource.
                                  FriendlyName A human readable descriptive text, up to 64 characters long.
                                  DateCreated The date that this resource was created, given as GMT in RFC 2822 format.
                                  DateUpdated The date that this resource was last updated, given as GMT in RFC 2822 format.
                                  Uri The URI for this resource, relative to https://api.twilio.com

                                  CredentialListMappings HTTP GET

                                  Get the user lists mapped to this domain that is used for calls.

                                  GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Calls/CredentialListMappings
                                  

                                  Get the user lists mapped to this domain that is used for registration.

                                  GET /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Calls/CredentialListMappings

                                  Get a Credential List Mapping (calls)

                                  Loading Code Sample...
                                      
                                      
                                          
                                          
                                          
                                          
                                        

                                      CredentialListMappings HTTP POST

                                      Map a CredentialList to the domain (used for calls).

                                      POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Calls/CredentialListMappings

                                      Map a CredentialList to the domain (used for registrations).

                                      POST /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Registrations/CredentialListMappings
                                      

                                      POST Parameters

                                      The following parameters are required in your POST to CredentialListMappings:

                                      Parameter Description
                                      CredentialListSid The Sid of the CredentialList that you want to associate with this domain. Once associated, Twilio will start authenticating access to the domain against this list.
                                      Loading Code Sample...
                                          
                                          
                                              
                                              
                                              
                                              
                                            

                                          CredentialListMappings HTTP PUT

                                          Not supported.

                                          CredentialListMappings HTTP DELETE

                                          Calls

                                          DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Calls/CredentialListMappings/{CLSid}

                                          Registrations

                                          DELETE /2010-04-01/Accounts/{AccountSid}/SIP/Domains/{SipDomainSid}/Auth/Registrations/CredentialListMappings/{CLSid}
                                          

                                          Delete a Credential List Mapping

                                          Remove a CredentialListMapping from a domain for calls

                                          Loading Code Sample...
                                              
                                              
                                                  
                                                  
                                                  
                                                  
                                                

                                              Need some help?

                                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                                              Loading Code Sample...