API - Session Status

Support Center > API Integration

Published 01/20/2017 at 6:25am UTC

Page viewed 789 times

Details

How can I determine whether a session is currently active? (Applicable to customers using Zoom integration only.)

Answer

Session Status API

There are two methods you can use to determine the status of a session:

  • Webhook (have status pushed to you)
  • Status API (pull status via an API call)

The proper method to use will depend on your use case, but most use cases will involve your taking some action when a session starts or ends; in these cases, you should use the webhook if possible.

These methods work only with our Zoom videoconferencing platform. If you are using our VSee videoconferencing platform, you can subscribe to VSee PubNub events to determine status.

Webhook

All SecureVideo webhooks are configured by an account administrator in the API tab. Fill in the Custom Webhook URL with a URL on your server where you would like to receive all SecureVideo webhooks.

Once you do that, any time a SecureVideo session starts or ends, our system will perform an HTTPS POST to your Custom Webhook URL. When updating session status, the content of the HTTPS POST will be JSON, as follows:

{ "WebhookType": "SESSION_STATUS", "ID": 12345, "Status": "STARTED" }

In the Webhook JSON:

  • WebhookType is the type of webhook you are receiving. This is always "SESSION_STATUS", as that is the only webhook currently implemented. Future webhooks will have other WebhookTypes.
  • ID is the ID of the object relevant to the webhook, and depends on WebhookType. For "SESSION_STATUS" webhooks, ID will be the Session ID for which status is provided.
  • Status is the status of the object relevant to the webhook, and depends on WebhookType. For "SESSION_STATUS" webhooks, Status will be "STARTED" (the session has just been started) or "ENDED" (the session has just ended).

Status API

GET https://api.securevideo.com/status/12345 (where 12345 is the Session ID)

Gets the current status of any session. Generally, this will be one whose ID you have previously gathered from the Session API.

The returned status will be in JSON, for example:

{
"SessionID": 12345,
"SessionStatus": "STARTED"
}

The possible values for SessionStatus are:

  • NOT_STARTED: The session has never been started. Note that if any session host tests a session prior to its start time, even if that session host is the only one to connect to the session at that time(e.g., she quickly tests her camera and then disconnects), the SessionStatus thereafter will be "STARTED" or "ENDED". The status of "NOT_STARTED" means there has been no successful connection to the session by any participant, at any time.
  • STARTED: The session has been started and is ongoing. There is at least one active connection to the session.
  • ENDED: The session has been started and is no longer ongoing. There are no active connections to the session. Note that even if a session is ended, it can be restarted and then ended again later. This is not uncommon, and can happen in the event of a dropped connection, or participants deciding to have a quick follow-up session using the same session they used previously.

Accuracy of Webhook and Status API

Session status is accurate the vast majority of the time, but is not guaranteed to be real-time in all cases. Occasionally, networking and/or endpoint conditions can cause a delay in our reporting status to you via webhooks and the Status API.

 

 

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