close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Back to Tutorials

Archiving Tutorial (Web)


The OpenTok archiving API lets you record a session's audio-video streams to MP4 files.

Setting up the server

In order to archive OpenTok sessions, you need to have a server set up. There are many ways to implement archiving with a server, but for this tutorial we'll be quick-launching a simple PHP server.

To launch the server, simply click the Heroku button below, at which point you'll be sent to Heroku's website and prompted for your OpenTok API Key and API Secret — you can get these values on your project page in your Video API account. If you don't have a Heroku account, you'll need to sign up (it's free).


Want to explore the code? The button above launches server code from the learning-opentok-php GitHub repo. Visit the repo to review the code as well as additional documentation — you can even fork the repo and make changes before deploying.

Setting up your project

To follow this tutorial, clone OpenTok's Web sample apps repo on GitHub:

git clone

Then open the Archiving folder in your code editor to follow along.

Important: You can only archive sessions that use the OpenTok Media Router (sessions with the media mode set to routed). The default learning-opentok-php code used by this tutorial app uses routed sessions.

Exploring the code

You use server-side code to start and stop archive recordings. In the config.js file, you set the SAMPLE_SERVER_BASE_URL variable to the base URL of the web service the app calls to start archive recording, stop recording, and play back the recorded video. Make sure there is no trailing / at the end of the domain.

The archiving application uses the same code available in the Basic Video Chat folder to initialize an OpenTok session, connect to the session, publish a stream, and subscribe to stream in the session. If you have not already gotten familiar with the code in that branch, consider checking out the Basic Client Tutorial for web before continuing.

To start recording the video stream, the user clicks the Start Recording button which invokes the startArchive() method in app.js. This method in turn sends an XHR (or Ajax) request to server. The session ID of the session that needs to be recorded is passed in JSON format to the server. As soon as the startArchive() method is called, the Start Recording button is hidden and the Stop Recording button is displayed.

function startArchive() {
    url: SAMPLE_SERVER_BASE_URL + '/archive/start',
    type: "POST",
    contentType: "application/json", // send as JSON
    data: JSON.stringify({"sessionId": sessionId}),

    complete: function() {
      //called when complete
      console.log('startArchive() complete');

    success: function() {
      //called when successful
      console.log('successfully called startArchive()');

    error: function() {
      //called when there is an error
      console.log('error calling startArchive()');


To stop the recording, the user clicks the Stop Recording button, which invokes the stopArchive() method. This method is similar to the startArchive() method in that it sends an Ajax request to the server to stop the archive. The only difference is that this method passes the archive ID of the archive that needs to be stopped as a URL parameter instead of the sessionId. The Stop Recording button is hidden and the View Archive button is enabled.

function stopArchive() {
  $.post(SAMPLE_SERVER_BASE_URL + '/archive/' + archiveID + '/stop');
  $('#view').prop('disabled', false);

To download the archive that has just been recorded, the user clicks View Archive button which invokes the viewArchive() method. This method is similar to the startArchive() and stopArchive() methods in that it sends an Ajax request to the server. The server code has the logic to check if the archive is available for download or not. If it is available, the application is redirected to the archive page. If not, a new page is loaded which continuously checks whether the archive is available for download or not and loads it when it is available.


For more information on archiving, see the OpenTok archiving developer guide.

Congratulations! You've finished the Archiving Tutorial for Web.
You can continue to play with and adjust the code you've developed here, or check out the Next Steps below.