Twilio Proxy Session
Session Resource Reference for the Twilio Proxy REST API
A Session is a single instance of two individuals communicating. It belongs to a Service and maps two Participants for a Proxy application. Sessions allow you to:
Specify a unique identifier relevant to your use case, such as a job ID
See whether a given Session is closed or not and the reason it has been closed
Control the length of time the Session should be active
Session properties
Resource Properties in REST API format
sid
sid
Not PII
The unique string that we created to identify the Session resource.
service_sid
sid
The SID of the Service the session is associated with.
account_sid
sid
The SID of the Account that created the Session resource.
date_started
date_time
The ISO 8601 date when the Session started.
date_ended
The ISO 8601 date when the Session ended.
date_last_interaction
The ISO 8601 date when the Session last had an interaction.
date_expiry
The ISO 8601 date when the Session should expire. If this is value is present, it overrides the ttl value.
unique_name
string
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.
status
enum:status
The status of the Session. Can be: open, in-progress, closed, failed, or unknown.
closed_reason
The reason the Session ended.
ttl
integer
The time, in seconds, when the session will expire. The time is measured from the last Session create or the Session’s last Interaction.
mode
enum:mode
The Mode of the Session. Can be: message-only, voice-only, or voice-and-message.
date_created
The ISO 8601 date and time in GMT when the resource was created.
date_updated
The ISO 8601 date and time in GMT when the resource was last updated.
url
The absolute URL of the Session resource.
links
uri_map
The URLs of resources related to the Session.
Create a Session resource
post
ServiceSid}/Sessions
Create a new Session.
Parameters in REST API format
Path
The SID of the parent Service resource.
Optional
An application-defined string that uniquely identifies the resource. This value should not have PII.
The Mode of the Session. Can be: message-only, voice-only, or voice-and-message and the default value is voice-and-message.
The initial status of the Session. Can be: open, in-progress, closed, failed, or unknown. The default is open on create.
participants
object[]
The Participant objects to include in the new session.
fail_on_participant_conflict
boolean
[Experimental] For accounts with the ProxyAllowParticipantConflict account flag, setting to true enables per-request opt-in to allowing Proxy to reject a Session create (with Participants) request that could cause the same Identifier/ProxyIdentifier pair to be active in multiple Sessions. Depending on the context, this could be a 409 error (Twilio error code 80623) or a 400 error (Twilio error code 80604). If not provided, requests will be allowed to succeed and a Debugger notification (80802) will be emitted. Having multiple, active Participants with the same Identifier/ProxyIdentifier pair causes calls and messages from affected Participants to be routed incorrectly. Please note, the default behavior for accounts without the ProxyAllowParticipantConflict flag is to reject the request as described. This will eventually be the default for all accounts.
Example 1
You are viewing an outdated version of this SDK.
Fetch a Session resource
get
ServiceSid}/Sessions/{Sid}
Retrieve a single Session.
The SID of the parent Service of the resource to fetch.
sid_like
The Twilio-provided string that uniquely identifies the Session resource to fetch.
Read multiple Session resources
Retrieve a list of all Sessions for a given Service.
The SID of the parent Service of the resource to read.
Update a Session resource
Post updates to a given Session.
The SID of the parent Service of the resource to update.
The Twilio-provided string that uniquely identifies the Session resource to update.
The new status of the resource. Can be: in-progress to re-open a session or closed to close a session.
[Experimental] For accounts with the ProxyAllowParticipantConflict account flag, setting to true enables per-request opt-in to allowing Proxy to return a 400 error (Twilio error code 80604) when a request to set a Session to in-progress would cause Participants with the same Identifier/ProxyIdentifier pair to be active in multiple Sessions. If not provided, requests will be allowed to succeed, and a Debugger notification (80801) will be emitted. This will eventually be the default for all accounts.
Delete a Session resource
delete
Deleting a Session removes it permanently. Related Participants and Interactions will also be deleted.
Any Message or Call logs created during interactions for this Session will be deleted automatically after 90 days of the Session being closed, as per our Session retention policy. If you want to delete these resources before then, you must issue DELETE requests for the inbound and outbound resources of all child Interactions directly. Once you have deleted a Session, those resource Sids will not be discoverable via Proxy.
The SID of the parent Service of the resource to delete.
The Twilio-provided string that uniquely identifies the Session resource to delete.
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 Community Forums or browsing the Twilio tag on Stack Overflow.
Proxy Limits – Twilio
Twilio Proxy has a number of limits in place which will constrain certain elements of the system and how it is used.
The Proxy limits are enforced at the Service instance level (except for Service list limits which are enforced at the Account level). These limits are set within a Service instance scope.
Number Pool Limits
Each service can have a maximum of 5000 Reserved numbers and 500 dynamic/non-reserved numbers.
Active Participants per Number
We recommend, but do not enforce, a limit of 100 participants associated with a given number in active sessions at any given time. See for more information on proxy number management.
Throughput Limits
Limits of this type will impact the number of simultaneous actions that can be performed within a Service Instance.
Requests Per Second
RPS is the guaranteed Requests Per Second against a given endpoint that a Service instance will support. All Service instances have a baseline of 30 RPS per endpoint. Proxy will allow short bursts above the baseline RPS – up to 5x the baseline. If the bursts become sustained throughput, the Service will start rejecting requests.
Please note that the RPS limit is currently enforced for Read actions against Services, Sessions, Participants and Interactions.
How This Works
The request limit is based on average request rate in 5s sliding window. For example, for 30 req/s limit we allow burst up to 150 req/s. After this your application client request logic needs to wait until average goes below threshold to make any query requests again against that endpoint.
Requests that go over RPS threshold are rejected with HTTP status code 429 Too Many Requests.
When the Throughput is Exceeded
For reliable handling of short-term bursts of requests towards the Proxy REST API, please make sure your backend application implements a retry logic. When your application receives HTTP status code 429 back from the Proxy service, it should repeat the request several times, using a good exponential back-off algorithm like the one advocated by Amazon.
Data Length/Size Limits
Limits for user provided data in UTF-8 characters. If a payload limit is specified in bytes, we assume that the data is serialized using UTF-8 encoding where each character (e. g. emoticon) may take more than one byte.
Resource Property Limits
Resource
Field
Maximum length / Size
Service
UniqueName
191 characters
CallbackUrl
4000 characters
InterceptCallbackUrl
OutOfSessionCallbackUrl
Session
Ttl
0 < ttl < 2147483647
Participant
FriendlyName
255 characters
Identifier
ProxyIdentifier
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 Community Forums or browsing the Twilio tag on Stack Overflow.
Proxy: One-to-one Masked Communications – Twilio
Public Beta
Twilio’s Proxy API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.
Public Beta products are not covered by a Twilio SLA.
Twilio Proxy simplifies the task of masking the communications between two parties (aka masked phone numbers or masked calling). Proxy automatically provides a number and associates two numbers together in order to forward messages and calls back and forth.
With Proxy, Twilio facilitates any use case that can benefit from a temporary conversation between two parties.
Not a developer? See the Proxy product page.
Get started with Proxy
Follow our quickstart for the fastest experience adding masked phone numbers for SMS and Voice communications.
Build your app
You’ve got an idea in mind that could employ ephemeral communications. Let us help you make it a reality.
These docs will help you turn that idea into production and show you all of the details you need to have a hit on your hands.
Usage guides
API reference
Legal implications of managing communications between users
If you choose to manage communications between your users, including voice calls, text-based messages (e. g., SMS), and chat, you may need to comply with certain laws and regulations, including those regarding obtaining consent. Additional information regarding legal compliance considerations and best practices for using Twilio to manage and record communications between your users, such as when using Twilio Proxy, can be found here.
Notice: Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Twilio.
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.
You are viewing an outdated version of this SDK.
Frequently Asked Questions about twilio proxy session
How does twilio proxy work?
Twilio Proxy simplifies the task of masking the communications between two parties (aka masked phone numbers or masked calling). Proxy automatically provides a number and associates two numbers together in order to forward messages and calls back and forth.
What is twilio proxy service?
Deploy and moderate private interactions between a customer and a mobile worker representing a business. Works with text, phone calls, chat, and messaging apps. Available in developer preview.May 24, 2017
What interaction can occur in a proxy session?
Interactions can have both inbound and outbound legs or be “one-sided” (like when creating a Message Interaction resource). If a user sends an SMS to a proxy number, and Twilio Proxy handles the proxying to the other Participant, you’ll have an Interaction with both an inbound SMS and an outbound SMS.
