API - Sessions

Support Center > API Integration

Published 02/05/2014 at 11:16pm UTC

Page viewed 4312 times

Details

How do I use the API to manage active sessions for my users?

Answer

Manage Session API

There are 4 API methods available to manage your sessions:

 

All sessions are scheduled in Universal Coordinated Time (UTC). Participant timezones are used by our system to convert the session time from UTC to the relevant timezone for the invitation and reminders. For Meet Now Sessions, the ScheduleTs will be the time that the session was created, and will have a random minutes and seconds component, e.g., 2014-04-16T15:11:22.  For Scheduled Sessions, the ScheduleTs will have 0 seconds, and the minute will be 0, 15, 30, or 45, e.g. 2014-04-16T15:00:00.

 

Get a List of Active Sessions

GET https://api.securevideo.com/session/5 (where 5 is the User ID)

Gets a list of active sessions for the user whose ID = 5.

GET https://api.securevideo.com/session 

Gets a list of active sessions across your user base. Active sessions are those which are either scheduled for a future date, and happening today, or have happened in the last day.  Previous sessions are deactivated nightly by a SecureVideo automated process.

GET https://api.securevideo.com/session?participantEmail=testing@securevideo.com 

Gets a list of active sessions across your user base for which the e-mail address specified in the participantEmail query string parameter holds an active connect code.

GET https://api.securevideo.com/session/5?participantEmail=testing@securevideo.com (where 5 is the user ID)

Gets a list of active sessions for the user whose ID = 5 for which the e-mail address specified in the participantEmail query string parameter holds an active connect code.

 

For all of these methods, Session JSON is returned containing an array of active sessions.  This array may be empty, if the user has no active sessions.  For an example of how to interpret Session JSON, click here.

 

Create a New Session for a User

POST https://api.securevideo.com/session/5 (where 5 is the User ID)

{
"ScheduleTs": "2014-04-16T15:00:00",
"IsRecorded": true,
"Participants": [
{
"SecureVideoUserId": "12"
},
{
"ParticipantFullName": "Trevor",
"ParticipantEmailAddress": "trevor@geemail.com",
"ParticipantSmsNumber": "3124455566",
"ParticipantDefaultResolution": "default",
"ParticipantTimeZoneWindowsId": "Hawaiian Standard Time",
"ShouldAutoDeliverCode": "S",
"SvcId": 1037,
"DepositRequired": 20.00
}
]
}

Creates a new user with the specified properties.  Note that the above JSON you will POST to create a new session that is a strict subset of the JSON you will receive from GET /session.

To schedule a future session, ScheduleTs is required.  ScheduleTs is always in UTC time, using ISO time format without time zone (e.g., 2014-04-16T15:00:00). To schedule a session for right now, set ScheduleTs to null.

IsRecorded specifies whether the session will be recorded to the SecureVideo cloud. If true, and your account has been configured by SecureVideo to have recording privileges, then the session will be recorded. Otherwise, the session will not be recorded.

The Participants array must have at least one object.  Do not add the session host (e.g., a clinician) to the participant array, only add session guests (e.g., patients).

You can include either of two types of Participants to the Session: SecureVideo users, or non-SecureVideo users. In the JSON example above, we are adding one of each: the SecureVideo user with the User ID of 12, and a non-SecureVideo user named Trevor.

When adding a SecureVideo user to the session, you should only include the SecureVideoUserId. (The SecureVideoUserId is the SystemUserId returned when creating a new user, or getting a list of users.) 

When adding a non-SecureVideo user to the session, you should include the fields described above. Some guidelines for non-SecureVideo users include: 

ParticipantFullName is required and must be at least 2 characters. If ShouldAutoDeliverCode is N, then the ParticipantEmailAddress and ParticipantSmsNumber may be blank, otherwise, one or the other is required.

  • "E": If ParticipantEmailAddress exists, the SecureVideo system will send via e-mail a Session invite and Session reminders to this participant.
  • "S": If ParticipantSmsNumber exists, the SecureVideo system will send via text message a Session invite and Session reminders to this participant.
  • "N": No automatic delivery of the code will occur.  The Session host, or your system, will be responsible for providing invites and reminders to the Participant.

ParticipantDefaultResolution must be one of the values "hd", "high", "default", or "low". This property value is case sensitive (i.e., "HD" or "High" are not valid values), where "hd" is 720p, "high" is 480p, "default" is 320p, and "low" is 240p.

If you specify ParticipantTimeZoneWindowsId, the participant will have Session times indicated in his/her specific time zone.  If you do not specify ParticipantTimeZoneWindowsId, the participant will have Session times expressed in the time zone of the Session Host.  The list of valid time zones can be seen here.

If you have set up Stripe payments in the UI (Features > Get Paid Online), you can specify a deposit that this participant must pay the DepositRequired amount (in US dollars) by credit card prior to entering the waiting room to receive a specified Service referenced by the SvcId that you would find as the Service ID on your "Account Services" screen. If you specify null for both SvcId and DepositRequired (the default), then the participant will be able to enter the waiting room without making a payment. SvcId and DepositRequired must both either be null, or both be not null.

On success, this request will return a 201 Status Code, indicating that a new record was created, along with content containing the newly created record.

 

Reschedule a Session

PUT https://api.securevideo.com/session/225 (where 225 is the Session ID)

{"ScheduleTs": "2014-02-04T22:00:00"}

Reschedules the session with the ID specified in the URI to the time indicated in the content of the request.  Reschedule notifications are sent to all participants who have ShouldAutoDeliverCode = true.

On success, this request will return a 200 Status Code, along with content containing the newly updated record.

 

Cancel a Session

DELETE https://api.securevideo.com/session/225 (where 225 is the Session ID)

Cancels the session with the ID specified in the URI.  Cancellation notifications are sent to all participants who have ShouldAutoDeliverCode = true.

On success, this request will return a 204 Status Code, indicating No Content.

 

 

This article was last reviewed by our Support team on April 19, 2017.