Menu

Expand
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?

Session Resource

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<KC> Not PII

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

service_sid
sid<KS> Not PII

The SID of the Service the session is associated with.

account_sid
sid<AC> Not PII

The SID of the Account that created the Session resource.

date_started
date_time<iso8601> Not PII

The ISO 8601 date when the Session started.

date_ended
date_time<iso8601> Not PII

The ISO 8601 date when the Session ended.

date_last_interaction
date_time<iso8601> Not PII

The ISO 8601 date when the Session last had an interaction.

date_expiry
date_time<iso8601> Not PII

The ISO 8601 date when the Session should expire. If this is value is present, it overrides the ttl value.

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. This value should not have PII.

status
enum:status Not PII

The status of the Session. Can be: open, in-progress, closed, failed, or unknown.

closed_reason
string Not PII

The reason the Session ended.

ttl
integer Not PII

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 Not PII

The Mode of the Session. Can be: message-only, voice-only, or voice-and-message.

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 Session resource.

links
uri_map Not PII

The URLs of resources related to the Session.

Create a Session resource

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

Create a new Session.

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

The SID of the parent Service resource.

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.

date_expiry
Optional
post date_time<iso8601> Not PII

The ISO 8601 date when the Session should expire. If this is value is present, it overrides the ttl value.

ttl
Optional
post integer Not PII

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
Optional
post enum:mode Not PII

The Mode of the Session. Can be: message-only, voice-only, or voice-and-message and the default value is voice-and-message.

status
Optional
post enum:status Not PII

The initial status of the Session. Can be: open, in-progress, closed, failed, or unknown. The default is open on create.

participants
Optional
post object[] Not PII

The Participant objects to include in the new session.

fail_on_participant_conflict
Optional
post boolean Not PII

[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
        
        
        
        

        Fetch a Session resource

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

        Retrieve a single Session.

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

        The SID of the parent Service of the resource to fetch.

        sid
        Path
        get sid_like<KC> Not PII

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

        Example 1
              
              
              
              

              Read multiple Session resources

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

              Retrieve a list of all Sessions for a given Service.

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

              The SID of the parent Service of the resource to read.

              Example 1
                    
                    
                    
                    

                    Update a Session resource

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

                    Post updates to a given Session.

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

                    The SID of the parent Service of the resource to update.

                    sid
                    Path
                    post sid<KC> Not PII

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

                    date_expiry
                    Optional
                    post date_time<iso8601> Not PII

                    The ISO 8601 date when the Session should expire. If this is value is present, it overrides the ttl value.

                    ttl
                    Optional
                    post integer Not PII

                    The time, in seconds, when the session will expire. The time is measured from the last Session create or the Session's last Interaction.

                    status
                    Optional
                    post enum:status Not PII

                    The new status of the resource. Can be: in-progress to re-open a session or closed to close a session.

                    fail_on_participant_conflict
                    Optional
                    post boolean Not PII

                    [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. 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
                          
                          
                          
                          

                          Delete a Session resource

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

                          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.

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

                          The SID of the parent Service of the resource to delete.

                          sid
                          Path
                          delete sid<KC> Not PII

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

                          Example 1
                                
                                
                                
                                
                                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.