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?

Session

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

Names 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
Names in None format
service_sid
Required
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.

Example
        
        
        
        

        Fetch a Session resource

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

        Retrieve a single Session.

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

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

        sid
        Required
        get sid_like<KC> Not PII

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

        Example
              
              
              
              

              Read multiple Session resources

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

              Retrieve a list of all Sessions for a given Service.

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

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

              Example
                    
                    
                    
                    

                    Update a Session resource

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

                    Post updates to a given Session.

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

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

                    sid
                    Required
                    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.

                    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 new status of the resource. Can be: in-progress to re-open a session or closed to close a session.

                    participants
                    Optional
                    post object[] Not PII

                    The Participant objects to include in the session.

                    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 records created during interactions for this Session 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 Session, those resource Sids will not be discoverable via Proxy.

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

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

                          sid
                          Required
                          delete sid<KC> Not PII

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

                          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.