Suggestions

close search

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, visit your TokBox account page.

The archive callback URL is set separately from the the callback URL for session events. Set the archive callback URL in the Archive section of your TokBox 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 TokBox 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

Your endpoint will receive the following JSON for each distinct event:

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

Your endpoint will receive the following JSON for each distinct event:

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

Your endpoint will receive the following JSON for each distinct event:

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

Your endpoint will receive the following JSON for each distinct event:

{
    "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.