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
|
The unique string that we created to identify the Session resource. |
service_sid
|
The SID of the Service the session is associated with. |
account_sid
|
The SID of the Account that created the Session resource. |
date_started
|
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 |
unique_name
|
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
|
The status of the Session. Can be: |
closed_reason
|
The reason the Session ended. |
ttl
|
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
|
The Mode of the Session. Can be: |
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
|
The URLs of resources related to the Session. |
Create a Session resource
https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions
Create a new Session.
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the parent Service resource. |
unique_name
Optional
|
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
|
The ISO 8601 date when the Session should expire. If this is value is present, it overrides the |
ttl
Optional
|
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
|
The Mode of the Session. Can be: |
status
Optional
|
The initial status of the Session. Can be: |
participants
Optional
|
The Participant objects to include in the new session. |
fail_on_participant_conflict
Optional
|
[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
https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{Sid}
Retrieve a single Session.
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the parent Service of the resource to fetch. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Session resource to fetch. |
Example 1
Read multiple Session resources
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
|
The SID of the parent Service of the resource to read. |
Example 1
Update a Session resource
https://proxy.twilio.com/v1/Services/{ServiceSid}/Sessions/{Sid}
Post updates to a given Session.
Parameters
| Parameters in REST API format | |
|---|---|
service_sid
Path
|
The SID of the parent Service of the resource to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Session resource to update. |
date_expiry
Optional
|
The ISO 8601 date when the Session should expire. If this is value is present, it overrides the |
ttl
Optional
|
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
|
The new status of the resource. Can be: |
fail_on_participant_conflict
Optional
|
[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
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
|
The SID of the parent Service of the resource to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Session resource to delete. |
Example 1
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.