Menu

Expand
Rate this page:

Service

A Service is the top-level scope of all other resources in the REST API. It owns Sessions and Proxy Numbers (e.g. Phone Numbers and Short Codes) for a Proxy application. Services allow you to:

  • Create multiple environments (e.g. dev, stage, and prod) under the same Twilio account with segregated data
  • Scope access to resources through the REST API
  • Configure behavior of the Service per instance

Service properties

Resource Properties in REST API format
sid
sid<KS> Not PII

The unique string that we created to identify the Service resource.

unique_name
string Not PII

An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. Supports UTF-8 characters. This value should not have PII.

account_sid
sid<AC> Not PII

The SID of the Account that created the Service resource.

chat_instance_sid
sid<IS> Not PII

The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.

callback_url
url Not PII

The URL we call when the interaction status changes.

default_ttl
integer Not PII

The default ttl value for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0 indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl value.

number_selection_behavior
enum:number_selection_behavior Not PII

The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky or avoid-sticky. prefer-sticky means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.

geo_match_level
enum:geo_match_level Not PII

Where a proxy number must be located relative to the participant identifier. Can be: country, area-code, or extended-area-code. The default value is country and more specific areas than country are only available in North America.

intercept_callback_url
url Not PII

The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.

out_of_session_callback_url
url Not PII

The URL we call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.

date_created
date_time<iso8601> Not PII

The ISO 8601 date and time in GMT when the resource was created.

date_updated
date_time<iso8601> Not PII

The ISO 8601 date and time in GMT when the resource was last updated.

url
url Not PII

The absolute URL of the Service resource.

links
uri_map Not PII

The URLs of resources related to the Service.

Note on Proxy Numbers associated with Services

A Twilio Phone Number or Short Code associated with a Proxy Service cannot be associated with other Proxy Services in the same account.

Learning about Proxy Number management

A Proxy Service contains a lot of detailed configuration options regarding Proxy Number selection logic. If you'd like to learn more about how Proxy handles Proxy Numbers, check out the Proxy Number Management explanation page.

Create a Service resource

post
https://proxy.twilio.com/v1/Services

Create a new Service.

Parameters
Parameters in REST API format
unique_name
Required
post string Not PII

An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII.

default_ttl
Optional
post integer Not PII

The default ttl value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0 indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl value.

callback_url
Optional
post url Not PII

The URL we should call when the interaction status changes.

geo_match_level
Optional
post enum:geo_match_level Not PII

Where a proxy number must be located relative to the participant identifier. Can be: country, area-code, or extended-area-code. The default value is country and more specific areas than country are only available in North America.

number_selection_behavior
Optional
post enum:number_selection_behavior Not PII

The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky or avoid-sticky and the default is prefer-sticky. prefer-sticky means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.

intercept_callback_url
Optional
post url Not PII

The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.

out_of_session_callback_url
Optional
post url Not PII

The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.

chat_instance_sid
Optional
post sid<IS> Not PII

The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.

Example 1
Loading Code Sample...
        
        
        

        Create Service

        Fetch a Service resource

        get
        https://proxy.twilio.com/v1/Services/{Sid}

        Retrieve a single Service.

        Parameters
        Parameters in REST API format
        sid
        Path
        get sid_like<KS> Not PII

        The Twilio-provided string that uniquely identifies the Service resource to fetch.

        Example 1
        Loading Code Sample...
              
              
              

              Fetch Service

              Read multiple Service resources

              get
              https://proxy.twilio.com/v1/Services

              Retrieve a list of all Services for a given account.

              Example 1
              Loading Code Sample...
                    
                    
                    

                    Read Service

                    Update a Service resource

                    post
                    https://proxy.twilio.com/v1/Services/{Sid}

                    Update a Service's configuration.

                    Parameters
                    Parameters in REST API format
                    sid
                    Path
                    post sid<KS> Not PII

                    The Twilio-provided string that uniquely identifies the Service resource to update.

                    unique_name
                    Optional
                    post string Not PII

                    An application-defined string that uniquely identifies the resource. This value must be 191 characters or fewer in length and be unique. This value should not have PII.

                    default_ttl
                    Optional
                    post integer Not PII

                    The default ttl value to set for Sessions created in the Service. The TTL (time to live) is measured in seconds after the Session's last create or last Interaction. The default value of 0 indicates an unlimited Session length. You can override a Session's default TTL value by setting its ttl value.

                    callback_url
                    Optional
                    post url Not PII

                    The URL we should call when the interaction status changes.

                    geo_match_level
                    Optional
                    post enum:geo_match_level Not PII

                    Where a proxy number must be located relative to the participant identifier. Can be: country, area-code, or extended-area-code. The default value is country and more specific areas than country are only available in North America.

                    number_selection_behavior
                    Optional
                    post enum:number_selection_behavior Not PII

                    The preference for Proxy Number selection in the Service instance. Can be: prefer-sticky or avoid-sticky and the default is prefer-sticky. prefer-sticky means that we will try and select the same Proxy Number for a given participant if they have previous Sessions, but we will not fail if that Proxy Number cannot be used. avoid-sticky means that we will try to use different Proxy Numbers as long as that is possible within a given pool rather than try and use a previously assigned number.

                    intercept_callback_url
                    Optional
                    post url Not PII

                    The URL we call on each interaction. If we receive a 403 status, we block the interaction; otherwise the interaction continues.

                    out_of_session_callback_url
                    Optional
                    post url Not PII

                    The URL we should call when an inbound call or SMS action occurs on a closed or non-existent Session. If your server (or a Twilio function) responds with valid TwiML, we will process it. This means it is possible, for example, to play a message for a call, send an automated text message response, or redirect a call to another Phone Number. See Out-of-Session Callback Response Guide for more information.

                    chat_instance_sid
                    Optional
                    post sid<IS> Not PII

                    The SID of the Chat Service Instance managed by Proxy Service. The Chat Service enables Proxy to forward SMS and channel messages to this chat instance. This is a one-to-one relationship.

                    Example 1
                    Loading Code Sample...
                          
                          
                          

                          Update Service

                          Delete a Service resource

                          delete
                          https://proxy.twilio.com/v1/Services/{Sid}

                          Permanently delete a Service and all children (Sessions, Participants, Interactions). In addition, all associated Proxy Numbers (e.g. Phone Numbers and Short Codes) will become available for assignment to another Service.

                          Any Message or Call records created during interactions for Sessions in this Service will NOT be deleted automatically. If you want to delete all related Message/Call resources, you must issue direct DELETE requests for the inbound and outbound resources of all child Interactions directly. Once you have deleted a Service, those resource Sids will not be discoverable via Proxy.

                          Parameters
                          Parameters in REST API format
                          sid
                          Path
                          delete sid<KS> Not PII

                          The Twilio-provided string that uniquely identifies the Service resource to delete.

                          Example 1
                          Loading Code Sample...
                                
                                
                                

                                Delete Service

                                Rate this page:

                                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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                Loading Code Sample...
                                      
                                      
                                      

                                      Thank you for your feedback!

                                      Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      thanks-feedback-gif