Vonage Video API 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 (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

Live captions

Experience Composer

Audio Connector

Account management

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. 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 Video API 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 Video API 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 Video API 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.)

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

POST Parameters

archiveName

The name to use for archives in auto-archived sessions. When setting this option, the archiveMode option must be set to always or an error will result. The length of the archive name can be up to 80 chars. Due to encoding limitations the following special characters are translated to a colon (:) character: ~, -, _. If you do not set a name and the archiveMode option is set to always, the archive name will be empty.

archiveResolution

The resolution of archives in an auto-archived session. Valid values are "480x640", "640x480" (the default), "720x1280", "1280x720", "1080x1920", and "1920x1080". When setting this option, the archiveMode option must be set to always or an error will result.

location

The IP address that the Vonage Video APi 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 "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

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.

type

String. The maximum length is 128 bytes, and it must contain only letters (A-Z and a-z), numbers (0-9), '-', '_', and '~'.

data

String. The maximum length is 8kb.

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

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}" \ https://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}" \ 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.

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:

Getting stream information

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.

HTTP GET to session/stream

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/

GET header properties

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

Response

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"]
}
  • The layoutClassList property is an array of the layout classes for the stream.
  • The id property is the stream ID.
  • The videoType property is set to "camera", "screen", or "custom". A "screen" video uses screen sharing on the publisher as the video source; a "custom" video is published by a web client using an HTML VideoTrack element as the video source.
  • The 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:

  • 200 — Success.
  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID.
  • 403 — You passed in an invalid OpenTok API key or JWT token.
  • 404 — The session exists but has not had any streams added to it yet.
  • 408 — You passed in an invalid stream ID.
  • 500 — OpenTok server error.

Example

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
  • 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.
  • Set the 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/
  • 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.

Forcing a single stream to mute published audio

You can use the OpenTok REST API to force a publisher of a specific stream to mute its audio.

POST to session/stream/mute

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/stream/<stream_id>/mute

Replace <api_key> with the OpenTok project API key (see the Project Page of your Video API account). Replace <session_id> with the session ID of the session containing the stream. Replace <stream_id> with the stream ID.

POST header properties

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).

HTTP Response

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

  • 200 — Success. The response data is a project details object.

  • 400 — Invalid request.

  • 403 — Authentication error.

  • 404 — Not found. The session or stream is not found.

  • 500 — OpenTok server error.

Example

SESSION_ID=2_MX40NzIwMzJ-fjE2MzM0NzE4NjY4OTfn4 STREAM_ID=eac2b8fb-b6da-40e7-9d31-d1b04edc2270 API_KEY=123456 API_SECRET=ABCDEF1234567890 JWT=jwt_token curl -v \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/stream/${STREAM_ID}/mute

Forcing streams in a session to mute published audio

You can use the OpenTok REST API to force all streams (except for an optional list of streams) in a session to mute published audio. You can also use this method to disable the force mute state of a session (see below).

POST to session/mute

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/mute

Replace <api_key> with the OpenTok project API key (see the Project Page of your Video API account). Replace <session_id> with the session ID.

POST header properties

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).

POST data

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

{
  "active": true,
  "excludedStreamIds": [
    "excludedStreamId1",
    "excludedStreamId2"
  ]
}

The JSON data includes the following properties:

  • active (Boolean, required) — Whether to mute streams in the session (true) and enable the mute state of the session, or to disable the mute state of the session (false). With the mute state enabled (true), all current and future streams published to the session (with the exception of streams in the excludedStreamIds array) are muted. When you call this method with the active property set to false, future streams published to the session are not muted (but any existing muted streams remain muted).

  • excludedStreamIds (Array of strings, optional) — The stream IDs for streams that should not be muted. This is an optional property. If you omit this property, all streams in the session will be muted. This property only applies when the active property is set to true. When the active property is set to false, it is ignored.

    The elements in the excludedStreamIds array are stream IDs (strings) for the streams you wish to exclude from being muted.

    If you do not wish to include an array of excluded streams, do not include any body content.

HTTP Response

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.

  • 404 — Not found. The session is not found.

  • 500 — OpenTok server error.

Example

The following forces all streams (except for an optional list of streams) in a session to mute published audio:

SESSION_ID=2_MX40NzIwMzJ-fjE2MzM0NzE4NjY4OTfn4 DATA='{"excludedStreamIds": ["eac2b8fb-b6da-40e7-9d31-d1b04edc2270", "9c18b42f-ee38-4b38-99bb-d37b2eca9741 "], "active": true}' API_KEY=123456 API_SECRET=ABCDEF1234567890 JWT=jwt_token curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ -d "${DATA}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/mute

To disable the mute state of the session (to disable future streams from being muted), call the method again with the active property set to false:

SESSION_ID=SOME_SESSION_ID DATA='{"active": false}' API_KEY=123456 API_SECRET=ABCDEF1234567890 curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:JSON_WEB_TOKEN" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/mute

Listing connections in a session

Use this method to list the connections from an OpenTok session associated with a project.

HTTP GET to session/connection

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/connection

Replace <api_key> with your OpenTok API key. See the Project Page in your Video API account.

Replace <sessionId> with the session ID of the session containing the connections.

You can add optional query parameters to filter the results:

  • offset (integer, optional): The zero-based index of the first connection to return. Default is 0 (the oldest connection).
  • count (integer, optional): The maximum number of connections to return. Default is 50; maximum is 1000.

For example, the following call retrieves 20 connections starting at position 400:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/connection?offset=400&count=20

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": 3,
  "projectId" : "<api_key>",
  "sessionId" : "<sessionId>",
  "items": [{
      "connectionId": "<connection_id_1>",
      "createdAt": 1747655658197,
      "connectionState": "Connected"
    },{
      "connectionId": "<connection_id_2>",
      "createdAt": 1747655658227,
      "connectionState": "Connected"
    },{
      "connectionId": "<connection_id_3>",
      "createdAt": 1747655658258,
      "connectionState": "Connecting"
    }
  ]
}

The JSON object includes the following properties:

  • count — The total number of connections in the session.
  • projectId — Your OpenTok API key.
  • sessionId — The session ID.
  • items — An array of objects defining each connection retrieved. Connections are listed from the oldest to the newest in the return set.

Each object in the items array represents a connection and has the following properties:

  • connectionId — The connection ID.
  • connectionState — The state of the connection:
    • "Connecting" — The connection is still in creation phase and not completely established.
    • "Connected" — The connection is fully established and connected to the session.
  • createdAt — The timestamp for when the connection was created, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

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

  • 200 — Success. The response data contains the connection list from an OpenTok session.
  • 400 — Invalid request. This response may indicate that some parameter of your query is invalid.
  • 403 — Authentication error.
  • 404 — The session is not found.
  • 500 — OpenTok server error.

Example

In the following examples:

  • Set the value for API_KEY to your OpenTok API key.
  • Set the value for JWT to a valid JSON web token (see Authentication).
  • Set the value for SESSION_ID to your OpenTok Session ID.

The following command line example retrieves the first 50 connections from the session:

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

The next command line example retrieves the first connection created in the session:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=0&count=1

The following command line example retrieves two connections, starting with the fifth connection created in the session:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=5&count=2

The next example retrieves no connections, since the offset is larger than the number of connections in the session:

API_KEY=123456 SESSION_ID=SOMESESSIONID JWT=jwt_token # replace with a JSON web token (see "Authentication") curl \ -i \ -X GET \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/connection?offset=500&count=100

Migrating a session

Use this method to migrate a session to a different server when required. Migration is only possible if there is no migration currently in progress for the session and if the session was not created or migrated recently. (See the Server Rotation and Session Migration developer guide.)

Note: When migration is triggered, all connections that have the "migrate" capability will be migrated to the new server. Any connections without the "migrate" capability will be closed as part of the migration process. (See Enabling session migration in clients.)

Resource URL:

https://api.opentok.com/v2/project/<api_key>/session/<sessionId>/migrate

Replace <api_key> with the OpenTok project API key (see the Project Page of your Video API account). Replace <session_id> with the session ID of the session to be migrated to a different server.

Resource verb:

POST

POST header properties

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).

HTTP Response

For some error responses, in addition to the HTTP response code, the response body includes a code field to indicate the specific reason for the error. The HTTP response will have one of the following status codes:

  • 202 — Accepted. The request is valid and the session will be migrated.

  • 400 — Invalid request. This response may indicate that the request is missing some information.

  • 403 — Authentication error. Due to unauthorized token or invalid token

  • 404 — Not found. The session is not found.

  • 409 — Conflict. The session can not be migrated at this time. This may be due to one of the following reasons:

    • code 15214: A migration is already in progress for the session.
    • code 15215: The session was created or migrated recently.

  • 500 — OpenTok internal server error.

Sample Request

SESSION_ID=SOMESESSIONID API_KEY=123456 JWT=json_web_token curl -v \ -H "Content-Type: application/json" \ -X POST \ -H "X-OPENTOK-AUTH:${JWT}" \ https://api.opentok.com/v2/project/${API_KEY}/session/${SESSION_ID}/migrate
  • Set the value for API_KEY to your OpenTok API key.
  • Set the value for JWT to a JSON web token (see Authentication).
  • Set the SESSION_ID value to the ID of the session to be migrated.

Sample Response

Authentication error response:

{
  "code":15215,
  "message":"Migration is not allowed shortly after session creation or a previous migration",
  "description":"Migration is not allowed shortly after session creation or a previous migration"
}

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 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 Video API 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,
    "layout" : {
      "type": "custom",
      "stylesheet": "the layout stylesheet (only used with type == custom)",
      "screenshareType": "the layout type to use when there is a screen-sharing stream (optional)"
    },
    "name" : "archive_name",
    "outputMode" : "composed",
    "resolution" : "640x480",
    "streamMode" : "auto"
}

The JSON object includes the following properties:

  • sessionId (String) — (Required) 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.
  • layout (Object) — Optional. Specify this to assign the initial layout type for the archive. This applies only to composed archives. This object has three properties: type, stylesheet, and screenshareType, which are each strings. 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.) Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset. 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.
  • maxBitrate (optional) — The maximum video bitrate for the archive, in bits per second. The minimum value is 100,000 and the maximum is 6,000,000. This option is only valid for composed archives. Set the maximum video bitrate to control the size of the composed archive. This maximum bitrate applies to the video bitrate only. If the output archive has audio, those bits will be excluded from the limit. When you set the maxBitrate property, the archive uses a constant bitrate. You cannot set both the maxBitrate property and the quantizationParameter properties — doing so results in an error.
  • multiArchiveTag (String) — (Optional) Set this to support recording multiple archives for the same session simultaneously. Set this to a unique string for each simultaneous archive of an ongoing session. You must also set this option when manually starting an archive in a session that is automatically archived. If you do not specify a unique multiArchiveTag, you can only record one archive at a time for a given session. See Simultaneous archives.
  • name (String) — (Optional) The name of the archive (for your own identification). The maximum length of the archive name is 255 characters.
  • 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.
  • quantizationParameter (Number) — (Optional) The quantization parameter (QP) for a composed archive, which adjusts the trade-off between video quality and file size. Setting the quantization parameter causes the archive to use a variable bitrate and a constant compression quantization, resulting in a consistent quality level across scene changes. Valid values are from 15 to 40, and 20 to 30 produce reasonable results without a large perceptual quality difference. Lower QP values produce finer video compression quantization, resulting in increased video quality (retaining more video detail) and a larger file size. Higher QP values produce coarser video compression quantization, decreasing video quality and resulting in a smaller file size. You can only set a quantization parameter for a composed archive — setting quantizationParameter for an individual stream archive results in an error. You cannot set both the quantizationParameter property and the maxBitrate property — doing so results in an error.
  • resolution (String) — (Optional) The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). 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.
  • streamMode (String) — (Optional) Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

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",
  "streamMode" : "auto",
  "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).
  • multiArchiveTag — The unique tag for simultaneous archives (if one was set).
  • 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.
  • resolution — The resolution of the archive (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920"). This property is only set for composed archives.
  • sessionId — The session ID of the OpenTok session being archived.
  • status — This is set to "started".
  • streamMode — Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual").
  • streams — An array of objects corresponding to streams currently being archived. This is only set for an archive with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:
    • streamId — The stream ID of the stream included in the archive.
    • hasAudio — Whether the stream's audio is included in the archive.
    • hasVideo — Whether the stream's video is included in the archive.

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.
  • You specify an invalid resolution value.
  • The outputMode property is set to "individual" and you set the resolution property and (which is not supported in individual stream archives).
  • You specify an invalid maxBitrate value or you specify a maxBitrate value for an individual stream archive. (maxBitrate is only supported for composed archives.)
  • You specify an invalid quantizationParameter value or you specify a quantizationParameter value for an individual stream archive. (quantizationParameter is only supported for composed archives.)
  • You specify both a maxBitrate and a quantizationParameter property.

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 you attempt to start an archive for a session that is already being recorded without setting the multiArchiveTag option. Or if you attempt to start a simultaneous archive for a session without setting a unique multiArchiveTag value.

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 stop recording after 4 hours (14,400 seconds), 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 4 hours in length each. For more information, see Archive duration

Calling this method for automatic archives has no effect. Automatic archives continue recording to multiple consecutive files of up to 4 hours (14,400 seconds) 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.

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 Video API 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",
  "multiArchiveTag": "archive-1234b"
  "name" : "The archive name you supplied",
  "outputMode": "composed"
  "projectId" : 234567,
  "reason" : "",
  "resolution" : "640x480",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "stopped",
  "streamMode" : "auto",
  "streams" : "[]",
  "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.
  • multiArchiveTag — The unique tag for simultaneous archives (if one was set).
  • outputMode — Either "composed" or "individual". See Individual stream and composed archives.
  • projectId — Your OpenTok API key.
  • resolution — The resolution of the archive (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920"). 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".
  • streamMode — Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual").
  • streams — An array of objects corresponding to streams currently being archived. This is only set for an archive with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:
    • streamId — The stream ID of the stream included in the archive.
    • hasAudio — Whether the stream's audio is included in the archive.
    • hasVideo — Whether the stream's video is included in the archive.

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.

Note: Archive records are available for up to 12 months.

HTTP GET to archive

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 Video API 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 Video API 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",
    "multiArchiveTag": "archive-1234a",
    "name" : "Foo",
    "outputMode" : "composed",
    "projectId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 247748791,
    "status" : "available",
    "streamMode" : "manual",
    "streams" : [],
    "url" : "https://example.com/archive.mp4"
  }, {
    "createdAt" : 1384221380000,
    "duration" : 328,
    "hasAudio" : true,
    "hasVideo" : true,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "multiArchiveTag": "archive-1234b",
    "name" : "Foo",
    "outputMode" : "composed",
    "projectId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "streamMode" : "auto",
    "streams" : [],
    "url" : "https://example.com/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.
  • multiArchiveTag — The unique tag for simultaneous archives (if one was set).
  • 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".
  • 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 following conditions occur:

      • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
      • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

      If a client resumes publishing while the archive is in the "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 Video API account.

  • streamMode — Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual").
  • resolution — The resolution of the archive (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920"). 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.
  • streamMode — Whether all streams are included in the archive ("auto") or you select streams to include in the archive ("manual"). See Selecting streams to be included in an archive.
  • streams — An array of objects corresponding to streams currently being archived. This is only set for an archive with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:
    • streamId — The stream ID of the stream included in the archive.
    • hasAudio — Whether the stream's audio is included in the archive.
    • hasVideo — Whether the stream's video is included in the archive.
  • 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.

Note: Archive records are available for up to 12 months.

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 Video API 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",
  "multiArchiveTag": "archive-1234b",
  "name" : "Foo",
  "outputMode" : "composed",
  "projectId" : 123456,
  "reason" : "",
  "resolution" : "640x480",
  "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
  "size" : 247748791,
  "status" : "available",
  "streamMode" : "auto",
  "streams" : []
  "url" : "https://example.com/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.
  • multiArchiveTag — The unique tag for simultaneous archives (if one was set).
  • 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", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920"). 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 following conditions occur:

      • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
      • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

      If a client resumes publishing while the archive is in the "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 Video API account.

  • size — The size of the archive file. For archives that have not been generated, this value is set to 0.
  • streamMode — Whether all streams are included in the archive ("auto") or you select streams to include in the archive ("manual"). See Selecting streams to be included in an archive.
  • streams — An array of objects corresponding to streams currently being archived. This is only set for an archive with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:
    • streamId — The stream ID of the stream included in the archive.
    • hasAudio — Whether the stream's audio is included in the archive.
    • hasVideo — Whether the stream's video is included in the archive.
  • 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 Video API 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.

Setting an S3 or Azure archiving upload target

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 Vonage Video API account page.

For Amazon S3, you will need to provide Vonage 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.

HTTP PUT to archive

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.

PUT header properties

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

PUT data

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" or "https://storage.googleapis.com". We support Cloudian and Google Cloud Storage (accessed using the AWS S3 API) as S3-compatible storage solutions. 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.

HTTP Response

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.

  • The config value exceeds the size limit. We encrypt the config setting when storing it, and the encrypted size must be 2,048 characters or less.

  • Your request data includes invalid JSON.

    • 403 — Authentication error. You passed in an invalid token in the X-OPENTOK-AUTH header.

Example

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.

Deleting an archiving upload target

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 Vonage Video API account page.

HTTP DELETE to archive

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.

DELETE header properties

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).

Response

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

  • 204 — Success (no content).

  • 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.

Dynamically changing the layout type of a composed archive

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.

HTTP PUT to archive

Submit an HTTP PUT request to the following URL:

Replace <apiKey> with your OpenTok API key.

Replace <archiveId> with the archive 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",
  "screenshareType": "optional layout type to use when there is a screen-sharing stream",
  "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.

    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).

  • stylesheet (String) — 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.

  • screenshareType (String) — Optional. The layout type to use when there is a screen-sharing stream in the session. Note that to use this property, you must set the type property to "bestFit" and leave the stylesheet property unset. For more information, see Layout types for screen sharing.

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/archive/$archiveId/layout

Changing the composed archive 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 a composed OpenTok archive. For more information, see Assigning live streaming layout classes to OpenTok streams.

HTTP PUT to stream

Submit an HTTP PUT request to the following URL:

Replace <apiKey> with your OpenTok API key. Replace <sessionId> with 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

Selecting streams to be included in an archive

Use this method to change the streams included in a composed archive that was started with the streamMode set to "manual" (see Starting an archive recording).

The archive composer includes added streams based on stream prioritization rules.

HTTP PATCH to archive/streams

Submit an HTTP PATCH request to the following URL:

Replace <apiKey> with your OpenTok API key. Replace <archiveId> with the archive ID.

PATCH 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.

PATCH data

To add a stream to the archive, include a JSON object of the following form as the request body content:

{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f",
  "hasAudio": true,
  "hasVideo": false
}

The JSON object contains the following properties:

  • addStream (String) — The stream ID.
  • hasAudio (Boolean, optional) — Whether the composed archive should include the stream's audio (true, the default) or not (false).
  • hasVideo (Boolean, optional) — Whether the composed archive should include the stream's video (true, the default) or not (false).

You can call the method repeatedly with addStream set to the same stream ID, to toggle the stream's audio or video in the archive.

If you set both hasAudio and hasVideo to false, you will get error response.

To stop a stream from being included in the archive, include a JSON object of the following form as the request body content:

{
  "removeStream": "12312312-3811-4726-b508-e41a0f96c68f"
}

Set the removeStream property to the stream ID.

Response

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

  • 204 — Success (no content).
  • 400 — Invalid request. This response may indicate that data provided in your request is an invalid JSON, or the request couldn't be fulfilled because the archive was started with streamMode set to "auto", which does not support stream manipulation.
  • 403 — Authentication error.
  • 404 — Archive or stream not found.
  • 500 — OpenTok server error.

Examples

Adding a stream to an archive:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":$STREAM_ID} \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

Removing a stream's video in an archive (but leaving the audio in):

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":\"$STREAM_ID\", \"hasAudio\":true, \"hasVideo\":false } \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

Removing a stream from an archive:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"removeStream\":\"$STREAM_ID\"} \
   https://api.opentok.com/v2/project/$apiKey/archive/$ARCHIVE_ID/streams

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 Video API 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": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "headers": {
      "headerKey": "headerValue"
    },
    "auth": {
      "username": "username",
      "password": "password"
    },
    "secure": true|false,
    "video": true|false,
    "observeForceMute": true|false,
    "streams": ["stream-id-1", "stream-id-2"]
  }
}

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 Vonage 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 comprised of word characters (a-z, A-Z, 0-9) or the characters _, +, !, %, `, ', ~, or -.

    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.

    If from is undefined, or set to a string (for example, "<joe@example.com>"), that is unrecognized or a non-authorised number, in most cases it will be converted to "Unknown" before the request is forwarded to a Carrier for PSTN termination by SIP providers. Depending on the provider, "Unknown" will show up as the incoming number on PSTN phones. In some cases, providers may have those calls rejected for security reasons, to avoid issues like number spoofing. In the event the call is not rejected by providers, +00000000 will show up as the incoming number on PSTN phones.

    A number is considered unrecognized when it is not E.164 or not a Vonage virtual number if connecting to the Vonage Voice API, for instance.

  • SIP headers​​ (optional) — This object defines custom headers to be added to the SIP ​INVITE​ request initiated from OpenTok to your SIP platform.

  • SIP auth​ (optional) — This object contains the username and password to be used in 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).

  • video (optional) — A Boolean flag that indicates whether the SIP call will include video (​true​) or not (​false​, the default). With video included, the SIP client's video is included in the OpenTok stream that is sent to the OpenTok session. SIP video is limited to 480p at 800 kbps. The SIP client will receive a single composed video of the published streams in the OpenTok session.

  • observeForceMute (optional) A boolean flag that indicates whether the SIP end point observes force mute moderation (true) or not (false, the default). Also, with observeForceMute set to true, the caller can press "*6" to unmute and mute the published audio. For the "*6" mute toggle to work, the SIP caller must negotiate RFC2833 DTMFs (RFC2833/RFC4733 digits). The mute toggle is not supported with SIP INFO or in-band DTMFs. A message (in English) is played to the caller when the caller mutes and unmutes, or when the SIP client is muted through a force mute action.

  • streams (optional) — An array of stream IDs for streams to include in the SIP call. If you do not set this property, all streams in the session are included in the call.

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.
  • 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:

  • 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 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='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
  • 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 property of the data JSON to a valid OpenTok connection token for the participant being called (see the Token Creation developer guide).
  • Set the username and password properties of the data JSON to the username and password for your SIP endpoint. (This is optional.)

Sending DTMF digits to SIP clients

Use the play-dtmf REST API to send DTMF digits to all participants in an active OpenTok session or to a specific client connected to that session.

Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.

Send DTMF digits to all clients connected to the session

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/play-dtmf

Replace <api_key> with your OpenTok API key. See the Project page of your Video API account. Replace <session_id> with the session ID of the session you are sending the DTMF signal to.

The DTMF message is ignored by clients that do not support DTMF (such as non-SIP clients).

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:

{ "digits": "1713" }

The JSON object includes a digits property. This is the string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).

Response

In a successful call, the response includes an HTTP status code 200.

Upon errors, the response includes one of the following HTTP status codes:

  • 400 — One of the properties — digits or sessionId — is invalid.

  • 403 — Authentication error. This can occur if you use an invalid OpenTok API key or an invalid JSON web token

  • 404 — The specified session does not exist.

In an error case, the response body will be JSON with a code and message property:

{ "code" : 400, "message" : "One of the properties digits or sessionId is invalid." }

Example

The following sends an HTTP POST request to the play-dtmf resource of the session:

SESSION_ID=2_MX40NTMyODc3Mn5-fg API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"digits":"1713"}' 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}/play-dtmf

Signal DTMF tones to a specific client connected to the session

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project/<api_key>/session/<session_id>/connection/<connection_id>/play-dtmf

Replace <api_key> with your OpenTok API key. See the Project Page of your Video API account. Replace <session_id> with the session ID of the session you are sending the DTMF signal to. Replace <connection_id> with the connection ID of the client you are sending the DTMF signal to.

You can obtain the connection ID of a SIP client from the response in the REST API call to initiate the SIP call.

If you send DTMF digits to a client that does not support DTMF (such as a non-SIP client), the client ignores the request.

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:

{ "digits": "1713" }

The JSON object includes a digits property. This is the string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).

Response

In a successful call, the response includes an HTTP status code 200.

Upon errors, the response includes one of the following HTTP status codes:

  • 400 — One of the properties — digits or sessionId — is invalid.

  • 403 — Authentication error. This can occur if you use an invalid OpenTok API key or an invalid JSON web token

  • 404 — The specified session does not exist or the client specified by the connectionId property is not connected to the session.

In an error case, the response body will be JSON with a code and message property:

{ "code" : 400, "message" : "One of the properties digits, sessionId or connectionId is invalid." }

Example

Send an HTTP POST to the play-dtmf resource of a specific connection ID belonging to the session:

SESSION_ID=2_MX40NTMyODc3Mn5-fg CONNECTION_ID=396edda0-fc30-41fd-8e63 API_KEY=123456 JWT=jwt_token # replace with a JSON web token (see "Authentication") DATA='{"digits":"1713"}' 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}/play-dtmf

Starting a live streaming broadcast

Use this method to start a live streaming broadcast 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.

The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simultaneously 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.

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)",
    "screenshareType": "optional layout type to use when there is a screen-sharing stream"
  },
  "maxBitrate": 1000000,
  "maxDuration": 5400,
  "outputs": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    },
    "rtmp": [{
      "id": "foo",
      "serverUrl": "rtmps://myfooserver:443/myfooapp",
      "streamName": "myfoostream"
    },
    {
      "id": "bar",
      "serverUrl": "rtmp://mybarserver:443/mybarapp",
      "streamName": "mybarstream"
    }]
  },
  "hasAudio": true,
  "hasVideo": true,
  "resolution": "640x480",
  "streamMode" : "auto"
}

The JSON object includes the following properties:

  • sessionId (String) — Set this to the session ID of the OpenTok session you want to broadcast.

  • hasAudio (Boolean) — (Optional) Whether the broadcast will include 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 broadcast will include 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.

    Note: when setting hasVideo to false, the broadcast will include video with black 160x120 frames in RTMP streams. Some endpoints, like YoutTube and Facebook, reject audio-only RTMP streams.

  • layout (Object) — Optional. Specify this to assign the initial layout type for the broadcast. This object has three properties: type, stylesheet, and screenshareType, which are each strings. 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.) Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset. 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.

  • multiBroadcastTag (String) — (Optional) Set this to support multiple broadcasts for the same session simultaneously. Set this to a unique string for each simultaneous broadcast of an ongoing session. See Simultaneous broadcasts.

  • maxBitrate (optional) — The maximum bitrate for the broadcast stream(s), in bits per second. The minimum value is 100,000 and the maximum is 6,000,000.

  • 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 4 hours (14,400 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).

    For each RTMP stream, specify 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). Be sure to include the port for the serverUrl, as in "rtmps://myfooserver:443/myfooapp" (instead of "rtmps://myfooserver/myfooapp"). 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. Vonage 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. This object includes the following optional properties:

    • dvr (Boolean) — Whether to enable DVR functionality — rewinding, pausing, and resuming — in players that support it (true), or not (false, the default). With DVR enabled, the HLS URL will include a ?DVR query string appended to the end.
    • lowLatency (Boolean) — Whether to enable low-latency mode for the HLSstream. Some HLS players do not support low-latency mode. This feature is incompatible with DVR mode HLS broadcasts.

    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 landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for broadcasts that include video streams from mobile devices (which often use the portrait aspect ratio). This property is optional.

  • streamMode (String) — (Optional) Whether streams included in the broadcast are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the broadcast. When streams are selected manually ("manual"), you specify which streams to include based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the broadcast. For both automatic and manual modes, the broadcast composer includes streams based on stream prioritization rules.

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": "",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  },
  "outputs": {
    "rtmp": {
      "id": "my-id",
      "serverUrl": "rtmp://myserver:443/myapp",
      "streamName": "my-stream-name"
    }
  }
}

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,
  "resolution": "640x480",
  "status": "started",
  "streamMode": "auto",
  "streams": [],
  "multiBroadcastTag": "broadcast-1234b",
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "connecting",
    "rtmp": [{
      "id": "foo",
      "status": "connecting",
      "serverUrl": "rtmps://myfooserver:443/myfooapp",
      "streamName": "myfoostream",
    }, {
      "id": "bar",
      "status": "connecting",
      "serverUrl": "rtmp://mybarserver:443/mybarapp",
      "streamName": "mybarstream",
    }]
  }
}

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.
  • resolution — The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1920x1080").
  • status — This is set to "started".
  • streamMode — Whether all streams are included in the broadcast ("auto") or you select streams to include in the broadcast ("manual").
  • streams — An array of objects corresponding to streams currently being broadcast. This is only set for a broadcast with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:
    • streamId — The stream ID of the stream included in the broadcast.
    • hasAudio — Whether the stream's audio is included in the broadcast.
    • hasVideo — Whether the stream's video is included in the broadcast.
  • maxDuration — The maximum duration for the broadcast (if one was set), in seconds.
  • multiBroadcastTag — The unique tag for simultaneous broadcasts (if one was set).
  • broadcastUrls — An object containing details about the HLS and RTMP broadcasts.

If you specified an HLS endpoint, the object includes an hls property and an hlsStatus property. The hls property 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. The hlsStatus property is set to one of the following:

  • "connecting" — The OpenTok server is in the process of starting transcoders. This is the initial state.
  • "ready" — The OpenTok server has succesfully initialized but the CDN is not consuming media.
  • "live" — The OpenTok server has successfully initialized and the CDN is consuming media.
  • "ended" — The source stream has ended. If DVR is enabled and pre-recorded media is requested, then the status will transition to "live".
  • "error" — There is an error in the OpenTok platform.

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:

  • 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. Or you have exceeded the limit of five simultaneous RTMP streams for an OpenTok session. Or you specified and invalid resolution.
  • 403 — Authentication error.
  • 409 — The broadcast has already started for the session. Or if you attempt to start a simultaneous broadcast for a session without setting a unique multiBroadcastTag value.
  • 500 — OpenTok server error.

Example

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:443/myfooapp\", \
      \"streamName\": \"myfoostream\" \
    }, \
    { \
      \"id\": \"bar\", \
      \"serverUrl\": \"rtmp://mybarserver:443/mybarapp\", \
      \"streamName\": \"mybarstream\" \
    }] \
  } \
}" \
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 a broadcast stops automatically 60 seconds after the last client disconnects from the session. Also there is a default maximum duration of 4 hours (14,400 seconds) for each HLS and RTMP stream (the live stream broadcast automatically stops when this duration is reached). You can change the maximum duration for the broadcast by setting the maxDuration property when you start the broadcast REST method.

HTTP POST to broadcast//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,
  "resolution": "640x480",
  "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)
  • resolution — The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920").
  • status — This is set to "stopped".
  • streamMode — Whether all streams are included in the broadcast ("auto") or you select streams to include in the broadcast ("manual").
  • streams — An array of objects corresponding to streams currently being broadcast. This is an empty array for the stop method.
  • maxDuration — The maximum duration for the broadcast (if one was set), in seconds.
  • multiBroadcastTag — The unique tag for simultaneous broadcasts (if one was set).
  • 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

Listing live streaming broadcasts

Use this method to get details on broadcasts that are in progress and started. Completed broadcasts are not included in the listing.

HTTP GET to broadcast

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 broadcasts
  • count (optional, default: 50, maximum: 1000) — The number of broadcasts to retrieve starting at offset
  • sessionId (optional): Retrieve only broadcasts for a given session ID

GET header properties

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:

{
  "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",
        "hlsStatus": "live",
        "rtmp": {
          "foo": {
            "serverUrl": "rtmps://myfooserver:443/myfooapp",
            "streamName": "myfoostream",
            "status": "started"
          },
          "bar": {
            "serverUrl": "rtmp://mybarserver:443/mybarapp",
            "streamName": "mybarstream",
            "status": "live"
          }
        }
      }
      "status": "started",
      "streamMode" : "manual",
      "streams" : []
    }, {
      "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",
        "hlsStatus": "live",
        "rtmp": {
          "foo": {
            "serverUrl": "rtmp://myfooserver:443/myfooapps",
            "streamName": "myfoostreams",
            "status": "live"
          }
        }
      },
      "settings": {
        "hls": {
          "dvr": false,
          "lowLatency": false
        }
      },
      "status": "started",
      "streamMode" : "auto"
    }
  ]
}

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

  • resolution — The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920").

  • status — The status of the broadcast. This method only returns broadcasts with the status set to "started".

  • maxDuration — The maximum duration for the broadcast (if one was set), in seconds.

  • multiBroadcastTag — The unique tag for simultaneous broadcasts (if one was set).

  • broadcastUrls — Details on the HLS and RTMP broadcast streams.

    For an HLS stream, the URL is provided as the hls property. See the OpenTok live streaming developer guide for more information on how to use this URL. The hlsStatus property is set to one of the following:

    • "connecting" — The OpenTok server is in the process of starting transcoders. This is the initial state.
    • "ready" — The OpenTok server has succesfully initialized but the CDN is not consuming media.
    • "live" — The OpenTok server has succesfully initialized and the CDN is consuming media.
    • "ended" — The source stream has ended. If DVR is enabled and pre-recorded media is requested, then the status will transition to live".
    • "error" — There is an error in the OpenTok platform.

    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.

  • settings — Further details on the HLS broadcast stream. This settings object includes an hls property with the following properties:

  • streamMode — Whether all streams are included in the broadcast ("auto") or you select streams to include in the broadcast ("manual"). See Selecting streams to be included in a live streaming broadcast.

  • streams — For a broadcast with "manual" streamMode and a status set to "started", this is an array of objects corresponding to streams currently being broadcast. Each object in the array includes the following properties:

    • streamId — The stream ID of the stream included in the broadcast.
    • hasAudio — Whether the stream's audio is included in the broadcast.
    • hasVideo — Whether the stream's video is included in the broadcast.

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

  • 200 — Success
  • 403 — Authentication error
  • 500 — OpenTok server error

Examples

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

Getting information about a live streaming broadcast

Use this method to get details on 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.

GET header properties

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,
  "resolution": "640x480",
  "streamMode" : "auto",
  "streams" : [],
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "live",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "live"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "live"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "live"
}

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.

  • resolution — The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1080x1920").

  • 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 as the hls property. See the OpenTok live streaming developer guide for more information on how to use this URL. The hlsStatus property is set to one of the following:

  • "connecting" — The OpenTok server is in the process of starting transcoders. This is the initial state.
  • "ready" — The OpenTok server has successfully initialized but the CDN is not consuming media.
  • "live" — The OpenTok server has successfully initialized and the CDN is consuming media.
  • "ended" — The source stream has ended. If DVR is enabled and pre-recorded media is requested, then the status will transition to "live".
  • "error" — There is an error in the OpenTok platform.

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.

  • settings — Further details on the HLS broadcast stream. This properties object includes an hls property with the following properties:

  • multiBroadcastTag — The unique tag for simultaneous broadcasts (if one was set).

  • streamMode — Whether all streams are included in the broadcast ("auto") or you select streams to include in the broadcast ("manual"). See Selecting streams to be included in a live streaming broadcast.

  • streams — An array of objects corresponding to streams currently being broadcast. This is only set for a broadcast with the status set to "started" and the streamMode set to "manual". Each object in the array includes the following properties:

    • streamId — The stream ID of the stream included in the broadcast.
    • hasAudio — Whether the stream's audio is included in the broadcast.
    • hasVideo — Whether the stream's video is included in the broadcast.

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 \
  -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)",
  "screenshareType": "the layout type to use when there is a screen-sharing stream (optional)"
}

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 (String) — 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.
  • screenshareType (String) — Optional. The layout type to use when there is a screen-sharing stream in the session. Note that to use this property, you must set the type property to "bestFit" and leave the stylesheet property unset. For more information, see Layout types for screen sharing.

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 broadcast stream. For more information, see Assigning live streaming layout classes to OpenTok streams.

HTTP PUT to stream

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.

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

Selecting streams to be included in a live streaming broadcast

Use this method to change the streams included in a live streaming broadcast that was started with the streamMode set to "manual" (see Starting a live streaming broadcast).

The broadcast composer includes added streams based on stream prioritization rules.

HTTP PATCH to broadcast/streams

Submit an HTTP PATCH request to the following URL:

Replace <apiKey> with your OpenTok API key. Replace <broadcastId> with the broadcast ID.

PATCH 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.

PATCH data

To add a stream to the broadcast, include a JSON object of the following form as the request body content:

{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f",
  "hasAudio": true,
  "hasVideo": false
}

The JSON object contains the following properties:

  • addStream (String) — The stream ID.
  • hasAudio (Boolean, optional) — Whether the broadcast should include the stream's audio (true, the default) or not (false).
  • hasVideo (Boolean, optional) — Whether the broadcast should include the stream's video (true, the default) or not (false).

You can call the method repeatedly with addStream set to the same stream ID, to toggle the stream's audio or video in the broadcast.

If you set both hasAudio and hasVideo to false, you will get error response.

To stop a stream from being included in the broadcast, include a JSON object of the following form as the request body content:

{
  "removeStream": "12312312-3811-4726-b508-e41a0f96c68f"
}

Set the removeStream property to the stream ID.

Response

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

  • 204 — Success (no content).
  • 400 — Invalid request. This response may indicate that data provided in your request is an invalid JSON, or the request couldn't be fulfilled because the broadcast was started with streamMode set to "auto", which does not support stream manipulation.
  • 403 — Authentication error.
  • 404 — Broadcast or stream not found.
  • 500 — OpenTok server error.

Examples

Adding a stream to a broadcast:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":$STREAM_ID} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Removing a stream's video in a broadcast (but leaving the audio in):

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"addStream\":\"$STREAM_ID\", \"hasAudio\":true, \"hasVideo\":false } \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Removing a stream from a broadcast:

curl -i \
   -X PATCH \
   -H X-OPENTOK-AUTH:$JWT_TOKEN \
   -H "Content-Type:application/json" \
   -D {\"removeStream\":\"$STREAM_ID\"} \
   https://api.opentok.com/v2/project/$apiKey/broadcast/$BROADCAST_ID/streams

Starting Live Captions

Use this method to start real-time Live Captions for an OpenTok Session.

The maximum allowed duration is 4 hours, after which the audio captioning will stop without any effect on the ongoing OpenTok Session. Captions sessions will also be terminated 60 seconds after the last client disconnects. An event will be posted to your callback URL if provided when starting the captions.

Each OpenTok Session supports only one audio captioning session.

For more information about the Live Captions feature, see the Live Captions developer guide.

HTTP POST to start Live Captions

Submit an HTTP POST request to the following URL:

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

Replace <apiKey> with your OpenTok API key.

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>",
  "token": "A valid OpenTok token with the role set to moderator",
  "languageCode": "en-US",
  "maxDuration": 1800,
  "partialCaptions": true,
}

The JSON object includes the following properties:

  • sessionId (String) — The session ID of the OpenTok session. The audio from Publishers publishing into this session will be used to generate the captions.
  • token(String)— A valid OpenTok token with role set to Moderator.
  • languageCode (String) — (Optional) The BCP-47 code for the language used by Live Captions (see this list of supported languages). The default value is "en-US".
  • maxDuration (Integer) — (Optional) The maximum duration for the audio captioning, in seconds. The default value is 14,400 seconds (4 hours), the maximum duration allowed. The minimum value for maxDuration is 300 (300 seconds, or 5 minutes).
  • partialCaptions (Boolean) — (Optional) Whether to enable this to faster captioning at the cost of some degree of inaccuracies. The default value is true.

Response

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

{
  "captionsId": "7c0680fc-6274-4de5-a66f-d0648e8d3ac2"
}

The JSON object includes the following property:

  • captionsId — The unique ID for the audio captioning session.

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

  • 202 — Accepted.
  • 400 — Bad Request; The response may indicate error regarding the data in the request that is not acceptable.
  • 403 — Authentication error. The supplied X-OPENTOK-AUTH may be invalid.
  • 409 — Live captions have already started for this OpenTok Session.
  • 500 — Vonage Video API platform error.

Example


curl -X POST  \
-H 'X-OPENTOK-AUTH: ' \
-H 'Content-Type: application/json' \
-d '{
  "sessionId": "<valid-session-id>",
  "token": "<valid-token>",
}'
 https://api.opentok.com/v2/project/<apiKey>/captions

Stopping Live Captions

Use this method to stop live captions for a session.

HTTP POST to stop Live Captions

Submit an HTTP POST request to the following URL:

POST https://api.opentok.com/v2/project/<apiKey>/captions/<captionsId>/stop

Replace <apiKey> with your OpenTok API key. Replace <captionsId> with the ID returned in the start captions API response.

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

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

  • 202 — Accepted
  • 403 — Authentication error
  • 404 — No matching captionsId was found
  • 500 — Vonage Video API platform error

Example

curl
  -X POST
  -H "Content-Type: application/json"
  -H "X-OPENTOK-AUTH:<valid-jwt-token>"
  https://api.opentok.com/v2/project/<apiKey>/captions/<captionsId>/stop;

Starting an Experience Composer

Use this method to create an Experience Composer for an OpenTok session. For more information, see the Experience Composer developer guide.

HTTP POST to render

Submit an HTTP POST request to the following URL:

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

Replace <apiKey> with your OpenTok API key.

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": "&lt;session-id&gt;",
  "token": "A valid OpenTok token",
  "url": "https://webapp.customer.com",
  "maxDuration": 1800,
  "resolution": "1280x720",
  "properties": {
    "name": "Composed stream for Live event #1"
  }
}

The JSON object includes the following properties:

  • sessionId (String) — The session ID of the OpenTok session that will include the Experience Composer stream.
  • token (String) — A valid OpenTok token with a Publisher role and (optionally) connection data to be associated with the output stream.
  • url (String) — A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention. The minimum length of the URL is 15 characters and the maximum length is 2048 characters.
  • maxDuration (Integer) — (Optional)The maximum time allowed for the Experience Composer, in seconds. After this time, it is stopped automatically, if it is still running. The maximum value is 36000 (10 hours), the minimum value is 60 (1 minute), and the default value is 7200 (2 hours). When the Experience Composer ends, its stream is unpublished and an event is posted to the callback URL, if configured in the Account Portal.
  • resolution (String) — (Optional) The resolution of the Experience Composer, either "640x480" (SD landscape), "480x640" (SD portrait), "1280x720" (HD landscape), "720x1280" (HD portrait), "1920x1080" (FHD landscape), or "1080x1920" (FHD portrait). By default, this resolution is "1280x720" (HD landscape, the default).
  • properties (Object) — (Optional) The initial configuration of Publisher properties for the composed output stream. The properties object contains the key name (String) which serves as the name of the composed output stream which is published to the session. The name must have a minimum length of 1 and a maximum length of 200.

Response

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

{
  "id": "1248e7070b81464c9789f46ad10e7764",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": "e2343f23456g34709d2443a234",
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "callbackUrl": "https://callback.customer.com/",
  "name": "Composed-HD-Customer-1",
  "url": "https://webapp.customer.com",
  "resolution": "1280x720",
  "status": "starting",
  "streamId": "e32445b743678c98230f238" 
}

The JSON object includes the following properties:

  • id — The unique ID for the Experience Composer.
  • sessionId — The OpenTok session ID.
  • projectId — Your OpenTok API key.
  • createdAt — The time the Experience Composer started, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • updatedAt — This is the UNIX timestamp when the Experience Composer status was last updated. For this start method, this timestamp matches the createdAt timestamp.
  • callbackUrl — The callback URL for Experience Composer events (if one was set). See Configuring callbacks.
  • name — The name of the Experience Composer (if one was specified).
  • url — A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention.
  • resolution — The resolution of the Experience Composer (either "640x480", "480x640", "1280x720", "720x1280", "1920x1080", or "1080x1920").
  • status — For this start method, this is set to "starting".
  • streamId — The ID of the composed stream being published.

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

  • 202 — Success.

  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON. It may include an error code, some of which are listed below:

    • 50001 — Invalid application URL structure.
    • 50002 — Application URL is unreachable.
    • 50005 — Invalid maxDuration provided.
    • 50006 — Invalid resolution provided.
    • 50007 — Invalid stream name provided.
    • 50008 — Invalid sessionId provided.

  • 403 — Authentication error. It may include an error code, some of which are listed below:

    • 10001 - Invalid token format or signature.
    • 10002 - Unauthorized token.
    • 10003 - Invalid partner auth format.
    • 10004 - Unauthorized partner auth.
    • 10007 - The token does not match the session ID.
    • 10012 - Expired token.

  • 429 — Too many requests. You have exceeded the Experienced Composer usage limit. The response will include an error code set to 50004.

  • 500 — Vonage Video API platform error.

Example

  curl 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-OPENTOK-AUTH:<valid-jwt-token>"  
  -d '{"url": "&lt;valid-url-to-be-rendered&gt;", "sessionId": "&lt;valid-session-id&gt;", "token": "&lt;valid-token&gt;", "projectId": "&lt;valid-project-id&gt;"}'
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render

Getting info about an Experience Composer

Use this method to get details on an Experience Composer.

HTTP GET to render

Submit an HTTP GET request to the following URL:

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

Replace <apiKey> with your OpenTok API key. Replace <experienceComposerId> with the ID of the Experience Composer. You get the Experience Composer ID when you start an Experience Composer.

GET header properties

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":"80abaf0d-25a3-4efc-968f-6268d620668d",
  "sessionId":"1_MX4yNzA4NjYxMn5-MTU0NzA4MDUyMTEzNn5sOXU5ZnlWYXplRnZGblV4RUo3dXJpZk1-fg",
  "projectId":"27086612",
  "createdAt":1547080532099,
  "updatedAt":1547080532199,
  "callbackUrl": "https://callback.customer.com/",
  "name": "Composed-HD-Customer-1",
  "url": "https://webapp.customer.com",
  "resolution": "480x640",
  "status":"failed",
  "reason":"Could not load URL"
}

The JSON object includes the following properties:

  • id — The unique ID for the Experience Composer.
  • sessionId — The OpenTok session ID.
  • projectId — Your OpenTok API key.
  • createdAt — The time the Experience Composer 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.
  • callbackUrl — The callback for URL Experience Composer events (if one was set). See Configuring callbacks.
  • name — The name of the Experience Composer (if one was specified).
  • url — A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention.
  • resolution — The resolution of the Experience Composer (either "640x480", "1280x720", "480x640", or "720x1280").
  • status — The status of the Experience Composer. Poll frequently to check status updates. This property set to one of the following:
    • "starting" — The Vonage Video API platform is in the process of connecting to the remote application at the URL provided. This is the initial state.
    • "started" — The Vonage Video API platform has successfully connected to the remote application server, and is publishing the web view to an OpenTok stream.
    • "stopped" — The Experience Composer has stopped.
    • "failed" — An error occurred and the Experience Composer could not proceed. It may occur at startup if the OpenTok server cannot connect to the remote application server or republish the stream. It may also occur at any point during the process due to an error in the Vonage Video API platform.
  • reason — The reason field is only available when the status is either &quot;stopped&quot; or "failed". If the status is stopped, the reason field will contain either "Max Duration Exceeded" or "Stop Requested." If the status is failed, the reason will contain a more specific error message.
  • streamId — The ID of the composed stream being published. The streamId is not available when the status is "starting" and may not be available when the status is "failed".

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

  • 200 — Success
  • 400 — Invalid request
  • 403 — Authentication error
  • 404 — No Experience Composer matching the specified ID was found.
  • 500 — Vonage Video API platform error.

Example

curl 
  -X GET 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;"
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render/&lt;experienceComposerId&gt;

Getting a list of Experience Composers

Use this method to get a list of Experience Composers associated with a project.

HTTP GET to render

Submit an HTTP GET request to the following URL:

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

Replace <apiKey> with your OpenTok API key. The following optional query parameters can be added:

  • offset — The start offset for the list of Experience Composers. The default is 0.
  • count — The number of Experience Composers to retrieve starting at the offset. The default value is 50 and the maximum is 1000.

GET header properties

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:

{
  "count":2,
  "items":[
    {
      "id":"80abaf0d-25a3-4efc-968f-6268d620668d",
      "sessionId":"1_MX4yNzA4NjYxMn5-MTU0NzA4MDUyMTEzNn5sOXU5ZnlWYXplRnZGblV4RUo3dXJpZk1-fg",
      "projectId":"27086612",
      "createdAt":1547080532099,
      "updatedAt":1547080532099,
      "callbackUrl": "callback.customer.com/",
      "name": "Composed-HD-Customer-1",
      "url": "https://webapp.customer.com",
      "resolution": "1280x720",
      "status": "started",
      "streamId": "d2334b35690a92f78945"
    },
    {
      "id":"d95f6496-df6e-4f49-86d6-832e00303602",
      "sessionId":"2_MX4yNzA4NjYxMn5-MTU0NzA4MDUwMDc2MH5STWRiSE1jZjVoV3lBQU9nN2JuNElUV3V-fg",
      "projectId":"27086612",
      "createdAt":1547080511760,
      "updatedAt":1547080518965,
      "callbackUrl": "https://callback.customer.com/",
      "name": "Composed-HD-Customer-2",
      "url": "https://webapp2.customer.com",
      "resolution": "1280x720",
      "status":"stopped",
      "streamId": "d2334b35690a92f78945",
      "reason":"Max duration exceeded"
    }
  ]
}

The JSON object includes the following properties:

  • count — The total number of Experience Composers.
  • items — The array containing the retrieved Experience Composers. Each Experience Composer item includes the following properties:
    • id — The unique ID for the Experience Composer.
    • sessionId — The OpenTok session ID.
    • projectId — Your OpenTok API key.
    • createdAt — The time the Experience Composer 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.
    • callbackUrl — The callback URL for Experience Composer events (if one was set). See Configuring callbacks.
    • name — The name of the Experience Composer (if one was specified).
    • url — A publicly reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention.
    • resolution — The resolution of the Experience Composer (either "640x480", "1280x720", "480x640", or "720x1280").
    • status — The status of the Experience Composer. Poll frequently to check status updates. This property set to one of the following:
      • "starting" — The Vonage Video API platform is in the process of connecting to the remote application at the URL provided. This is the initial state.
      • "started" — The Vonage Video API platform has successfully connected to the remote application server and is publishing the web view to an OpenTok stream.
      • "stopped" — The Experience Composer has stopped.
      • "failed" — An error occurred and the Experience Composer could not proceed. This may occur at startup if the OpenTok server cannot connect to the remote application server or republish the stream. It may also occur at any point during the process due to a Vonage Video API platform error.
    • reason — The reason field is only available when the status is either "stopped" or "failed". If the status is "stopped", the reason field will contain either "Max Duration Exceeded" or "Stop Requested." If the status is "failed", the reason will contain a more specific error message.
    • streamId — The ID of the composed stream being published. The streamId is not available when the status is "starting" and may not be available when the status is "failed".

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

  • 200 — Success
  • 403 — Authentication error
  • 500 — Vonage Video API platform error.

Example

curl 
  -X GET 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;"
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render?count=2

Stopping an Experience Composer

Use this method to stop an Experience Composer of an OpenTok session. Note that by default Experience Composers automatically stop 2 hours after they are started. You can also set a different maxDuration value when you create the Experience Composer. When the Experience Composer ends, an event is posted to the callback URL, if you have configured one for the project.

HTTP DELETE to render

Submit an HTTP DELETE request to the following URL:

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

Replace <apiKey> with your OpenTok API key. Replace <experienceComposerId> with the ID of the Experience Composer you want to stop. You get the Experience Composer ID from the response received when you start an Experience Composer.

DELETE header properties

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

Response

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

  • 204 — No content.
  • 400 — Invalid request.
  • 403 — Authentication error.
  • 404 — The Experience Composer (with the specified ID) was not found, or it has already stopped.
  • 500 — Vonage Video API platform error.

Example

curl 
  -X DELETE 
  -H "Content-Type: application/json" 
  -H "X-OPENTOK-AUTH:&lt;valid-jwt-token&gt;" 
  https://api.opentok.com/v2/project/&lt;apiKey&gt;/render/&lt;experienceComposerId&gt;/

Starting an Audio Connector WebSocket connection

Use this method to send audio from a Vonage Video API session to a WebSocket.

For more information, including details of the WebSocket data, see the Audio Connector developer guide.

HTTP POST to connect

Submit an HTTP POST request to the following URL:

Replace <apiKey> with your OpenTok API key.

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": "OpenTok session ID",
  "token": "A valid OpenTok token",
  "websocket": {
    "uri": "wss://service.com/ws-endpoint",
    "streams": [
      "streamId-1",
      "streamId-2"
    ],
    "headers": {
      "headerKey": "headerValue"
    },
    "audioRate" : 8000,
    "bidirectional": false,
    "audioTransport": {
      "transport": "binary"
    }
  }
}

The JSON object includes the following properties:

  • sessionId​ (required) — The OpenTok session ID that includes the OpenTok streams you want to include in the WebSocket stream. The Audio Connector feature is only supported in routed sessions (sessions that use the OpenTok Media Router).

  • token​ (required) — The OpenTok token to be used for the Audio Connector connection to the OpenTok session. You can add token data to identify that the connection is the Audio Connector endpoint or for other identifying data. (The OpenTok client libraries include properties for inspecting the connection data for a client connected to a session.) If you will be using the Audio Connector to publish audio to the session, set the role of the token to publisher or moderator. See the Token Creation developer guide.

  • websocket ​(required): Included details for the WebSocket:

    • uri ​(required): A publicly reachable WebSocket URI to be used for the destination of the audio stream (such as "wss://example.com/ws-endpoint").

    • streams (optional) — An array of stream IDs for the OpenTok streams you want to include in the WebSocket audio. If you omit this property, all streams in the session will be included.

    • headers​ (optional) — An object of key-value pairs of headers to be sent to your WebSocket server with each message, with a maximum length of 512 bytes.

    • audioRate (optional) — A number representing the audio sampling rate in Hz. Accepted values are 8000, 16000 (the default) and 24000.

    • audioTransport (optional) — A JSON object that configures how audio is serialized on the WebSocket wire. By default, audio is sent as raw binary PCM 16-bit frames. Set this to use JSON-wrapped base64 audio, which is required by some AI vendors (for example, OpenAI Realtime). The object has the following properties:

      • transport (required) — "binary" (raw PCM16, the default) or "json".
      • encoding (required when transport is "json") — "base64".
      • audio_field (optional) — The JSON key for the outbound audio data. Defaults to "audio".
      • receive_audio_field (optional) — The JSON key for inbound audio data (when bidirectional is enabled). Defaults to the same value as audio_field.
      • static_fields (optional) — An object of extra key-value pairs included in every outbound JSON audio message.

    • bidirectional (optional) — (Boolean) Whether to send audio data from the WebSocket connection to a stream published in the session. The default is false (the WebSocket is not used to publish a stream). See details in the Audio Connector developer guide.

Response

A successful call results in an HTTP response with status code 200, with details included in the JSON response data:

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007"
}

The JSON response data includes the following properties:

  • id — A unique ID identifying the Audio Connector WebSocket connection.

  • connectionId — The OpenTok connection ID for the Audio Connector WebSocket connection in the OpenTok session.

Upon error, the HTTP response will have one of the following status codes:

  • 400 — Invalid request. This response may indicate that data in your request data is invalid JSON, or if one of the JSON properties is invalid.
  • 403 — Authentication error.
  • 409 — Only routed sessions are allowed to initiate Audio Connector WebSocket connections.
  • 500 — OpenTok server error.

Example

Starting an Audio Connector WebSocket:

api_key=12345
json_web_token="jwt_string" # replace with a JSON web token (see "Authentication")
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
data='{\
  "sessionId" : "'$session_id'", \
  "token": "A valid OpenTok token", \
  "websocket": { \
    "uri": "wss://example.com/ws-endpoint", \
    "streams": [
      "opentok-stream-id-1",
      "opentok-stream-id-2",
    ]
  },
  "headers": [
    "X-Custom-Header-1": "header-data-1"
    "X-Custom-Header-2": "header-data-2"
  ],
}'
curl \
  -i \
  -H "Content-Type: application/json" \
  -H "X-OPENTOK-AUTH:$json_web_token" \
    -d "$data" \
  https://api.opentok.com/v2/project/$api_key/connect

Creating a new project API key

Use this method to create an OpenTok API key and secret for a project.

Important: After you create the project, it may take up to 60 seconds for it to be available for use.

You can also create a new project on your Vonage Video API account page.

POST to partner

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/project

POST header properties

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

POST data

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.

HTTP Response

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.

Example

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

Changing the status for a project API key

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.

PUT to partner

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.

PUT header properties

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.

PUT data

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

{
  "status": "ACTIVE" | "SUSPENDED"
}

HTTP Response

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.

Example

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

Deleting a project

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 Vonage Video API account page.

DELETE to partner

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.

DELETE header properties

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.

HTTP Response

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

  • 204 — Success (no content).
  • 403 — Authentication error.
  • 404 — Not found. There is no project for the API key provided.
  • 500 — OpenTok server error.

Example

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

Getting information about projects

Use this method to get a project details record describing the project (or to get the records for all projects). See project details object.

GET to partner

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

GET header properties

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.

HTTP Response

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.

Generating a new project API secret

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.

POST to refreshSecret

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.

POST header properties

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.

HTTP Response

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.

Example

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