Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Session Monitoring

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 client connects or publishes 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: If within 30 minutes there are more than 50 event delivery failures (in which we don't receive a 200 success response when sending an HTTP request to your callback URL), we will disable session monitoring event forwarding. We will send an email if this occurs. You can reenable session monitoring in your Vonage Video API account page.

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:

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:

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"
    }
}

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"
    }
}

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.