Suggestions

close search

OpenTok REST API reference

Use the OpenTok REST API to generate OpenTok sessions, to work with archives, and to work with live streaming broadcasts. The OpenTok server SDKs implement many of the methods of the REST API.

The REST API includes the following methods:

Session creation, signaling, and moderation

Archiving

SIP interconnect

Live streaming broadcasts

The OpenTok SDKs wrap the OpenTok REST API to make it easier to make calls to the OpenTok platform.

Authentication

REST API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token. Create the JWT token with the following claims:

{
    "iss": "your_api_key",
    "ist": "project",
    "iat": current_timestamp_in_seconds,
    "exp": expire_timestamp_in_seconds,
    "jti": "jwt_nonce",
}

Set iss to your OpenTok API key (provided to you in your TokBox Account on the Project page).

Set ist to "project".

Set iat to the current Unix epoch timestamp (when the token was created), in seconds.

Set exp to the expiration time for the token. For security, we recommend that you use an expiration time close to the token creation time (for example, 3 minutes after creation) and that you create a new token for each REST API call. The maximum allowed expiration time range is 5 minutes.

Set jti to a unique identifier for the JWT. This is optional. See the JSON web token spec for details.

Use your OpenTok API secret as the JWT secret key and sign this with the HMAC-SHA256 encryption algorithm. (Your API secret is provided to you in your TokBox Account on the Project page.)

For example, the following Python code creates a token that can be used in an OpenTok REST API call:

import jwt # See https://pypi.python.org/pypi/PyJWT
import time
import uuid
print jwt.encode({"iss": "my-OpenTok-account-API-key",
  "iat": int(time.time()),
  "exp": int(time.time()) + 180,
  "ist": "project",
  "jti": uuid.uuid4()},
  'my-OpenTok-API-secret',
  algorithm='HS256')

Replace the my-OpenTok-account-API-key and my-OpenTok-API-secret with the OpenTok API key and API secret.

Note: Prior to using JSON Web Tokens, OpenTok REST API calls were authenticated using a custom HTTP header: X-TB-PARTNER-AUTH with the value set to your OpenTok API key and API secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<partner_secret>

However, this form of authentication (using X-TB-PARTNER-AUTH) is deprecated, and you should now use JSON Web tokens for authentication. (Use of this deprecated form of authentication will expire in July 2017.)

Creating a session

Generate a new session.

Resource URL:

https://api.opentok.com/session/create

Resource verb:

POST

POST header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Set the Accept header to application/json:

Accept:application/json

POST Parameters

archiveMode

Set to always to have the session archived automatically. With the archiveModeset to manual (the default), you can archive the session by calling the REST /archive POST method. If you set the archiveMode to always, you must also set the p2p.preference parameter to disabled (the default).

location

The IP address that TokBox will use to situate the session in its global network. If no location hint is passed in (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Pass a location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. Specify an IP address that is representative of the geographical location for the session.

p2p.preference

Set to enabled if you prefer clients to attempt to send audio-video streams directly to other clients; set to disabled for sessions that use the OpenTok Media Router. (Optional; the default setting is disabled -- the session uses the OpenTok Media Router.)

The OpenTok Media Router provides the following benefits:

  • The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the p2p.preference property is set to enabled, each client must send a separate audio-video stream to each client subscribing to it.)
  • The OpenTok Media Router can improve the quality of the user experience using audio fallback and video recovery. With these features, if a client's connectivity degrades to a degree that it does not support video for a stream it's subscribing to, the video is dropped on that client (without affecting other clients), and the client receives audio only. If the client's connectivity improves, the video returns.
  • The OpenTok Media Router supports the archiving feature, which lets you record, save, and retrieve OpenTok sessions.

With the p2p.preference property set to "enabled", the session will attempt to transmit streams directly between clients. If clients cannot connect due to firewall restrictions, the session uses the OpenTok TURN server to relay audio-video streams.

Sample Requests

POST /session/create HTTP/1.1
Host: https://api.opentok.com
X-OPENTOK-AUTH: json_web_token
Accept:application/json

location=10.1.200.30&p2p.preference=disabled

The following command line example creates a session that uses the OpenTok Media Router and specifies a location hint:

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr=location:10.1.200.30
curl \
   -X POST \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -H "$datastr" \
   $TB_url

The following command line example creates a session that attempts to transmit streams directly between clients (without using the OpenTok Media Router):

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr=p2p.preference:enabled
curl \
   -X POST \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -H "$datastr" \
   $TB_url

The following command line example creates an automatically-archived session:

export TB_url=https://api.opentok.com/session/create
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
datastr=archiveMode:always
curl \
   -X POST \
   -H "Accept:application/json" \
   -H "X-OPENTOK-AUTH:$json_web_token" \
   -H "$datastr" \
   $TB_url

Sample Response

The response is JSON data of the following form:

[
  {
    "session_id": "the session ID",
    "project_id": "your OpenTok API key",
    "create_dt": "The creation date",
    "media_server_url": "The URL of the OpenTok media router used by the session -- ignore this"
  }
]

Note that if you do not include the "Accept:application/json" header, the response format is XML. This XML version of the API call is deprecated.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or JWT token.

The HTTP response has a 500 status code for an OpenTok server error.

Sending a signal from your app server to connected clients

Use the Signal REST API to send signals to all participants in an active OpenTok session or to a specific client connected to that session. Signals sent from the server have an empty from parameter in the signal received handlers on clients connected to the session. For a signal sent from a participant in the session, the from property is set the connection ID of the client that sent the signal, but in this case there is no associated connection.

For both signal examples below, the request body will be used to forward both the type and data fields. These correspond to the type and data parameters passed in the client signal received handlers.

Signal all clients connected to the session

Send an HTTP POST to the signal resource of the session:

SESSION_ID=SOMESESSIONID
API_KEY=123456
JWT=jwt_token # replace with a JSON web token (see "Authentication")
DATA='{"type":"foo","data":"bar"}'
curl -v \
-H "Content-Type: application/json" \
-X POST \
-H "X-OPENTOK-AUTH:${JWT}" \
-d "${DATA}" \
http://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/signal

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

Signal a specific client connected to the session

Send an HTTP POST to the signal resource of a specific connection ID, belonging to the session:

SESSION_ID=SOMESESSIONID
CONNECTION_ID=SOMECONNECTIONID
API_KEY=123456
JWT=jwt_token # replace with a JSON web token (see "Authentication")
DATA='{"type":"foo","data":"bar"}'
curl -v \
-H "Content-Type: application/json" \
-X POST \
-H "X-OPENTOK-AUTH:${API_KEY}:${API_SECRET}" \
-d "${DATA}" \
http://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}/signal

Signaling error responses

Errors be returned in the response as HTTP Status Codes:

  • 400 — One of the signal properties — data, type, sessionId or connectionId — is invalid.
  • 403 — You are not authorized to send the signal. Check your authentication credentials.
  • 404 — The client specified by the connectionId property is not connected to the session.
  • 413 — The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB).

In an error case, the response body will look like this:

{ 
  "code" : 400,
  "message" : "One of the signal properties — data, type, sessionId or connectionId — is invalid."
}

Forcing a client endpoint to disconnect from a session

Your application server can disconnect a client from an OpenTok session by sending an HTTP DELETE request to the resource for that client's connection:

SESSION_ID=SOMESESSIONID
CONNECTION_ID=SOMECONNECTIONID
API_KEY=123456
JWT=jwt_token # replace with a JSON web token (see "Authentication")
curl -v \
-X DELETE \
-H "X-OPENTOK-AUTH:${JWT}" \
http://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

Error responses

Errors be returned in the response as HTTP Status Codes:

  • 400 — One of the arguments — sessionId or connectionId — is invalid.
  • 403 — You are not authorized to forceDisconnect, check your authentication credentials.
  • 404 — The client specified by the connectionId property is not connected to the session.

In an error case, the response body will look like this:

{
  "code" : 404,
  "message" : "Connection not found."
}

Starting an archive recording

To start recording an archive of an OpenTok session, submit an HTTP POST request.

To successfully start recording an archive, at least one client must be connected to the session.

You can only record one archive at a time for a given session. You can only record archives of sessions that use the OpenTok Media Router (with the media mode set to routed); you cannot archive sessions that have the media mode set to relayed. (See The OpenTok Media Router and media modes.)

For more information, see the OpenTok archiving developer guide.

HTTP POST to archive

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/archive

Replace <api_key> with your OpenTok API key. See the Project Page of your TokBox Account.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

POST header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Set the Content-type header to application/json:

Content-Type:application/json

POST data

Include a JSON object of the following form as the POST data:

{
    "sessionId" : "session_id",
    "hasAudio" : true,
    "hasVideo" : true,
    "name" : "archive_name"
    "outputMode" : "composed",
}

The JSON object includes the following properties:

  • sessionId (String) — (Optional) The session ID of the OpenTok session you want to start archiving
  • hasAudio (Boolean) — (Optional) Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.
  • hasVideo (Boolean) — (Optional) Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.
  • name (String) — (Optional) The name of the archive (for your own identification)
  • outputMode (String) — (Optional) Whether all streams in the archive are recorded to a single file ("composed", the default) or to individual files ("individual").

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "createdAt" : 1384221730555,
  "duration" : 0,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "The archive name you supplied",
  "projectId" : 234567,
  "reason" : "",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "started",
  "url" : null
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • hasAudio — Whether the archive will record audio (true) or not (false).
  • hasVideo — Whether the archive will record video (true) or not (false).
  • id — The unique archive ID. Store this value for later use (for example, to stop the recording).
  • projectId — Your OpenTok API key.
  • sessionId — The session ID of the OpenTok session being archived.
  • name — The name of the archive you supplied (this is optional)

The HTTP response has a 400 status code in the following cases:

  • You do not pass in a session ID or you pass in an invalid session ID.
  • No clients are actively connected to the OpenTok session.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or JWT token.

The HTTP response has a 404 status code if the session does not exist.

The HTTP response has a 409 status code if you attempt to start an archive for a session that does not use the OpenTok Media Router or if the session is already being recorded.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example starts recording an archive for an OpenTok session:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
name="Foo"
data='{"sessionId" : "'$session_id'", "name" : "'$name'"}'
curl \
     -i \
     -H "Content-Type: application/json" \
     -X POST \
     -d $data \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).
  • Set the session_id value to the session ID of the OpenTok session you want to archive.
  • Set the name value to the archive name (this is optional).

Stopping an archive recording

To stop recording an archive, submit an HTTP POST request.

Archives automatically stop recording after 120 minutes or when all clients have disconnected from the session being archived.

HTTP POST to archive

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>/stop

Replace <api_key> with your OpenTok API key. See your Project Page on your TokBox Account.

Replace <archive_id> with the archive ID. You can obtain the archive ID from the response to the API call to start recording the archive.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

POST header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "createdAt" : 1384221730555,
  "duration" : 60,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "The archive name you supplied",
  "projectId" : 234567,
  "reason" : "",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "stopped",
  "url" : null
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • hasAudio — Whether the archive will record audio (true) or not (false).
  • hasVideo — Whether the archive will record video (true) or not (false).
  • id — The unique archive ID.
  • projectId — Your OpenTok API key.
  • sessionId — The session ID of the OpenTok session that was archived.
  • name — The name of the archive you supplied (this is optional)
  • size — When the archive is stopped (and it has not been generated), the size is set to 0.
  • status — This is set to "stopped".
  • status — When the archive is stopped (and it has not been generated), this is set to null.

The HTTP response has a 400 status code if you do not pass in a session ID or you pass in an invalid session ID.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or JWT token.

The HTTP response has a 404 status code if you pass in an invalid archive ID.

The HTTP response has a 409 status code if you attempt to stop an archive that is not being recorded.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example stops recording an archive for an OpenTok session:

api_key=123456
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X POST \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive/$id/stop
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).
  • Set the id value to the archive ID. You can obtain the archive ID from the response to the API call to start recording the archive.

Listing archives

To list archives for your API key, both completed and in-progress, submit an HTTP GET request.

HTTP GET to archive

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/project/<api_key>/archive?offset=<offset>&count=<count>

Replace <api_key> with your OpenTok API key. See the Project Page in your TokBox Account.

Replace <offset> with the index offset of the first archive. 0 is offset of the most recently started archive (excluding deleted archive). 1 is the offset of the archive that started prior to the most recent archive. Setting <offset> is optional; the default is 0.

Replace <count> with the number of archives to be returned. Setting <count> is optional. The default number of archives returned is 50 (or fewer, if there are fewer than 50 archives). The maximum number of archives the call will return is 1000.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

Deleted archives are not included in the results of this API call.

Replace <api_key> with your OpenTok API key. See the Project Page in your TokBox Account.

GET header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "count" : 2,
  "items" : [ {
    "createdAt" : 1384221730000,
    "duration" : 5049,
    "hasAudio" : true,
    "hasVideo" : true,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "name" : "Foo",
    "projectId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 247748791,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
  }, {
    "createdAt" : 1384221380000,
    "duration" : 328,
    "hasAudio" : true,
    "hasVideo" : true,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "name" : "Foo",
    "projectId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
  } ]

The JSON object includes the following properties:

  • count — The total number of archives for the API key.
  • items — An array of objects defining each archive retrieved. Archives are listed from the newest to the oldest in the return set.

Each archive object (item) has the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • duration — The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.
  • hasAudio — Whether the archive will record audio (true) or not (false).
  • hasVideo — Whether the archive will record video (true) or not (false).
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)
  • projectId — Your OpenTok API key.
  • reason — For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".
  • sessionId — The session ID of the OpenTok session that was archived.
  • status — The status of the archive:
    • "available" — The archive is available for download from the OpenTok cloud.
    • "expired" — The archive is no longer available for download from the OpenTok cloud.
    • "failed" — The archive recording failed.
    • "paused" — The archive is in progress and no clients are publishing streams to the session. When an archive is in progress and any client publishes a stream, the status is "started". When an archive is "paused", nothing is recorded. When a client starts publishing a stream, the recording starts (or resumes). If all clients disconnect from a session that is being archived, the status changes to "paused", and after 60 seconds the archive recording stops (and the status changes to "stopped").
    • "started" — The archive started and is in the process of being recorded.
    • "stopped" — The archive stopped recording.
    • "uploaded" — The archive is available for download from the S3 bucket you specified in your TokBox Account.
  • size — The size of the archive file. For archives that have not been generated, this value is set to 0.
  • url — The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, use the REST API for retrieving archive information or listing archives.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or JWT token.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example retrieves information for all archives:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
curl \
    -i \
    -X GET \
    -H "X-OPENTOK-AUTH:$json_web_token" \
    https://api.opentok.com/v2/project/$api_key/archive
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).

Retrieving archive information

To retrieve information about a specific archive, submit an HTTP GET request.

You can also retrieve information about multiple archives. See Listing archives.

HTTP GET to archive

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
  • Replace <api_key> with your OpenTok API key. See the Project Page of your TokBox Account.
  • Replace <archive_id with the archive ID.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

GET header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "createdAt" : 1384221730000,
  "duration" : 5049,
  "hasAudio" : true,
  "hasVideo" : true,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "Foo",
  "projectId" : 123456,
  "reason" : "",
  "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
  "size" : 247748791,
  "status" : "available",
  "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • duration — The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.
  • hasAudio — Whether the archive will record audio (true) or not (false).
  • hasVideo — Whether the archive will record video (true) or not (false).
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)
  • projectId — Your OpenTok API key.
  • reason — For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".
  • sessionId — The session ID of the OpenTok session that was archived.
  • status — The status of the archive:
    • "available" — The archive is available for download from the OpenTok cloud.
    • "deleted" — The archive was deleted.
    • "expired" — The archive is no longer available for download from the OpenTok cloud.
    • "failed" — The archive recording failed.
    • "paused" — The archive is in progress and no clients are publishing streams to the session. When an archive is in progress and any client publishes a stream, the status is "started". When an archive is "paused", nothing is recorded. When a client starts publishing a stream, the recording starts (or resumes). If all clients disconnect from a session that is being archived, the status changes to "paused", and after 60 seconds the archive recording stops (and the status changes to "stopped").
    • "started" — The archive started and is in the process of being recorded.
    • "stopped" — The archive stopped recording.
    • "uploaded" — The archive is available for download from the S3 bucket you specified in your TokBox Account.
  • size — The size of the archive file. For archives that have not been generated, this value is set to 0.
  • url — The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, use the REST API for retrieving archive information or listing archives.

The HTTP response has a 400 status code if you do not pass in a session ID or you pass in an invalid archive ID.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or JWT token.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example retrieves information for an archive:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=23435236235235235235
curl \
    -i \
    -X GET \
    -H "X-OPENTOK-AUTH:$json_web_token" \
    https://api.opentok.com/v2/project/$api_key/archive/$archive
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).
  • Set the id value to the archive ID.

Deleting an archive

To delete an archive, submit an HTTP DELETE request.

You can only delete an archive which has a status of "available" or "uploaded". Deleting an archive removes its record from the list of archives (see Listing archives). For an "available" archive, it also removes the archive file, making it unavailable for download.

HTTP DELETE to archive

Submit an HTTP DELETE request to the following URL:

https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>

Replace <api_key> with your OpenTok API key. See the Project Page of your TokBox Account.

Replace <archive_id> with the archive ID.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

DELETE header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Response

An HTTP response with a status code of 204 indicates that the archive has been deleted.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key, an invalid JWT token, or an invalid archive ID.

The HTTP response has a 409 status code if the status of the archive is not "uploaded", "available", or "deleted".

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example deletes an archive:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X DELETE \
     -H "X-OPENTOK-AUTH:$json_web_token" \
     https://api.opentok.com/v2/project/$api_key/archive/$id
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).
  • Set the id value to the ID of the archive to delete.

Initiating a SIP call

To connect your SIP platform to an OpenTok session, submit an HTTP POST request to the dial method. The audio from your end of the SIP call is added to the OpenTok session as an audio-only stream. The OpenTok Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint.

The call ends when your SIP server sends a BYE message (to terminate the call). You can also end a call using the OpenTok REST API method to disconnect a client from a session. The OpenTok SIP gateway automatically ends a call after 5 minutes of inactivity (5 minutes without media received). Also, as a security measure, the OpenTok SIP gateway closes any SIP call that lasts longer than 6 hours.

The SIP interconnect feature requires that you use an OpenTok session that uses the OpenTok Media Router (a session with the media mode set to routed).

For more information, including technical details and security considerations, see the OpenTok SIP interconnect developer guide.

HTTP POST to dial

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/dial

Replace <api_key> with your OpenTok API key. See the Project Page of your TokBox Account.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

POST header properties

API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH — along with a JSON web token (JWT). See Authentication.

Set the Content-type header to application/json:

Content-Type:application/json

POST data

Include a JSON object of the following form as the POST data:

{
  "sessionId": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "sip": {
    "uri": "user@sip.partner.com;transport=tls",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false
  }
}

The JSON object includes the following properties:

  • sessionId​ (required) — The OpenTok session ID for the SIP call to join.
  • token​ (required) — The OpenTok token to be used for the participant being called. You can add token data to identify that the participant is on a SIP endpoint or for other identifying data, such as phone numbers. (The OpenTok client libraries include properties for inspecting the connection data for a client connected to a session.) See the Token Creation developer guide.
  • SIP uri​ ​(required) — The SIP URI to be used as destination of the SIP call initiated from OpenTok to your SIP platform.

    If the SIP ​uri​ contains a ​transport=tls​ header, the negotiation between TokBox and the SIP endpoint will be done securely. Note that this will only apply to the negotiation itself, and not to the transmission of audio. If you also audio transmission to be encrypted, set the ​secure​ property to ​true​.

    This is an example of secure call negotiation:

    "user@sip.partner.com;transport=tls"

    This is an example of insecure call negotiation:

    "user@sip.partner.com"
  • SIP headers​​ (optional) — This object defines custom headers to be added to the SIP ​INVITE​ request initiated from OpenTok to the your SIP platform. Each of the custom headers must start with the ​“X-"​ prefix, or the call will result in a Bad Request (400) response.
  • SIP auth​ (optional) — This object contains the username and password to be used in the the SIP INVITE​ request for HTTP digest authentication, if it is required by your SIP platform.
  • secure​ (optional) — A Boolean flag that indicates whether the media must be transmitted encrypted (​true​) or not (​false​, the default).

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
    "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
    "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
    "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
}

The JSON object includes the following properties:

  • id — A unique ID for the SIP call.
  • connectionId — The OpenTok connection ID for the SIP call's connection in the OpenTok session. You can use this connection ID to terminate the SIP call, using the OpenTok REST API.
  • sessionId — The OpenTok stream ID for the SIP call's stream in the OpenTok session.

The HTTP response has a 400 status code in the following cases:

  • You do not pass in a session ID or you pass in an invalid session ID.
  • You passed in a custom header that does not start with the ​“X-"​ prefix.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or an invalid JSON web token.

The HTTP response has a 404 status code if the session does not exist.

The HTTP response has a 409 status code if you attempt to start a SIP call for a session that does not use the OpenTok Media Router.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example connects your SIP endpoint to an OpenTok session:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
sip_uri='user@sip.partner.comwhen;transport=tls'
data='{\
    "sessionId" : "'$session_id'", \
    "token": "A valid OpenTok token", \
  "sip": { \
    "uri": "'$sip_uri'", \
    "auth": {
      "username": "username",
      "password": "password"
    }
  }
}'
curl \
  -i \
  -H "Content-Type: application/json" \
  -H "X-OPENTOK-AUTH:$json_web_token" \
    -d "$data" \
  https://api.opentok.com/v2/project/$api_key/dial
  • Set the value for api_key to your OpenTok API key.
  • Set the value for json_web_token to a JSON web token (see Authentication).
  • Set the session_id value to the session ID of the OpenTok session you want to connect to your SIP platform.
  • Set the sip_uri value to the SIP URI for your SIP endpoint.
  • Set the token value to a valid OpenTok connection token for the participant being called (see the Token Creation developer guide).
  • Set the username and password to the username and password for your SIP endpoint.

Starting a live streaming broadcast

Use this method to start a live streaming for an OpenTok session. This broadcasts the session using HTTP live streaming (HLS).

To successfully start broadcasting a session, at least one client must be connected to the session.

You can only have one active live streaming broadcast at a time for a session (however, having more than one would not be useful). You can only start live streaming for sessions that use the OpenTok Media Router (with the media mode set to routed); you cannot use live streaming with sessions that have the media mode set to relayed. (See The OpenTok Media Router and media modes.)

For more information about OpenTok live streaming, see the Broadcast developer guide.

HTTP POST to broadcast

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast

Replace <apiKey> with your OpenTok API key.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

POST header properties

Set the Content-Type header to application/json.

Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH — set to a JSON web token. See Authentication.

POST data

Include a JSON object of the following form as the request body content:

{
  "sessionId": "<session-id>",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  }
}

The JSON object includes the following properties:

  • sessionId (String) — Set this to the session ID of the OpenTok session you want to broadcast.
  • layout (Object) — Optional. Specify this to assign the initial layout type for the broadcast. Valid values for the layout property are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)). If you specify a "custom" layout type, set the stylesheet property of the layout object to the stylesheet. (For other layout types, do not set a stylesheet property.) If you do not specify an initial layout type, the HLS stream uses the Best Fit layout type. For more information, see Configuring Video Layout for the OpenTok live streaming feature.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "id": "1748b7070a81464c9759c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "broadcastUrls": {
    "hls": "http://example.com/2_MX40NDm0JaR1B-fg/stream.m3u8",
  }
}

The JSON object includes the following properties:

  • id — The unique ID for the broadcast
  • sessionId — The OpenTok session ID
  • projectId — Your OpenTok API key
  • createdAt — The time the broadcast started, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
  • updatedAt — For this start method, this timestamp matches the createdAt timestamp.
  • broadcastUrls — The URL for the HLS broadcast. Note this HLS broadcast URL points to an index file, an.M3U8 formatted playlist which contains a list of URLs to .ts media segment files (MPEG-2 transport stream files). While the URLs of both the playlist index file and media segment files are provided as soon as the HTTP response is returned, these URLs should not be accessed until 15 - 20 seconds later, after the initiation of the HLS broadcast, due to the delay between the HLS broadcast and the live streams in the OpenTok session. See https://developer.apple.com/library/ios/technotes/tn2288/_index.html for more information about the playlist index file and media segment files for HLS.

The HTTP response will have one of the following status codes:

  • 200 — Success.
  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options.
  • 403 — Authentication error.
  • 409 — The broadcast has already started for the session.
  • 500 — OpenTok server error.

Example

curl -i \
   -X POST \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"sessionId\":OPENTOK_SESSION_ID} \
   https://api.opentok.com/v2/project/$apiKey/broadcast

Stopping a live streaming broadcast

Use this method to stop a live broadcast of an OpenTok session. Note that broadcasts automatically stop 120 minutes after they are started.

HTTP POST to broadcast/<broadcastId>/stop

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>/stop

Replace <apiKey> with your OpenTok API key. Replace <broadcastId> with the ID of the broadcast you want to stop. You get the broadcast ID when you start a broadcast.

POST header properties

Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH — set to a JSON web token. See Authentication.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437936607000,
  "broadcastUrls": null
}

The JSON object includes the following properties:

  • id — The unique ID for the broadcast
  • sessionId — The ID for the OpenTok session being broadcast
  • projectId — Your OpenTok API key
  • createdAt — The time the broadcast started, expressed in seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
  • updatedAt — The time the broadcast was stopped, expressed in seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
  • broadcastUrls — This is set to null for the stop method

The HTTP response will have one of the following status codes:

  • 200 — Success.
  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON.
  • 403 — Authentication error.
  • 404 — The broadcast (with the specified ID) was not found or it has already stopped.
  • 500 — OpenTok server error.

Example

curl -i \
-X POST \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID/stop

Getting information about a live streaming broadcast

Use this method to get the HLS URL for a broadcast that is in-progress.

HTTP GET to broadcast

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>

Replace <apiKey> with your OpenTok API key. Replace <broadcastId> with the ID of the broadcast. You get the broadcast ID when you start a broadcast.

Note: Previously, this REST URL used /partner (which is now deprecated) instead of /project.

POST header properties

Set the Content-Type header to application/json.

Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH — set to a JSON web token. See Authentication.

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "broadcastUrls": {
    "hls": "http://example.com/2_MX40NDm0JaR1B-fg/stream.m3u8",
  },
    "status": "started" || "stopped"
}

The JSON object includes the following properties:

  • id — The unique ID for the broadcast
  • sessionId — The OpenTok session ID
  • projectId — Your OpenTok API key
  • createdAt — The time the broadcast started, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC)
  • updatedAt — For this GET method, this timestamp matches the createdAt timestamp.
  • broadcastUrls — The URL for the HLS broadcast. See the OpenTok live streaming developer guide for more information on how to use this URL.
  • status — The status of the broadcast — either "started" or "stopped".

The HTTP response will have one of the following status codes:

  • 200 — Success
  • 400 — Invalid request
  • 403 — Authentication error
  • 404 — No matching broadcast found (with the specified ID)
  • 500 — OpenTok server error

Example

curl -i \
  -X GET \
  -X Content-Type:application/json \
  -H X-OPENTOK-AUTH:JWT_TOKEN \
  https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID

Dynamically changing the layout type during a live streaming broadcast

You can dynamically change the layout type of a live streaming broadcast.

For more information about OpenTok live streaming broadcasts, see the Broadcast developer guide.

HTTP PUT to broadcast

Submit an HTTP PUT request to the following URL:

https://api.opentok.com/v2/project/<apiKey>/broadcast/<broadcastId>/layout

Replace <apiKey> with your OpenTok API key.

Replace <broadcastId> with the broadcast ID.

PUT header properties

Set the Content-Type header to application/json.

Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH — set to a JSON web token. See Authentication.

PUT data

Include a JSON object of the following form as the request body content:

{
  "type": "custom",
  "stylesheet": "the layout stylesheet (only used with type == custom)"
}

The JSON object includes the following properties:

  • type (String) — The layout type for the broadcast. Valid values are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)). If you specify a "custom" layout type, set the stylesheet property to the stylesheet. (For other layout types, do not set the stylesheet property.) For more information, see Configuring Video Layout for the OpenTok live streaming feature.
  • stylesheet (Object) — Optional. Specify this only if you set the type property to "custom". Set the stylesheet property to the stylesheet. (For other layout types, do not set the stylesheet property.) For more information, see Defining custom layouts.

When specifying a layout type other than the Best Fit layout type, be sure to apply appropriate layout classes for streams in the OpenTok session (see Assigning live streaming layout classes to OpenTok streams.

Response

The HTTP response will have one of the following status codes:

  • 200 — Success.
  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options.
  • 403 — Authentication error.
  • 500 — OpenTok server error.

Example

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"type\":"verticalPresentation"} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$broadcastId/layout

Changing the live streaming layout classes for an OpenTok stream

Use this method to change layout classes for an OpenTok stream. The layout classes define how the stream is displayed in the layout of the HLS stream. For more information, see Assigning live streaming layout classes to OpenTok streams in the Broadcast developer guide.

HTTP PUT to broadcast

Submit an HTTP PUT request to the following URL:

https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream

Replace <apiKey> with your OpenTok API key.

Replace <sessionId> with your the session ID.

PUT header properties

Set the Content-Type header to application/json.

Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH — set to a JSON web token. See Authentication.

PUT data

Include a JSON object of the following form as the request body content:

{
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "layoutClassList": ["full"]
    }
  ]
}

The JSON object includes an items array of objects. Each object defines the layout classes to assign to a stream, and it contains following properties:

  • id (String) — The stream ID.
  • layoutClassList (Array) — An array of layout classes (each strings) for the stream.

You can update the layout class list for multiple streams by passing in multiple JSON objects in the items array.

Response

The HTTP response will have one of the following status codes:

  • 200 — Success.
  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options.
  • 403 — Authentication error.
  • 500 — OpenTok server error.

Example

curl -i \
   -X PUT \
   -H X-OPENTOK-AUTH:JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"streamId\":STREAM_ID,\"layoutClassList\":[\"CLASS_NAME\"]} \
   https://api.opentok.com/v2/project/$apiKey/session/$sessionId