Suggestions

close search

OpenTok REST callback reference

Use REST callbacks to your application server to monitor your OpenTok app.

After your app server endpoint is registered to receive events for your project, use these callbacks to parse information about the status of your sessions. The REST callbacks include events from the following groups:

Common request fields

In the REST callbacks, the same keys are used to describe the same underlying data, regardless of the callback. These include:

Archive status

Archive status is updated several times throughout the life of the archive.

{
    "id": "75f30a36-df0f-471b-88b0-c56ad26b4473",
    "status": "started",
    "name": "",
    "reason": "",
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": 123456,
    "createdAt": 1470317864000,
    "size": 0,
    "duration": 0,
    "outputMode": "composed",
    "hasAudio": true,
    "hasVideo": true,
    "certificate": "",
    "sha256sum": "",
    "password": "",
    "updatedAt": 1470317864152,
    "projectId": 123456
}

Connection events

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

All connection events will have a connection object in the request body. The fields of the connection object are common to both created and destroyed events:

Connection Created

For endpoints registered to the connection group and the created event, 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"
    }
}

Connection Destroyed

Endpoints registered to the stream group and the destroyed event 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": ""
    }
}

Stream events

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.

All stream events will have a stream object embedded in them. Stream objects include several fields:

Additionally, all stream objects will have a connection property. The fields for this connection object are the same as those in the Connection Events, above.

Stream Created

Endpoints registered to the stream group and the created event 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

Endpoints registered to the stream group and the destroyed event 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"
    }
}