close search

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

Visit the Vonage API Developer Portal

Class: OpenTok::OpenTok

Defined in:


Contains methods for creating OpenTok sessions and generating tokens. It also includes methods for returning object that let you work with archives, work with live streaming broadcasts, using SIP interconnect, sending signals to sessions, disconnecting clients from sessions, and setting the layout classes for streams.

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

Instance Method Summary

Constructor Details

#initialize(api_key, api_secret, opts = {}) ⇒ OpenTok

Create a new OpenTok object.


  • api_key (String)

    The OpenTok API key for your OpenTok project.

  • api_secret (String)

    Your OpenTok API key.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :api_url (Symbol)

    Do not set this parameter. It is for internal use by TokBox.

  • :ua_addendum (Symbol)

    Do not set this parameter. It is for internal use by TokBox.

Instance Method Details


An Archives object, which lets you work with OpenTok archives.


A Broadcasts object, which lets you work with OpenTok live streaming broadcasts.


A Connections object, which lets disconnect clients from an OpenTok session.

#create_session(opts = {}) ⇒ Session

Creates a new OpenTok session and returns the session ID, which uniquely identifies the session.

For example, when using the OpenTok JavaScript library, use the session ID when calling the OT.initSession()</a> method (to initialize an OpenTok session).

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

A session ID string can be up to 255 characters long.

Calling this method results in an OpenTokException in the event of an error. Check the error message for details.

You can also create a session using the OpenTok REST API (see /developer/rest/#session_id_production) or at your OpenTok account page.


  • opts (Hash) (defaults to: {})

    (Optional) This hash defines options for the session.

Options Hash (opts):

  • :media_mode (Symbol)

    Determines whether the session will transmit streams the using OpenTok Media Router (:routed) or not (:relayed). By default, this property is set to :relayed.

    With the media_mode property 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.

    With the media_mode property set to :routed, the session will use 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 media_mode property 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.

  • :location (String)

    An IP address that the OpenTok servers will use to situate the session in its global network. If you do not set a location hint, the OpenTok servers will be based on the first client connecting to the session.

  • :archive_mode (Symbol)

    Determines whether the session will be archived automatically (:always) or not (:manual). When using automatic archiving, the session must use the :routed media mode.


  • (Session)

    The Session object. The session_id property of the object is the session ID.

#generate_token(session_id, options) ⇒ String

Generates a token for a given session.


  • session_id (String)

    The session ID of the session to be accessed by the client using the token.

  • options (Hash)

    A hash defining options for the token.

Options Hash (options):

  • :role (Symbol)

    The role for the token. Set this to one of the following values:

    • :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, a moderator can perform moderation functions, such as forcing clients to disconnect, to stop publishing streams, or to mute audio in published streams. See the Moderation developer guide.

  • :expire_time (integer)

    The expiration time, in seconds since the UNIX epoch. Pass in 0 to use the default expiration time of 24 hours after the token creation time. The maximum expiration time is 30 days after the 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.

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


  • (String)

    The token string.


A Signals object, which lets you send signals to OpenTok sessions.


A Sip object, which lets you use the OpenTok SIP gateway.


A Streams object, which lets you work with OpenTok live streaming broadcasts.