Suggestions

close search

OpenTok

Constructor

new OpenTok(apiKey, apiSecret)

Contains methods for creating OpenTok sessions, generating tokens, and working with archives.

To create a new OpenTok object, call the OpenTok constructor with your OpenTok API key and the API secret for your TokBox account. Do not publicly share your API secret. You will use it with the OpenTok constructor (only on your web server) to create OpenTok sessions.

Be sure to include the entire OpenTok Node.js SDK on your web server.

Parameters:
Name Type Description
apiKey String Your OpenTok API key. (See your TokBox account page.)
apiSecret String Your OpenTok API secret. (See your TokBox account page.)

Methods

Name Description
createSession(options, callback) Creates a new OpenTok session.
deleteArchive(archiveId, callback) Deletes an OpenTok archive.
dial(sessionId, token, sipUri, options) Dials a SIP gateway to input an audio-only stream into your OpenTok Session.
forceDisconnect(sessionId, connectionId, callback) Disconnects a participant from an OpenTok session.
generateToken(sessionId, options) Creates a token for connecting to an OpenTok session.
getArchive(archiveId, callback) Gets an Archive object for the given archive ID.
listArchives(options, callback) Retrieves a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.
startArchive(sessionId, options, callback) Starts archiving an OpenTok session.
stopArchive(archiveId, callback) Stops an OpenTok archive that is being recorded.

createSession(options, callback)

Creates a new OpenTok session. The session is passed as Session object into the callback function. The sessionId property is the session ID, which uniquely identifies the session. On error, an Error object is passed into the callback function.

For example, when using the OpenTok.js library, use the session ID when calling the OT.initSession() method (to initialize an OpenTok session).

OpenTok sessions do not expire. However, authentication tokens do expire (see the generateToken(String, TokenOptions) method). Also note that sessions cannot explicitly be destroyed.

A session ID string can be up to 255 characters long. You can also create a session using the OpenTok REST API or by logging in to your TokBox account.

Parameters:
Name Type Description
options Object This object defines options for the session, including the following properties (both of which are optional):
  • location (String) — An IP address that the OpenTok servers will use to situate the session in the global OpenTok network. If you do not set a location hint, the OpenTok servers will be based on the first client connecting to the session.
  • mediaMode (String) — Determines whether the session will transmit streams using the OpenTok Media Router ("routed") or not ("relayed"). By default, the setting is "relayed".

    With the mediaMode parameter set to "relayed", 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.

    The OpenTok Media Router provides the following benefits:

  • archiveMode (String) — Whether the session is automatically archived ("always") or not ("manual"). By default, the setting is "manual", and you must call the StartArchive() method of the OpenTok object to start archiving. To archive the session (either automatically or not), you must set the mediaMode parameter to "routed".
    • The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the mediaMode parameter is set to "relayed", 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 through 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.
callback function The function that is called when the operation completes. This function is passed two arguments:
  • error — On failiure, this parameter is set to an Error object. Check the error message for details. On success, this is set to null.
  • session — On sucess, this parameter is set to a Session object. The sessionId property of this object is session ID of the session. On error, this parameter is not set.

deleteArchive(archiveId, callback)

Deletes an OpenTok archive.

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. For an "available" archive, it also removes the archive file, making it unavailable for download.

Parameters:
Name Type Description
archiveId String The archive ID of the archive you want to delete.
callback function The function to call upon completing the operation. On successfully deleting the archive, the function is called with no arguments passed in. On failure, an error object is passed into the function.

dial(sessionId, token, sipUri, options)

Dials a SIP gateway to input an audio-only stream into your OpenTok Session. Part of the SIP feature.
Parameters:
Name Type Description
sessionId The session ID corresponding to the session to which the user will connect.
token The token for the session ID with which the SIP user will use to connect.
sipUri The sip URI the SIP Interconnect feature will dial.
options Object An optional options object with the following properties:

  • headers (Object) — Custom headers to be added to the SIP INVITE request iniated from OpenTok to the Third Party SIP Platform. All headers must start with the "X-" prefix, or a Bad Request (400) will be thrown.
  • auth (Object) — The credentials to be used for HTTP Digest authentication in case this is required by the third-party SIP platform.
    • "username" -- The username to be used in the SIP INVITE.
    • "password" -- The password to be used in the SIP INVITE.
  • secure (Boolean) — Whether the SIP media streams should be transmitted encrypted or not.

Returns:
A SipInterconnect object with the following properties:
  • id -- The unique conference ID of the SIP call.
  • connectionId -- The connection ID of the audio-only stream representing the SIP call.
  • streamId -- The stream ID of the audio-only stream representing the SIP call.

forceDisconnect(sessionId, connectionId, callback)

Disconnects a participant from an OpenTok session. This is the server-side equivalent to the forceDisconnect() method in OpenTok.js
Parameters:
Name Type Description
sessionId The session ID for the OpenTok session that the client you want to disconnect is connected to.
connectionId The connection ID of the client you want to disconnect.
callback function The function to call upon completing the operation. Two arguments are passed to the function:
  • error — An error object (if the call to the method fails).

generateToken(sessionId, options)

Creates a token for connecting to an OpenTok session. In order to authenticate a user connecting to an OpenTok session, the client passes a token when connecting to the session.

For testing, you can also generate a token by logging into your TokBox account.

Parameters:
Name Type Description
sessionId The session ID corresponding to the session to which the user will connect.
options An object that defines options for the token (each of which is optional):
  • role (String) — The role for the token. Each role defines a set of permissions granted to the token:
    • 'subscriber' — A subscriber can only subscribe to streams.
    • 'publisher' — A publisher can publish streams, subscribe to streams, and signal. (This is the default value if you do not specify a role.)
    • 'moderator' — In addition to the privileges granted to a publisher, in clients using the OpenTok.js 2.2 library, a moderator can call the forceUnpublish() and forceDisconnect() method of the Session object.
  • expireTime (Number) — The expiration time for the token, in seconds since the UNIX epoch. The maximum expiration time is 30 days after the creation time. If a fractional number is specified, then it is rounded down to the nearest whole number. The default expiration time of 24 hours after the token creation time.
  • data (String) — A string containing connection metadata describing the end-user.For example, you can pass the user ID, name, or other data describing the end-user. The length of the string is limited to 1000 characters. This data cannot be updated once it is set.
  • initialLayoutClassList (Array) — An array of class names (strings) to be used as the initial layout classes for streams published by the client. Layout classes are used in customizing the layout of videos in live streaming broadcasts and composed archives.
Returns:
The token string.

getArchive(archiveId, callback)

Gets an Archive object for the given archive ID.
Parameters:
Name Type Description
archiveId String The archive ID.
callback function The function to call upon completing the operation. Two arguments are passed to the function:
  • error — An error object (if the call to the method fails).
  • archive — The Archive object.

listArchives(options, callback)

Retrieves a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.
Parameters:
Name Type Description
options Object An options parameter with three properties:
  • count — The maximum number of archives to return. The default number of archives returned is 50 (or fewer, if there are fewer than 50 archives). The method returns a maximum of 1000 archives.
  • offset — The offset for the first archive to list (starting with the first archive recorded as offset 0). 1 is the offset of the archive that started prior to the most recent archive. This property is optional; the default is 0.
  • sessionId — Specify the id of a session in order to retrieve archives specifically for that session. This property is optional. When no sessionId is specified, then the method will return archives from any session created with your API key.

If you don't pass in an options argument, the method returns up to 1000 archives starting with the first archive recorded.

callback function The function to call upon completing the operation. Two arguments are passed to the function:
  • error — An error object (if the call to the method fails).
  • archives — An array of Archive objects.

startArchive(sessionId, options, callback)

Starts archiving an OpenTok session.

Clients must be actively connected to the OpenTok session for you to successfully start recording an archive.

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

Parameters:
Name Type Description
sessionId The session ID of the OpenTok session to archive.
options Object An optional options object with the following properties (each of which is optional):

  • name (String) — the name of the archive, which you can use to identify the archive. The name is set as a property of the Archive object, and it is a property of archive-related events in the OpenTok client libraries.
  • hasAudio (Boolean) — Whether the archive will include an audio track (true) or not (false). The default value is true (an audio track is included). If you set both hasAudio and hasVideo to false, the call to the startArchive() method results in an error.
  • hasVideo (Boolean) — Whether the archive will include a video track (true) or (not false). The default value is true (a video track is included). If you set both hasAudio and hasVideo to false, the call to the startArchive() method results in an error.
  • outputMode (String) — Whether all streams in the archive are recorded to a single file ("composed", the default) or to individual files ("individual").
For more information on archiving and the archive file formats, see the OpenTok archiving programming guide.

callback function The function to call upon completing the operation. Two arguments are passed to the function:
  • error — An error object (if the call to the method fails).
  • archive — The Archive object. This object includes properties defining the archive, including the archive ID.

stopArchive(archiveId, callback)

Stops an OpenTok archive that is being recorded.

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

You cannot stop an archive that is not being recorded.

Parameters:
Name Type Description
archiveId String The archive ID of the archive you want to stop recording.
callback function The function to call upon completing the operation. Two arguments are passed to the function:
  • error — An error object (if the call to the method fails).
  • archive — The Archive object.
Returns:
The Archive object corresponding to the archive being STOPPED.