Get started with the OpenTok JS library

Get started quickly by building a simple app in less than 15 minutes.

1Get an API key
2Generate a session & token
3Initialize & connect to session
4Publish a stream
5Subscribe to streams

This tutorial is meant for those who learn by doing. You will build a simple application that publishes and subscribes to video streams. If you prefer, you can instead read the conceptual API overview.

You can copy the code from this page or download the source code to get started using OpenTok in your own application. Note that this code will only work if it is running from your webserver. If you would like to run this code locally (not on a webserver), you should follow these instructions to configure your Flash permissions.

If you'd rather see this tutorial in video form, watch the screencast here.

If you are interested in using the OpenTok iOS SDK to use OpenTok video in an iOS app, please check out the OpenTok iOS SDK Getting Started guide.

1Get an API key

You need an API key to get started. Fill out the form below to get one on this page (it will also be emailed to you).

Name Must enter a valid name.

Email Must enter a valid email.

I agree to the TokBox Platform Terms of Service Must agree to terms of service.
Congrats! Here is your shiny new API key:
- Your API Key: 1566461
We inserted your key in to the rest of the tutorial code and emailed it to you for later reference. Let's move on.
There was an error getting your API key, try getting one here.

Email support@tokbox.com if the problem persists.
2Generate a session & token

OpenTok revolves around the concept of sessions. Think of a session as a room. You generate sessions on your server and then distribute them to users you would like in the same room.

To connect to a session, each user needs a token. Think of a token as a key to get in to a room. Tokens are what provide security—you can use them to specify what permissions a user has.

In this tutorial, we handle sessions and tokens for you, but when you build your own app you will use our Server-Side SDK to generate your own.

Your sessionId: 3272571db984f6c32e9bf3e457f14f70d84c531d

We inserted your session ID into the rest of the tutorial. Now, let's write some code.

There was an error getting your API key. Email support@tokbox.com with this error.

3Initialize & connect to session

Now that we have an API key and session we can initialize and connect to an OpenTok session.

First, we import the OpenTok JavaScript API (line 4). Second, we set the API key, sessionId, and token variables for the session (lines 7-9), which have been populated with the ones you generated. Last, we initialize the session, set up an event handler to alert us when we connect to the session, and then connect to the session (lines 13-19).

Execute the code to connect to your session. You will received an alert when it's connected.

			
			<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
			<head>
				<title>OpenTok Getting Started</title>
				<script src="http://staging.tokbox.com/v0.91/js/TB.min.js"></script>

				<script type="text/javascript">
					var apiKey = '1127';
					var sessionId = '14685d1ac5907f4a2814fed28294d3f797f34955';
					var token = 'devtoken';						

					TB.setLogLevel(TB.DEBUG); // Set this for helpful debugging messages in console

					var session = TB.initSession(sessionId);			
					session.addEventListener('sessionConnected', sessionConnectedHandler);			
					session.connect(apiKey, token);

					function sessionConnectedHandler(event) {
						alert('Hello world. I am connected to OpenTok :).');
					}			
				</script>

			</head>

			<body>
			</body>
			</html>

4Publish a stream

Once we're connected to the session publishing a stream to the session is simple, just call session.publish() and pass it the name of the div to replace with your video stream (line 21).

Execute the code to connect to your session and publish your stream.


			<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
			<head>
				<title>OpenTok Getting Started</title>
				<script src="http://staging.tokbox.com/v0.91/js/TB.min.js"></script>

				<script type="text/javascript">
					var apiKey = '1127';
					var sessionId = '14685d1ac5907f4a2814fed28294d3f797f34955';
					var token = 'devtoken';						
					
					TB.setLogLevel(TB.DEBUG);			

					var session = TB.initSession(sessionId);			
					session.addEventListener('sessionConnected', sessionConnectedHandler);
					session.connect(apiKey, token);

					var publisher;

					function sessionConnectedHandler(event) {
						// Publish my webcam stream and put it in a div
						publisher = session.publish('myPublisherDiv');
					}
				</script>

			</head>

			<body>
				
			</body>
			</html>

5Subscribe to streams

Subscribing to a stream is also simple, just call session.subscribe() and pass it the stream object and the id of the div the stream should replace (line 45).

In this app we subscribe to all streams in the session (though you could add logic here to suit your own application). To do this, we call our subscribeToStreams function within the sessionConnected and streamCreated event handlers, which are executed when you connect to the session and when a new stream is created.

Execute the code to publish and subscribe to streams in the session.


			<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
			<head>
				<title>OpenTok Getting Started</title>
				<script src="http://staging.tokbox.com/v0.91/js/TB.min.js"></script>

				<script type="text/javascript">
					var apiKey = '1127';
					var sessionId = '14685d1ac5907f4a2814fed28294d3f797f34955';
					var token = 'devtoken';						
					
					TB.setLogLevel(TB.DEBUG);			

					var session = TB.initSession(sessionId);			
					session.addEventListener('sessionConnected', sessionConnectedHandler);
					session.addEventListener('streamCreated', streamCreatedHandler);			
					session.connect(apiKey, token);

					var publisher;

					function sessionConnectedHandler(event) {
						publisher = session.publish('myPublisherDiv');
						
						// Subscribe to streams that were in the session when we connected
						subscribeToStreams(event.streams);
					}
					
					function streamCreatedHandler(event) {
						// Subscribe to any new streams that are created
						subscribeToStreams(event.streams);
					}
					
					function subscribeToStreams(streams) {
						for (var i = 0; i < streams.length; i++) {
							// Make sure we don't subscribe to ourself
							if (streams[i].connection.connectionId == session.connection.connectionId) {
								return;
							}

							// Create the div to put the subscriber element in to
							var div = document.createElement('div');
							div.setAttribute('id', 'stream' + streams[i].streamId);
							document.body.appendChild(div);
                                
							// Subscribe to the stream
							session.subscribe(streams[i], div.id);
						}
					}
				</script>
			</head>

			<body>
				
			</body>
			</html>

Next Steps

Congrats! You've built your first OpenTok app (hopefully in less than 15 minutes).

If you'd like to learn more, we suggest that you either read our conceptual overview or dive in to more advanced tutorials to learn how to do things like resizing, moderation, and audio control. If you have questions please post them in our forums.

Launch Your App

When you're done building your app, fill out the launch form to get access to our production servers for improved performance. Learn how to move your application from the staging servers (used in this tutorial) to production here.