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?

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

Names in Node.js format
sid
sid<KS> Not PII

A 34 character string that uniquely identifies this Service.

uniqueName
string Not PII

A human-readable description of this resource, up to 255 characters. Should not contain PII.

accountSid
sid<AC> Not PII

The unique SID identifier of the Account.

chatInstanceSid
sid<IS> Not PII

The Chat Service Instance sid managed by Proxy Service. Enables Proxy to forward sms and channel messages to this chat instance. This is a one-to-one relationship.

callbackUrl
url Not PII

The URL to which Twilio will make callbacks on interaction status changes.

defaultTtl
integer Not PII

The default time to live for Sessions created in this Service. The amount of time, specified in seconds, that each Session should remain open. Keys off the last interaction or Session creation time. Defaults to a value of 0 (unlimited Session length). You can override this value by setting a specific TTL on individual Sessions.

numberSelectionBehavior
enum:number_selection_behavior Not PII

The preference for Proxy Number selection for this instance. 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 error and 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.

geoMatchLevel
enum:geo_match_level Not PII

Whether proxy number selected must be in the same area code as the participant identifier. Options: country, area-code, extended-area-code. Default: country. Levels lower than country are only available in North America.

interceptCallbackUrl
url Not PII

Fires on each interaction. If you respond with a 403 status, we will abort/block the interaction. For any other status or timeout, the interaction continues.

outOfSessionCallbackUrl
url Not PII

A URL to send webhooks to when an action (inbound call or SMS) occurs where there is no Session or a closed Session. If your server (or a Twilio function) responds with valid TwiML, this will be processed. This means it is possible to, for example, 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.

dateCreated
date_time<iso8601> Not PII

The date that this Service was created, given in ISO 8601 format.

dateUpdated
date_time<iso8601> Not PII

The date that this Service was last updated, given in ISO 8601 format.

url
url Not PII

The URL of this resource.

links
uri_map Not PII

Contains a dictionary of URL links to nested resources of this 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
Names in None format
unique_name
Required
post string Not PII

The human-readable string that uniquely identifies this Service, up to 64 characters. Should not contain PII.

default_ttl
Optional
post integer Not PII

The default time delay in seconds after the latest of Session create time or the Session's last Interaction time, after which a session will expire. Used for sessions where TTL is not specified.

callback_url
Optional
post url Not PII

The URL to which Twilio will make callbacks on interaction status changes.

geo_match_level
Optional
post enum:geo_match_level Not PII

Whether proxy number selected must be in the same area code as the participant identifier. Options: country, area-code, extended-area-code. Default: country. Levels lower than country are only available in North America.

number_selection_behavior
Optional
post enum:number_selection_behavior Not PII

Options: prefer-sticky, avoid-sticky. Default: prefer-sticky.

intercept_callback_url
Optional
post url Not PII

A URL for Twilio call before each Interaction. Returning a 403 status code will prevent the interaction from continuing.

out_of_session_callback_url
Optional
post url Not PII

A URL for Twilio call when a new Interaction has no Session. See Out-of-Session Callback Response Guide for more information.

chat_instance_sid
Optional
post sid<IS> Not PII

The Chat Service Instance sid managed by Proxy Service. Enables Proxy to forward sms and channel messages to this chat instance. This is a one-to-one relationship.

Example
        
        
        
        

        Fetch a Service resource

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

        Retrieve a single Service.

        Parameters
        Names in None format
        sid
        Required
        get sid_like<KS> Not PII

        A 34 character string that uniquely identifies this Service.

        Example
              
              
              
              

              Read multiple Service resources

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

              Retrieve a list of all Services for a given account.

              Example
                    
                    
                    
                    

                    Update a Service resource

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

                    Update a Service's configuration.

                    Parameters
                    Names in None format
                    sid
                    Required
                    post sid<KS> Not PII

                    A 34 character string that uniquely identifies this Service.

                    unique_name
                    Optional
                    post string Not PII

                    A human-readable description of this resource, up to 64 characters. Should not contain PII.

                    default_ttl
                    Optional
                    post integer Not PII

                    The default time delay in seconds after the latest of Session create time or the Session's last Interaction time, after which a session will expire. Used for sessions where TTL is not specified.

                    callback_url
                    Optional
                    post url Not PII

                    The URL to which Twilio will make callbacks on interaction status changes.

                    geo_match_level
                    Optional
                    post enum:geo_match_level Not PII

                    Whether proxy number selected must be in the same area code as the participant identifier. Options: country, area-code, extended-area-code. Default: country. Levels lower than country are only available in North America.

                    number_selection_behavior
                    Optional
                    post enum:number_selection_behavior Not PII

                    Options: prefer-sticky, avoid-sticky. Default: prefer-sticky.

                    intercept_callback_url
                    Optional
                    post url Not PII

                    A URL for Twilio call before each Interaction. Returning a 403 status code will prevent the interaction from continuing.

                    out_of_session_callback_url
                    Optional
                    post url Not PII

                    A URL for Twilio call when a new Interaction has no Session. See Out-of-Session Callback Response Guide for more information.

                    chat_instance_sid
                    Optional
                    post sid<IS> Not PII

                    The Chat Service Instance sid managed by Proxy Service. Enables Proxy to forward sms and channel messages to this chat instance. This is a one-to-one relationship.

                    Example
                          
                          
                          
                          

                          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
                          Names in None format
                          sid
                          Required
                          delete sid<KS> Not PII

                          A 34 character string that uniquely identifies this Service.

                          Example
                                
                                
                                
                                
                                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 browsing the Twilio tag on Stack Overflow.