close search

Add Messaging, Voice, and Authentication to your apps with Nexmo APIs

Visit Nexmo

OpenTok .NET SDK

API referenceDownloadSamplesGitHub

The OpenTok .NET SDK lets you generate sessions and tokens for OpenTok applications that run on the .NET platform. The SDK also includes support for working with OpenTok archives.


Using the Package Manager Console:

PM> Install-Package OpenTok


Download the latest release from the Releases Page. Unzip the file and place the place the OpenTok.dll, dependent assemblies, and supporting files into your own project.



Import the OpenTokSDK namespace into any files that will be using OpenTok objects. Then initialize an OpenTokSDK.OpenTok object using your own API Key and API Secret.

using OpenTokSDK;

// ...

int ApiKey = 000000; // YOUR API KEY
string ApiSecret = "YOUR API SECRET";
var OpenTok = new OpenTok(ApiKey, ApiSecret);

Creating Sessions

To create an OpenTok Session, call the OpenTok instance's CreateSession(string location, MediaMode mediaMode, ArchiveMode archiveMode) method. Each of the parameters are optional and can be omitted if not needed. They are:

The return value is a OpenTokSDK.Session object. Its Id property is useful to get an identifier that can be saved to a persistent store (such as a database).

// Create a session that will attempt to transmit streams directly between clients
var session = OpenTok.CreateSession();
// Store this sessionId in the database for later use:
string sessionId = session.Id;

// Create a session that uses the OpenTok Media Router (which is required for archiving)
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED);
// Store this sessionId in the database for later use:
string sessionId = session.Id;

// Create an automatically archived session:
var session = OpenTok.CreateSession(mediaMode: MediaMode.ROUTED, ArchiveMode.ALWAYS);
// Store this sessionId in the database for later use:
string sessionId = session.Id;

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to it. You can generate a token either by calling an OpenTokSDK.OpenTok instance's GenerateToken(string sessionId, Role role, double expireTime, string data) method, or by calling a OpenTokSDK.Session instance's GenerateToken(Role role, double expireTime, string data) method after creating it. In the first method, the sessionId is required and the rest of the parameters are optional. In the second method, all the parameters are optional.

// Generate a token from a sessionId (fetched from database)
string token = OpenTok.GenerateToken(sessionId);

// Generate a token by calling the method on the Session (returned from CreateSession)
string token = session.GenerateToken();

// Set some options in a token
double inOneWeek = (DateTime.UtcNow.Add(TimeSpan.FromDays(7)).Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
string token = session.GenerateToken(role: Role.MODERATOR, expireTime: inOneWeek, data: "name=Johnny");

Working with Archives

You can only archive sessions that use the OpenTok Media Router (sessions with the media mode set to routed).

You can start the recording of an OpenTok Session using a OpenTokSDK.OpenTok instance's StartArchive(sessionId, name, hasVideo, hasAudio, outputMode) method. This will return an OpenTokSDK.Archive instance. The parameter name is optional and used to assign a name for the Archive. Note that you can only start an Archive on a Session that has clients connected.

// A simple Archive (without a name)
var archive = OpenTok.StartArchive(sessionId);

// Store this archive ID in the database for later use
Guid archiveId = archive.Id;

You can add a name for the archive (to use for identification) by setting the name parameter of the OpenTok.StartArchive() method.

You can also disable audio or video recording by setting the hasAudio or hasVideo parameter of the OpenTok.StartArchive() method false.

By default, all streams are recorded to a single (composed) file. You can record the different streams in the session to individual files (instead of a single composed file) by setting the outputMode parameter of the OpenTok.StartArchive() method OutputMode.INDIVIDUAL.

You can stop the recording of a started Archive using a OpenTokSDK.OpenTok instance's StopArchive(String archiveId) method or using the OpenTokSDK.Archive instance's Stop() method.

// Stop an Archive from an archive ID (fetched from database)
var archive = OpenTok.StopArchive(archiveId);

To get an OpenTokSDK.Archive instance (and all the information about it) from an archive ID, use the OpenTokSDK.OpenTok instance's GetArchive(archiveId) method.

var archive = OpenTok.GetArchive(archiveId);

To delete an archive, you can call a OpenTokSDK.OpenTok instance's DeleteArchive(archiveId) method or call the OpenTokSDK.Archive instance's Delete() method.

// Delete an archive from an archive ID (fetched from database)

// Delete an archive from an Archive instance (returned from GetArchive)

You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is done using an OpenTokSDK.OpenTok instance's ListArchives(int offset, int count) method. You may optionally paginate the Archives you receive using the offset and count parameters. This will return an OpenTokSDK.ArchiveList object.

// Get a list with the first 1000 archives created by the API Key
var archives = OpenTok.ListArchives();

// Get a list of the first 50 archives created by the API Key
var archives = OpenTok.ListArchives(0, 50);

// Get a list of the next 50 archives
var archives = OpenTok.ListArchives(50, 50);

Note that you can also create an automatically archived session, by passing in ArchiveMode.ALWAYS as the archiveMode parameter when you call the OpenTok.CreateSession() method (see "Creating Sessions," above).


You need an OpenTok API key and API secret, which you can obtain by logging into your TokBox account.

The OpenTok .NET SDK requires .NET Framework 3.5 or greater.

Release Notes

See the Releases page for details about each release.

Important changes since v2.2.0

Changes in v2.2.1:

The default setting for the CreateSession() method is to create a session with the media mode set to relayed. In previous versions of the SDK, the default setting was to use the OpenTok Media Router (media mode set to routed). In a relayed session, clients will attempt to send streams directly between each other (peer-to-peer); if clients cannot connect due to firewall restrictions, the session uses the OpenTok TURN server to relay audio-video streams.

Changes in v2.2.0:

This version of the SDK includes support for working with OpenTok archives.

This version of the SDK includes a number of improvements in the API design. These include a number of API changes: