Use the OpenTok REST API to generate OpenTok sessions, to work with archives, and to work with live streaming broadcasts. The OpenTok server SDKs (for Java, .NET, Node.js, PHP, Python, and Ruby) implement many of the methods of the REST API.
The REST API includes methods for the following:
Session creation, signaling, and moderation
Archiving
SIP interconnect
Live streaming broadcasts
Account management
The OpenTok SDKs wrap the OpenTok REST API to make it easier to make calls to the OpenTok platform.
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. For most REST API calls, use the
API key for the specific project in your account. This is provided on the
Project page of your TokBox Account.
However, the following REST methods are restricted to registered administrators
for the OpenTok account. To use these methods, you must set iss
to the
account-level API key, which is only available to account administrators.
(see Account Management):
To obtain the account-level API key and secret, log on to your TokBox Account, click Account Settings in the left-hand menu, and then under OpenTok REST API, click View account keys.
For most REST API calls, set ist
to "project"
. However, for the following
Account Management REST methods, set
ist
to "account"
:
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. For most REST API calls, use the API secret for the specific project in your account. This is provided on the Project page of your TokBox Account. However, the following REST methods are restricted to registered administrators for the OpenTok account. To use these methods, you must use the account-level API key and secret (which is only available to account administrators) as the JWT secret key (see Account Management):
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-API-key",
"iat": int(time.time()),
"exp": int(time.time()) + 180,
"ist": "project",
"jti": str(uuid.uuid4())},
'my-OpenTok-API-secret',
algorithm='HS256')
Replace the my-OpenTok-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.)
Generate a new session.
https://api.opentok.com/session/create
POST
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/x-www-form-urlencoded
:
Content-Type:application/x-www-form-urlencoded
Set the Accept
header to application/json
:
Accept:application/json
archiveMode
Set to always
to have the session archived automatically. With the
archiveMode
set 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:
enabled
, each client must send
a separate audio-video stream to each client subscribing to it.)
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.
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 "Content-Type:application/x-www-form-urlencoded" \
-H "Accept:application/json" \
-H "X-OPENTOK-AUTH:$json_web_token" \
-d $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 "Content-Type:application/x-www-form-urlencoded" \
-H "Accept:application/json" \
-H "X-OPENTOK-AUTH:$json_web_token" \
-d $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 "Content-Type:application/x-www-form-urlencoded" \
-H "Accept:application/json" \
-H "X-OPENTOK-AUTH:$json_web_token" \
-d $datastr \
$TB_url
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.
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.
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}" \
https://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
.
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}" \
https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection/${CONNECTION_ID}/signal
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."
}
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}" \
https://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
.
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."
}
Use this method to get information on an OpenTok stream (or all streams in a session).
For example, you can call this method to get information about layout classes used by an OpenTok stream. The layout classes define how the stream is displayed in the layout of a broadcast stream. For more information, see Assigning live streaming layout classes to OpenTok streams.
To get layout class information for a specific stream, submit an HTTP GET request to the following URL:
https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream/<streamId>
Replace <apiKey>
with your OpenTok API key.
Replace <sessionId>
with the session ID.
Replace <streamId>
with the stream ID.
To get layout class information for all streams in a session, submit an HTTP GET request to the following URL (leaving out the stream ID at the end):
https://api.opentok.com/v2/project/<apiKey>/session/<sessionId>/stream/
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
—
set to a JSON web token. See Authentication.
When getting layout class info for a single stream, the response's JSON data includes a layoutClassList
array:
{
"id": "8b732909-0a06-46a2-8ea8-074e64d43422",
"videoType": "camera",
"name": "",
"layoutClassList": ["full"]
}
layoutClassList
property is an array of the layout classes for the stream.id
property is the stream ID.videoType
property is either "camera" or "screen".name
property is the stream name (if one was set when the client published the stream).When getting layout class info for a multiple streams, the response's JSON data includes an items
property, which is array containing layout information for streams in the session:
{
"count": 2
"items": [
{
"id": "8b732909-0a06-46a2-8ea8-074e64d43422",
"videoType": "camera",
"name": "",
"layoutClassList": ["full"]
},
...
]
}
The HTTP response will have one of the following status codes:
The following command line example retrieves layout class information for a specific stream:
api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=23435236235235235235
stream_id=88ff99fc203a5bc
curl -i \
-X GET \
-H X-OPENTOK-AUTH:json_web_token \
https://api.opentok.com/v2/project/$api_key/session/$session_id/stream/$stream_id
api_key
to your OpenTok API key.json_web_token
to a JSON web token (see Authentication).session_id
value to the session.stream_id
value to the stream ID.The following command line example retrieves layout class information for all streams in a session:
api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=23435236235235235235
curl -i \
-X GET \
-H X-OPENTOK-AUTH:json_web_token \
https://api.opentok.com/v2/project/$api_key/session/$session_id/stream/
api_key
to your OpenTok API key.json_web_token
to a JSON web token (see Authentication).session_id
value to the session.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.
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
.
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
Include a JSON object of the following form as the POST data:
{
"sessionId" : "session_id",
"hasAudio" : true,
"hasVideo" : true,
"layout" : {
"type": "custom",
"stylesheet": "the layout stylesheet (only used with type == custom)"
}
"name" : "archive_name"
"outputMode" : "composed",
"resolution" : "640x480",
}
The JSON object includes the following properties:
sessionId
(String) — (Required) The session ID of the OpenTok session you want to start archivinghasAudio
(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.layout
(Object) — Optional. Specify this to assign the initial layout type for
the archive. This applies only to
composed
archives. 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 archive uses the best fit layout type. For more information, see
Customizing the video layout for composed archives.
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"
). See
Individual stream
and composed archives.resolution
(String) — (Optional) The resolution of the archive,
either "640x480"
(SD, the default) or "1280x720"
(HD). This property
only applies to composed archives. If you set this property and set the outputMode
property to "individual"
, the call to the REST method results in an error.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",
"outputMode" : "composed",
"projectId" : 234567,
"reason" : "",
"resolution" : "640x480",
"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).outputMode
— Either "composed"
or "individual"
. See
Individual stream
and composed archives.projectId
— Your OpenTok API key.resolution
— The resolution of the archive (either "640x480" or "1280x720").
This property is only set for composed archives.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:
resolution
value.outputMode
property is set to "individual"
and
you set the resolution
property and (which is not supported in individual
stream 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 404 status code if the session does not exist, or if the session exists but there are no clients connected to it.
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.
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
api_key
to your OpenTok API key.json_web_token
to a JSON web token
(see Authentication).session_id
value to the session ID of the OpenTok session you want to archive.name
value to the archive name (this is optional).To stop recording an archive, submit an HTTP POST request.
Archives stop recording after 2 hours (120 minutes), or 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing. However, automatic archives continue recording to multiple consecutive files of up to 2 hours in length each.
Calling this method for automatic archives has no effect. Automatic archives continue recording to multiple consecutive files of up to 2 hours in length each, until 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing a stream to the session.
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
.
API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH
— along with a JSON web token (JWT). See Authentication.
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" : "",
"resolution" : "640x480",
"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.resolution
— The resolution of the archive (either "640x480" or "1280x720").
This property is only set for composed archives.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.
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
api_key
to your OpenTok API key.json_web_token
to a JSON web token
(see Authentication).id
value to the archive ID. You can obtain the archive ID from the response to the API call to
start recording the archive.To list archives for your API key, both completed and in-progress, submit an HTTP GET request.
Submit an HTTP GET 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 in your TokBox Account.
Note: Previously, this REST URL used /partner
(which is now deprecated)
instead of /project
.
You can add query parameters to filter the results (these are optional):
Set an offset
query parameters to specify 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. The default value is 0.
Set a count
query parameter to limit the number of archives to be returned. 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.
Set a sessionId
query parameter to list archives for a specific session ID.
(This is useful when listing multiple archives for an automatically archived
session.)
For example the following call specifies a count
and offset
values:
https://api.opentok.com/v2/project/<api_key>/archive?offset=400&count=20
The following call specifies a (fake) sessionId
value:
https://api.opentok.com/v2/project/<api_key>/archive?sessionId=2_MX4xMDB-flR1-QxNzIxNX4
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.
API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH
— along with a JSON web token (JWT). See Authentication.
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" : "",
"resolution" : "640x480",
"sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
"size" : 247748791,
"status" : "available",
"url" : "https://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" : "",
"resolution" : "640x480",
"sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
"size" : 18023312,
"status" : "available",
"url" : "https://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"
— When an archive is paused, nothing is recorded.
The archive is paused if any of the the following conditions occur:
"stopped"
.
"stopped"
.
"started"
.
"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.resolution
— The resolution of the archive (either "640x480" or "1280x720").
This property is only set for composed archives.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.
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
api_key
to your OpenTok API key.json_web_token
to a JSON web token
(see Authentication).To retrieve information about a specific archive, submit an HTTP GET request.
You can also retrieve information about multiple archives. See Listing archives.
Submit an HTTP GET request to the following URL:
https://api.opentok.com/v2/project/<api_key>/archive/<archive_id>
<api_key>
with your OpenTok API key. See the Project Page of your TokBox Account.<archive_id
with the archive ID.
Note: Previously, this REST URL used /partner
(which is now deprecated)
instead of /project
.
API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH
— along with a JSON web token (JWT). See Authentication.
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",
"outputMode" : "composed",
"projectId" : 123456,
"reason" : "",
"resolution" : "640x480",
"sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
"size" : 247748791,
"status" : "available",
"url" : "https://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)outputMode
— Either "composed"
or "individual"
. See
Individual stream
and composed archives.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"
.resolution
— The resolution of the archive (either "640x480" or "1280x720").
This property is only set for composed archives.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"
— When an archive is paused, nothing is recorded.
The archive is paused if any of the the following conditions occur:
"stopped"
.
"stopped"
.
"paused"
state, the archive
recording resumes and the status changes back to "started"
.
"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.
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
api_key
to your OpenTok API key.json_web_token
to a JSON web token
(see Authentication).id
value to the archive ID.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.
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
.
API calls must be authenticated using a custom HTTP header — X-OPENTOK-AUTH
— along with a JSON web token (JWT). See Authentication.
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.
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
api_key
to your OpenTok API key.json_web_token
to a JSON web token
(see Authentication).id
value to the ID of the archive to delete.For an OpenTok project, you can have OpenTok upload completed archives to an Amazon S3 bucket (or an S3-compliant storage provider) or Windows Azure container.
Note: You can also set an archive upload target on your TokBox account page.
For Amazon S3, you will need to provide TokBox with upload-only permission to the Amazon S3 bucket. If you want to use an S3 IAM user, assign it the following user policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Resource": [ "arn:aws:s3:::<your-bucket-name>/*" ],
"Action": [
"s3:PutObject",
"s3:ListBucket"
]
},
{
"Sid": "Stmt2",
"Effect": "Allow",
"Resource": [ "arn:aws:s3:::*" ],
"Action": [
"s3:ListAllMyBuckets"
]
}
]
}
To set an archive upload target, submit an HTTP PUT request.
If you set an upload target, each completed archive file is uploaded as a file
named archive.mp4 in the path /projectKey/archiveId/
of the target bucket,
where projectKey
is the project API key, and archiveId
is the archive ID.
If you have already set an archive upload target for a project's archive files, you can submit another PUT request to register a new upload target.
For more information on archiving, see the archiving programming guide.
Submit an HTTP PUT request to the following URL:
https://api.opentok.com/v2/project/<api_key>/archive/storage
Replace <api_key>
with the OpenTok project API key.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication).
Set the Content-type
header to application/json
:
Content-Type:application/json
For an Amazon S3 bucket, include a JSON object of the following form as the PUT data:
{
"type": "s3",
"config": {
"accessKey":"myUsername",
"secretKey":"myPassword",
"bucket": "bucketName",
"endpoint": "http://s3.cloudianhyperstore.com"
},
"fallback":"none"
}
The JSON object includes the following properties:
type
— "s3"`
(for Amazon S3)
config
— Settings for the Amazon Web Services account:
accessKey
— The Amazon Web Services access key
secretKey
— The Amazon Web Services secret key
bucket
— The S3 bucket name.
endpoint
(optional) — An S3 endpoint. This is optional. The default
endpoint is http://s3.amazonaws.com
(the endpoint for Amazon S3). Specify this
if you want to use an S3-compliant storage solution (other than Amazon S3).
Set this to the endpoint base URL, including the protocol (http or https),
such as "https://s3.cloudianhyperstore.com"
.
We support Cloudian as an S3-compatible storage solution. Other S3-compatible
services may have feature limitations.
fallback
— Set this to "opentok"
to have the archive available at the
OpenTok dashboard if upload fails. Set this to "none"
(or omit the property) to
prevents archive files from being stored in the OpenTok cloud if the upload
fails.
For a Windows Azure container, include a JSON object of the following form as the PUT data:
{
"type": "azure",
"config": {
"accountName":"myAccountname",
"accountKey":"myAccountKey",
"container": "containerName",
"domain": "domainName"
},
"fallback":"none"
}
The JSON object includes the following properties:
type
— "azure"
(for Microsoft Azure)
config
— Settings for the Windows Azure account:
accountName
— The Windows Azure account name
accountKey
— The Windows Azure account key
container
— The Windows Azure container name.
domain
(optional) — The Windows Azure domain in which
the container resides.
fallback
— Set this to "opentok"
to have the archive available at the
OpenTok dashboard if upload fails. Set this to "none"
(or omit the property)
to prevents archive files from being stored in the OpenTok cloud if the
upload fails.
The HTTP response will have one of the following status codes:
200 — Success. The response body matches the data you submitted.
400 — Invalid request. This response may indicate the following:
The type is undefined.
The type is unsupported (it is not "s3"
or "azure"
).
The config is undefined.
Your request data includes invalid JSON.
X-OPENTOK-AUTH
header.The following command line example sets an S3 bucket for a project:
token=123456789 # Change this to your JWT token
projectKey=55555 # Change this to the project API key
storage_type=s3
access_key=myUsername # Change this to your S3 access key
secret_key=myPassword # Change this to your S3 secret key
bucket=bucketName # Change this to the bucket name
data='{"type": "$storage_type", "config": { "accessKey":"$access_key", "secretKey":"$secret_key", "bucket": "$bucket"}}'
curl \
-i \
-H "Content-Type: application/json" \
-X PUT -H "X-TB-OPENTOK-AUTH:$token" -d "$data" \
https://api.opentok.com/v2/project/$partnerKey/archive/storage
Set the value for token
to a valid OpenTok JWT token.
Set the value for projectKey
to the project API key.
Set the storage_type
value to "s3"
.
Set the access_key
value to the access key for your Amazon Web Services
account.
Set the secret_key
value to the secret key for your Amazon Web Services
account.
Set the bucket
value to the bucket name.
If you have set an archive upload target for a project's archive files, you can delete it.
Note: You can also delete an archive upload target on your TokBox account page.
Submit an HTTP DELETE request to the following URL:
https://api.opentok.com/v2/project/<project_key>/archive/storage
Replace <project_key>
with the project API key.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication).
The HTTP response will have one of the following status codes:
204 — Success.
403 — Authentication error. You passed in an invalid token in the X-OPENTOK-AUTH header.
404 — No upload target exists.
### Example
The following command line example deletes an upload target for a project:
token=123456789 # Change this to your JWT token
projectKey=55555 # Change this to the project key
curl \
-i \
-H "Content-Type: application/json" \
-X DELETE -H "X-OPENTOK-AUTH:$token" \
https://api.opentok.com/v2/project/$projectKey/archive/storage
Set the value for token
to a valid OpenTok JWT token.
Set the value for projectKey
to the project API key.
You can dynamically change the layout type of a composed archive while it is being recorded.
For more information about composed archiving, see the OpenTok archiving developer guide and Customizing the video layout for composed archives.
Submit an HTTP PUT request to the following URL:
https://api.opentok.com/v2/project/<apiKey>/archive/<archiveId>/layout
Replace <apiKey>
with your OpenTok API key.
Replace <archiveId>
with the archive ID.
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.
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 archive. 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 Customizing the video layout for composed archives.
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.
The HTTP response will have one of the following status codes:
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/archive/$archiveId/layout
Use this method to change layout classes for an OpenTok stream. The layout classes define how the stream is displayed in the layout of a composed OpenTok archive. For more information, see Assigning live streaming layout classes to OpenTok streams.
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 the session ID.
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.
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:
You can update the layout class list for multiple streams by passing in multiple JSON objects
in the items
array.
The HTTP response will have one of the following status codes:
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
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.
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
.
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
Include a JSON object of the following form as the POST data:
{
"sessionId": "OpenTok session ID",
"token": "A valid OpenTok token",
"sip": {
"uri": "sip:user@sip.partner.com;transport=tls",
"from": "from@example.com",
"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.
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:
"sip:user@sip.partner.com;transport=tls"
This is an example of insecure call negotiation:
"sip:user@sip.partner.com"
from
(optional): The number or string that will be sent to the final SIP number
as the caller. It must be a string in the form of from@example.com
, where
from
can be a string or a number. If from
is set to a number (for example, "14155550101@example.com"
), it will show up as the incoming number on
PSTN phones. If from
is undefined or set to a string (for example,
"joe@example.com"
), +00000000 will show up as the incoming number on PSTN phones.
headers
(optional) — This object defines custom headers to be added to
the SIP INVITE
request initiated from OpenTok to your SIP platform.
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).
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.
streamId
— 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:
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.
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='sip: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
api_key
to your OpenTok API key.
json_web_token
to a JSON web token (see
Authentication).
session_id
value to the session ID of the OpenTok session you want
to connect to your SIP platform.
sip_uri
value to the SIP URI for your SIP endpoint.
token
property of the data
JSON to a valid OpenTok
connection token for the participant being called (see the
Token Creation developer guide).
username
and password
properties of the data
JSON to the username and password for your SIP endpoint. (This is optional.)
Use this method to start a live streaming for an OpenTok session. This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams.
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). The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simulteneously for a session. 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.
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
.
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.
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)"
},
"maxDuration": 5400,
"outputs": {
"hls": {},
"rtmp": [{
"id": "foo",
"serverUrl": "rtmps://myfooserver/myfooapp",
"streamName": "myfoostream"
},
{
"id": "bar",
"serverUrl": "rtmp://mybarserver/mybarapp",
"streamName": "mybarstream"
}]
},
"resolution": "640x480"
}
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 broadcast stream uses the Best Fit layout type. For more information, see
Configuring Video Layout for the OpenTok live streaming feature.
maxDuration
(Integer) — Optional. The maximum duration for the broadcast,
in seconds. The broadcast will automatically stop when the maximum duration is reached.
You can set the maximum duration to a value from 60 (60 seconds) to 36000 (10 hours).
The default maximum duration is 2 hours (7200 seconds).
outputs
(Object) — Required. This object defines the types of broadcast
streams you want to start (both HLS and RTMP). You can include HLS, RTMP, or both as broadcast
streams. If you include RTMP streaming, you can specify up to five target RTMP streams (or just
one).
serverUrl
(the RTMP server URL),
streamName
(the stream name, such as the YouTube Live stream name or the
Facebook stream key), and (optionally) id
(a unique ID for the stream). If you
specify an ID, it will be included in the REST call response and the REST
method for getting information about a live streaming broadcast. TokBox streams the session
to each RTMP URL you specify. Note that OpenTok live streaming supports RTMP and RTMPS.
For HLS, include a single hls
property in the outputs
object. Set this
property to an empty object (as in the example above). The HLS URL is returned in the response
and in the REST method for getting information about a live streaming broadcast.
resolution
(String) — The resolution of the broadcast: either
"640x480"
(SD, the default) or "1280x720"
(HD). This property
is optional.
If you need to support only one RTMP URL, you can pass in an object (instead of an array of
objects) for the rtmp
property value in the POST data you supply when calling
the REST method. For example, the following POST data specifies one RTMP output URL (and does
not include HLS output):
{
"sessionId": "<session-id>",
"layout": {
"type": "custom",
"stylesheet": "the layout stylesheet (only used with type == custom)"
},
"outputs": {
"rtmp": {
"id": "my-id",
"serverUrl": "rtmp://myserver/myapp",
"streamName": "my-stream-name"
}
}
}
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,
"resolution": "640x480",
"status": "started",
"broadcastUrls": {
"hls" : "http://server/fakepath/playlist.m3u8",
"rtmp": [{
"id": "foo",
"status": "connecting",
"serverUrl": "rtmps://myfooserver/myfooapp",
"streamName": "myfoostream",
}, {
"id": "bar",
"status": "connecting",
"serverUrl": "rtmp://mybarserver/mybarapp",
"streamName": "mybarstream",
}]
}
}
The JSON object includes the following properties:
id
— The unique ID for the broadcastsessionId
— The OpenTok session IDprojectId
— Your OpenTok API keycreatedAt
— 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.resolution
— The resolution of the broadcast (either "640x480" or "1280x720").status
— This is set to "started"
.
broadcastUrls
— An object containing details about the HLS and RTMP
broadcasts.
If you specified an HLS endpoint, the object includes an hls
property, which is
set to the URL for the HLS broadcast. Note this HLS broadcast URL points to an index file,
an .M3U8-formatted playlist that 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.
If you specified RTMP stream endpoints, the object includes an rtmp
property.
This is an array of objects that include information on each of the RTMP streams. Each of
these objects has the following properties: id
(the ID you assigned to
the RTMP stream), serverUrl
(the server URL), streamName
(the stream name), and status
property (which is set to
"connecting"
). You can call the OpenTok REST method
to check for status updates for the broadcast.
The HTTP response will have one of the following status codes:
curl -i \
-X POST \
-H X-OPENTOK-AUTH:JWT_TOKEN \
-H "Content-Type:application/json" \
-D "{ \
\"sessionId\": \"your-opentok-session-id\", \
\"layout\": { \
\"type\": \"custom\", \
\"stylesheet\": \"custom-stylesheet-data\" \
}, \
\"outputs\": { \
\"hls\": {}, \
\"rtmp\": [{ \
\"id\": \"foo\", \
\"serverUrl\": \"rtmps://myfooserver/myfooapp\", \
\"streamName\": \"myfoostream\" \
}, \
{ \
\"id\": \"bar\", \
\"serverUrl\": \"rtmp://mybarserver/mybarapp\", \
\"streamName\": \"mybarstream\" \
}] \
} \
}" \
https://api.opentok.com/v2/project/$apiKey/broadcast
Use this method to stop a live broadcast of an OpenTok session. Note that broadcasts automatically stop 120 minutes after they are started.
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.
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
.
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,
"resolution": "640x480",
"broadcastUrls": null
}
The JSON object includes the following properties:
id
— The unique ID for the broadcastsessionId
— The ID for the OpenTok session being broadcast projectId
— Your OpenTok API keycreatedAt
— 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)resolution
— The resolution of the broadcast (either "640x480"
or "1280x720").broadcastUrls
— This is set to null for the stop methodThe HTTP response will have one of the following status codes:
curl -i \
-X POST \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID/stop
Use this method to get details on broadcasts that are in progress and started. Completed broadcasts are not included in the listing.
Submit an HTTP GET request to the following URL:
https://api.opentok.com/v2/project/<apiKey>/broadcast
Replace <apiKey>
with your OpenTok API key.
The following query parameters are accepted:
offset
(optional) — The start offset in the list of existing broadcastscount
(optional, default: 50, maximum: 1000) — The number of broadcasts
to retrieve starting at offsetsessionId
(optional): Retrive only broadcasts for a given session IDAuthenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
—
set to a JSON web token. See Authentication.
The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:
{
"count" : 2,
"items" : [
{
"id": "1748b707-0a81-464c-9759-c46ad10d3734",
"sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
"projectId": 100,
"createdAt": 1437676551000,
"updatedAt": 1437676551000,
"resolution": "640x480",
"broadcastUrls": {
"hls" : "http://server/fakepath/playlist.m3u8",
"rtmp": {
"foo": {
"serverUrl": "rtmps://myfooserver/myfooapp",
"streamName": "myfoostream",
"status": "started"
},
"bar": {
"serverUrl": "rtmp://mybarserver/mybarapp",
"streamName": "mybarstream",
"status": "live"
}
}
}
"status": "started"
}, {
"id": "1c46ad10-0a81-464c-9759-748b707d3734",
"sessionId": "2_MX2NzY1NDgwMTJ4xMDBfjE0Mzc-Tfn4jMz",
"projectId": 100,
"createdAt": 1437676853000,
"updatedAt": 1437676853000,
"resolution": "640x480",
"broadcastUrls": {
"hls" : "http://server/fakepath2/playlist.m3u8",
"rtmp": {
"foo": {
"serverUrl": "rtmp://myfooserver/myfooapps",
"streamName": "myfoostreams",
"status": "live"
}
}
}
"status": "started"
}
]
}
The JSON object includes the following properties:
count
— The total number of broadcasts in the results.items
— An array of objects defining each broadcast retrieved.
Broadcasts are listed from the newest to the oldest in the return set.Each broadcast object (item) has the following properties:
id
— The unique ID for the broadcastsessionId
— The OpenTok session IDprojectId
— Your OpenTok API keycreatedAt
— 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.resolution
— The resolution of the broadcast (either "640x480"
or "1280x720").status
— The status of the broadcast. This method only returns broadcasts
with the status set to "started"
.broadcastUrls
— Details on the HLS and RTMP broadcast streams. For an HLS
stream, the URL is provided. See the
OpenTok live streaming developer guide for more information on how to use this URL.
For each RTMP stream, the RTMP server URL and stream name are provided, along with the RTMP
stream's status. The status
property is set to one of the following:connecting
— The OpenTok platform is in the process of connecting to the
remote RTMP server. This is the initial state, and it is the status if you start when there
are no streams published in the session. It changes to "live" when there are streams (or it
changes to one of the other states).live
— The OpenTok platform has successfully connected to the remote RTMP
server, and the media is streaming.offline
— The OpenTok platform could not connect to the remote RTMP
server. This is due to an unreachable server or an error in the RTMP handshake. Causes
include rejected RTMP connections, non-existing RTMP applications, rejected stream names,
authentication errors, etc. Check that the server is online, and that you have provided the
correct server URL and stream name.error
— There is an error in the OpenTok platform.The HTTP response will have one of the following status codes:
Listing all broadcasts (up to 50):
curl -i \
-X GET \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast
Listing a range of broadcasts:
curl -i \
-X GET \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast?offset=200&count=100
Listing broadcasts for a specified session ID:
SESSION_ID="1_MX40NTMyODc3Mn5-MTU1MDg3NDIHVXBxbkp3Qzd-fg"
curl -i \
-X GET \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast?sessionId=$SESSION_ID
Use this method to get details on a broadcast that is in-progress.
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
.
<h3">GET header properties
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
—
set to a JSON web token.
See Authentication.
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,
"resolution": "started",
"broadcastUrls": {
"hls" : "http://server/fakepath/playlist.m3u8",
"rtmp": {
"foo": {
"serverUrl": "rtmps://myfooserver/myfooapp",
"streamName": "myfoostream",
"status": "live"
},
"bar": {
"serverUrl": "rtmp://mybarserver/mybarapp",
"streamName": "mybarstream",
"status": "live"
}
}
}
"status": "started"
}
The JSON object includes the following properties:
id
— The unique ID for the broadcastsessionId
— The OpenTok session IDprojectId
— Your OpenTok API keycreatedAt
— 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.resolution
— The resolution of the broadcast (either "640x480"
or "1280x720").status
— The status of the broadcast: either "started"
or
"stopped"
.broadcastUrls
— Details on the HLS and RTMP broadcast streams. For an HLS
stream, the URL is provided. See the
OpenTok live streaming developer guide for more information on how to use this URL.
For each RTMP stream, the RTMP server URL and stream name are provided, along with the RTMP
stream's status.
status
— The status of the RTMP stream. Poll frequently to check status
updates. This property set to one of the following:
connecting
— The OpenTok platform is in the process of connecting to the
remote RTMP server. This is the initial state, and it is the status if you start when there
are no streams published in the session. It changes to "live" when there are streams (or it
changes to one of the other states).
live
— The OpenTok platform has successfully connected to the remote RTMP
server, and the media is streaming.
offline
— The OpenTok platform could not connect to the remote RTMP
server. This is due to an unreachable server or an error in the RTMP handshake. Causes
include rejected RTMP connections, non-existing RTMP applications, rejected stream names,
authentication errors, etc. Check that the server is online, and that you have provided the
correct server URL and stream name.
error
— There is an error in the OpenTok platform.
The HTTP response will have one of the following status codes:
curl -i \
-X GET \
-H X-OPENTOK-AUTH:JWT_TOKEN \
https://api.opentok.com/v2/project/API_KEY/broadcast/BROADCAST_ID
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.
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.
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.
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:
"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.
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.
The HTTP response will have one of the following status codes:
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
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 broadcast stream. For more information, see Assigning live streaming layout classes to OpenTok streams.
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 the session ID.
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.
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:
You can update the layout class list for multiple streams by passing in multiple JSON objects
in the items
array.
The HTTP response will have one of the following status codes:
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
Use this method to create an OpenTok API key and secret for a project.
Note: You can also create a new project on your TokBox account page.
Submit an HTTP POST request to the following URL:
https://api.opentok.com/v2/project
If you are going to send request data to set a name (see the next section,
"POST data"), set the Content-Type
header to application/json
.
Otherwise, do not set the the Content-Type
header.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication). Note that you must use the account-level API key and account-level API secret when creating the token. The account-level API key and secret is only available to registered administrators of your OpenTok account.
Include a JSON object of the following form as the request body content:
{
"name": "Acme" // optional
}
If you do not wish to set a name for the project, do not include any body content.
The HTTP response will have one of the following status codes:
200 — Success. The response data is a project details object.
400 — Invalid request. This response may indicate that data in your request data is invalid JSON.
403 — Authentication error.
500 — OpenTok server error.
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
export data='{"name":"Acme"}'
curl -i\
-X POST \
-H $headerstr \
-H "Content-Type:application/json" \
-D $data \
$TB_url/v2/project
Account administrators can use this method to change a project's status. The status is either active or suspended. If a project's status is suspended, you will not be able to use the project API key (and any OpenTok sessions created with it).
You can change a project's status from active to suspended and back.
Submit an HTTP PUT request to the following URL:
https://api.opentok.com/v2/project/<api_key>
Where <api_key>
is the project API key.
Set the Content-Type
header to application/json
.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication). Note that you must use the account-level API key and account-level API secret when creating the token. The account-level API key and secret is only available to registered administrators of your OpenTok account.
Include a JSON object of the following form as the request body content:
{
"status": "ACTIVE" | "SUSPENDED"
}
The HTTP response will have one of the following status codes:
200 — Success. The response data is the project details object.
400 — Invalid request. This response may indicate that data in your request data is invalid JSON.
403 — Authentication error.
500 — OpenTok server error.
The following example sets the status for the "Acme" project to suspended:
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567 # Replace with the project API key.
export data='{"status":"SUSPENDED"}'
curl -i\
-X PUT \
-H $headerstr \
-H "Content-Type:application/json" \
-D $data \
$TB_url/v2/project/$apikey
Use this method to delete a project. This prevents the use of the project API key (an any OpenTok sessions created with it).
You can also temporarily suspend a project's API key.
Note: You can also delete a project on your TokBox account page.
Submit an HTTP DELETE request to the following URL:
https://api.opentok.com/v2/project/<api_key>
Where <api_key>
is the project API key.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication). Note that you must use the account-level API key and account-level API secret when creating the token. The account-level API key and secret is only available to registered administrators of your OpenTok account.
The HTTP response will have one of the following status codes:
The following example deletes a project:
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567 # Replace with the project API key.
curl -i\
-X DELETE \
-H $headerstr \
$TB_url/v2/project/$apikey
Use this method to get a project details record describing the project (or to get the records for all projects). See project details object.
To get information on a specific project, submit a GET request to the following URL:
https://api.opentok.com/v2/project/<api_key>
Where <api_key>
is the API key for the project.
To get information on all of your projects, submit a GET request to the following URL:
https://api.opentok.com/v2/project
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication). Note that you must use the account-level API key and account-level API secret when creating the token. The account-level API key and secret is only available to registered administrators of your OpenTok account.
The HTTP response will have one of the following status codes:
200 — Success. The response data is the project details object or an array of project details objects. See project details object.
403 — Authentication error.
404 — Not found. There is no project for the API key provided.
500 — OpenTok server error.
### Example
The following example gets details for a specific project:
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567 # Replace with the project API key.
curl -i\
-X GET \
-H $headerstr \
$TB_url/v2/project/$apikey
The response is a JSON project details object.
The following example gets details for all of your projects:
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
curl -i\
-X GET \
-H $headerstr \
$TB_url/v2/project
The response is an array of project details objects.
For security reasons, you may want to generate a new API secret for a project.
Note: Use the new API secret for all REST API calls and with the OpenTok server-side SDKs. When you generate a new API secret, all existing client tokens become invalid (and they cannot be used to connect to OpenTok sessions); use the new API secret with the OpenTok server SDK to generate client tokens.
Submit an HTTP POST request to the following URL:
https://api.opentok.com/v2/project/<api_key>/refreshSecret
Where <api_key>
is the project API key.
Authenticate this API call using a custom HTTP header — X-OPENTOK-AUTH
:
X-OPENTOK-AUTH:<token>
Set this header to a JWT token (see Authentication). Note that you must use the account-level API key and account-level API secret when creating the token. The account-level API key and secret is only available to registered administrators of your OpenTok account.
The HTTP response will have one of the following status codes:
200 — Success. The response data is the project details object, with the new API secret.
403 — Authentication error.
404 — Not found. There is no project for the API key provided.
500 — OpenTok server error.
The following example generates a new project API secret:
export token=YOUR_TOKEN_STRING # See "Authentication."
export TB_url=https://api.opentok.com
headerstr="X-OPENTOK-AUTH:$token"
apikey=1234567 # Replace with the project API key.
curl -i\
-X POST \
-H $headerstr \
$TB_url/v2/project/$apikey/refreshSecret