Session Monitoring

Using the Vonage Video platform, developers can monitor certain activity of clients using the client SDKs, from within their app server.

By registering for callbacks with the Vonage Video REST API, your callback URL will receive HTTP POST requests when any sessions are created and destroyed, clients connect and disconnect, and clients publish and unpublish streams to a session in your Vonage project.

Additionally, you can register a callback to monitor events related to Vonage Video archives for your project.

Registering callbacks

Session events and archive status updates can all be registered to HTTP endpoints within your server.

Whenever registered activity occurs, an HTTP request is sent from Vonage Video infrastructure to your endpoint.

To register a callback:

Log in to your Vonage Video API Account.
From the left-hand menu, select Applications.
For existing projects click on the three dots and select the Edit option and scroll down to the capability section.
For new projects the capability section is displayed after clicking on Create a new application.
Toggle to enable the video option.
Set the callback URL in the Session Monitoring section.

Secure callbacks: You can secure webhook callback requests with signed callbacks, using a signature secret. See Secure callbacks.

The archive callback URL and broadcast callback URL are set separately from the the callback URL for session events. Set the archive callback URL in the Archive section of your Vonage Video API account page.

Important: The new service will no longer disable event forwarding in the case of excessive delivery failures, since the retry and backoff mechanism will be used. Therefore, there will no longer be any expected email indication to notify that callbacks were disabled and need to be re-enabled, because the new service will not suspended/disable callbacks in any way.

Monitoring when sessions start and stop

When clients first start using a session and when a session stops being used, sessionCreated and sessionDestroyed events are sent to your registered callback endpoint.

Session created

This event is sent when the first client connects to a session. If all clients disconnect (see Session destroyed), clients can later reconnect to the same session.

For each distinct event, the server sends an HTTP POST request to the callback URL you supply. The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionCreated",
  "timestamp": 1470257688309,
  "createdAt": 1470257688309
}

The JSON object includes the following properties:

sessionId — The session ID associated with this event
projectId — The project ID associated with this event
event — "sessionCreated"
timestamp — The timestamp for when the callback event was sent
createdAt — The timestamp for when the first client connected to the session

Session destroyed

This event is sent when a session stops being used:

One minute after all participants have disconnected from the session.
When a Video API session times out, which can occur after 8 hours.
When a Video API server shuts down unexpectedly.

After this event is dispatched, you can still reuse the session. Clients can reconnect to the session using the same session ID Session created callback event will be sent. However, it is a better practice to have clients reconnect using a new session ID.

Also, as a best practice, you should have clients reconnect to new sessions (using a new session ID), within 8 hours of the Session created callback event.

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionDestroyed",
  "timestamp": 1470258896953,
  "createdAt" : 1470258896953,
  "reason" : "clientDisconnected"
  }

The JSON object includes the following properties:

sessionId — The session ID associated with this event
projectId — The project ID associated with this event
event — "sessionDestroyed"
timestamp — The timestamp for when the callback event was sent
createdAt — The timestamp for when this session stopped being used
reason — This is set to one of the following:
- "clientDisconnected" — All clients have disconnected from the session.
- "forceDisconnected" — A moderator has disconnected the clients from the session. Or the session timed out. Or a Video API server shut down unexpectedly.
- "mediaIdle" — All clients have been disconnected from the session because they have not published or subscribed to streams within 4 hours of connecting.
- "serverRotation" - All clients have been disconnected from the session due to the server being rotated as part of a scaling operation.

Session notification events

The sessionNotification event is sent when a group of Video API servers for one of your sessions is scheduled to be rotated.

The sessionNotification event is an HTTP POST request sent to session monitoring callback URL you supply. The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "timestamp": 1470282888309,
  "remainingTime": 3600,
  "createdAt": 1470257688309
}

The JSON object includes the following properties:

sessionId — The session ID associated with this event
projectId — The application ID associated with this event
event — "sessionNotification"
reason — For a server rotation event, this is set to "serverRotation". (Currently, this is the only type of session notification event.)
remainingTime — The remaining time, in seconds, until the servers for the session will be rotated. This will be set to 3600 — 1 hour.
timestamp — The timestamp for when the callback event was sent
createdAt — The timestamp for when the first client connected to the session

See Server Rotation for more information on Video API server rotations and how to keep clients connected when server rotations occur.

Monitoring connection activity

Once properly registered, The Vonage Video infrastructure can send HTTP requests for all connections made (and destroyed) to all sessions for a single project.

This is particularly useful for tracking user availability without requiring additional connections or reporting directly from the endpoint.

When clients receive connectionCreated and connectionDestroyed events in response to other clients connecting to and disconnecting from a session, these same events are sent to your registered callback endpoint.

Connection created

For each distinct event, the server sends an HTTP POST request to the URL you supply.

The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionCreated",
    "timestamp": 1470257688309,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": "TOKENDATA"
    }
}

The JSON object includes the following properties:

sessionId — The session ID associated with this event.
projectId — The project ID associated with this event.
event — "connectionCreated".
timestamp — Milliseconds since unix epoch time.
connection — An object defining the connection, containing the following properties:
- id — The connection ID.
- data — The connection data.
- createdAt — The timestamp value this object was created.

Connection destroyed

For each distinct event, the server sends an HTTP POST request to the URL you supply.

The Content-Type for the request is application/json.

The data of the request is a JSON object of the following form:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": ""
    }
}

The JSON object includes the following properties:

sessionId — The session ID associated with this event.
projectId — The project ID associated with this event.
reason — For a connectionDestroyed event, this is set to one of the following:
- "clientDisconnected" — A client disconnected from the session (for example, by calling the OpenTok.js Session.disconnect() method or by closing the browser or app).
- "forceDisconnected" — A moderator has disconnected the client from the session (by calling the OpenTok.js Session.forceDisconnect() method).
- "networkDisconnected" — The network connection terminated abruptly (for example, the client lost their internet connection).
- "mediaIdle" - The client was disconnected from a session because it did not publish or subscribe to streams within 4 hours of connecting.
- "serverRotation" — The client was disconnected from the session due to the server being rotated as part of a scaling operation.
event — "connectionDestroyed".
timestamp — Milliseconds since unix epoch time.
connection — An object defining the connection, containing the following properties:
- id — The connection ID.
- data — The connection data.
- createdAt — The timestamp value this object was created.

Monitoring streams

Server endpoints can also register to receive HTTP requests triggered by stream activity on all sessions for a given project.

When streams are created and destroyed, the request will contain stream and connection data for the stream that triggered the event.

When clients receive streamCreated and streamDestroyed events in response to other clients publishing to a session, these same events are sent to your registered callback endpoint.

Stream created

For each distinct event, the server sends an HTTP POST request to the URL you supply.

The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamCreated",
    "timestamp": 1470258860571,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

sessionId — The session ID associated with this event.
projectId — The project ID associated with this event.
event — "streamCreated".
timestamp — Milliseconds since unix epoch time.
stream — An object that defines the stream:
- id — The stream ID.
- connection — The connection associated with this stream. This object includes the following properties:
  - id — The connection ID
  - data — The connection data.
  - createdAt — The timestamp value the connection was created.
- createdAt — The timestamp value the stream was created.
- name — The name, if there was one, passed in when the publisher associated with this stream was initialized.
- videoType — The type of video sent on this stream, either "camera", "screen", or "custom" (or undefined for an audio-only stream).

Stream destroyed

For each distinct event, the server sends an HTTP POST request to the URL you supply.

The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

sessionId — The session ID associated with this event.
projectId — The project ID associated with this event.
event — "streamDestroyed".
reason — For a streamDestroyed event, this is set to one of the following:
- "clientDisconnected" — The client disconnected from the session (for example, by calling the OpenTok.js Session.disconnect() method).
- "forceDisconnected" — A moderator has disconnected the publisher of the stream from the session, by calling the OpenTok.js Session.forceDisconnect() method.
- "forceUnpublished" — A moderator has forced the publisher of the stream to stop publishing the stream, by calling the OpenTok.js Session.forceUnpublish() method.
- "mediaStopped" — The user publishing the stream has stopped sharing the screen. This value is only used in screen-sharing video streams.
- "networkDisconnected" The network connection terminated abruptly (for example, the client lost their internet connection).
- "serverRotation" — The stream was destroyed because the server was rotated as part of a scaling operation.
timestamp — Milliseconds since unix epoch time.
stream — An object that defines the stream:
- id — The stream ID
- connection — The connection associated with this stream. This object includes the following properties:
  - id — The connection ID.
  - data — The connection data.
  - createdAt — The timestamp value the connection was created.
- createdAt — The timestamp value the stream was created.
- name — The name, if there was one, passed in when the publisher associated with this stream was initialized.
- videoType — The type of video sent on this stream, either "camera", "screen", or "custom" (or undefined for an audio-only stream).

Monitoring archives

Each archive goes through multiple states through the lifespan of the archive. For every status update that occurs, a server endpoint with an archive status registration will receive an HTTP request.

This is particularly useful for triggering post-processing of an archive, or for performing any necessary administrative tasks after an archive has been uploaded to persistent storage.

For more information see the archive status changes section of the Vonage Video archiving developer guide.

Monitoring broadcasts

See the Monitoring live streaming broadcast status changes section of the Vonage live streaming broadcasts developer guide.

Monitoring SIP call progress

You can monitor status updates for SIP connections to a session.

See the Monitoring call progress section of the Vonage Video SIP Interconnect developer guide.

Monitoring Experience Composer

You can monitor status updates for Experience Composers. See the Configuring callbacks section of the Experience Composer developer guide.

Monitoring live captions

You can monitor status updates for live captions. See the Live caption callbacks section of the live captions developer guide.