Suggestions

close search

Searching ...

Register to receive real-time session event callbacks and monitor your session activity from your app server.

Using the OpenTok platform, developers can monitor certain activity of clients using OpenTok client SDKs, from within their app server. By registering for callbacks with the OpenTok 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 OpenTok project. Additionally, you can register a callback to monitor events related to OpenTok archives for your project.

Registering callbacks

Session events and archive status updates information can all be registered to HTTP endpoints within your server. Whenever registered activity occurs, an HTTP request is issued from OpenTok infrastructure to your endpoint.

To register a callback:

1. Visit your Vonage Video API account page.

2. Select the OpenTok project for which you want to register a callback.

3. 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 broacast 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 session monitoring service no longer disables event forwarding in the case of excessive delivery failures (as was the case in previous versions), since a retry and backoff mechanism is used. You will no longer receive emails on session monitoring callback disruptions, since the service will not be suspended or disabled.

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 pratice, you should have clients reconnect to new sessions (using a new session ID), within 8 hours of the Session created callback event.

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": "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 because of Video API server rotation.

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 project 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, OpenTok 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 (see 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 a session because of Video API server rotation.

• 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 (see 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 (see 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 stopped because the publishing client was disconnected from a session because of Video API server rotation.

• 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 (see 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 OpenTok archiving developer guide.

Monitoring broadcasts

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

Monitoring SIP call progress

You can monitor status updates for SIP connections to OpenTok session. See the Monitoring call progress section of the OpenTok 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.