Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalWhen you connect to an OpenTok session on an app, you specify the session you want to connect to using an OpenTok session ID. Each session ID identifies a unique OpenTok session. You can think of a session as a room in which participants meet and chat.
The number of sessions you create and how clients connect to them depend upon the requirements of your app. If your app connects users with one another for a one-time meeting, create a unique session for that meeting. However, if your app connects users over various days in the same "room," then you can create one session and reuse it. If one group of users meet with each other, while other groups meet independently, create unique sessions for each group.
OpenTok sessions do not expire. However, authentication tokens do expire. Also note that sessions cannot explicitly be destroyed.
When you create a session, you can specify the following options, which are described in the sections that follow:
When you create a session, you specify how clients in the session will send audio-video streams, known as the media mode. There are two options:
Relayed — In a relayed session, clients will attempt to send audio-video streams directly between each other (peer-to-peer). However, if clients cannot connect due to firewall restrictions, the session uses the OpenTok TURN server to relay audio-video streams. (Prior to version 2.2, the OpenTok server SDKs referred to these sessions as peer-to-peer sessions. However, even when using those SDKs, sessions will still use the OpenTok TURN server to relay streams if firewall restrictions block peer-to-peer streaming.)
The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the media mode property is set to relayed, each client publishing a stream must send it separately to each client subscribing to it. With the OpenTok Media Router, a publisher sends one stream once to the router and it forwards it to each subscribing client.)
The OpenTok Media Router can improve the quality of the user experience through subscriber 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 OpenTok archiving feature, which lets you record, save, and retrieve OpenTok sessions.
The OpenTok Media Router supports live-streaming broadcasts.
The OpenTok Media Router supports Experience Composer.
In sessions that use the OpenTok Media Router, lowering the frame rate for a published video proportionally reduces the bandwidth the stream uses.
The OpenTok Media Router supports the scalable video feature. Scalable video can greatly improve the quality of video in multi-party sessions.
In clients using the OpenTok iOS and Android SDKs, relayed sessions support only two clients connected to the session. The OpenTok Media Router supports additional clients for multiparty sessions on mobile devices.
Routed sessions (sessions that use the OpenTok Media Router) also benefit from the following optimizations:
Adaptive media routing. Beginning with OpenTok.js v2.24.7 and v2.27.0 of the other client SDKs (for Android, iOS, Windows, macOS, Linux, and React Native), routed sessions are optimized to use adaptive media routing, if possible. Adaptive media routing determines if media can be relayed without the OpenTok Media Router for one-on-one video streaming, to optimize the media performance between two participants. The routed session automatically adapts media routing to use the OpenTok Media Router when required — for sessions with three or more participants, archiving, live-streaming broadcasts, SIP interconnect, Experience Composer, Live Captions, and Audio Connector.
With the addition of adaptive media routing, there is also a scalableVideo option in the OpenTok.js
OT.initPublisher() method, to override the default and disable scalable video
for the publisher in a routed session.
Single peer connection. Starting with version 2.28.0 of the client SDKs for iOS, Android, Windows, macOS, and Linux, routed sessions will support single peer connection. With single peer connection enabled, all subscriber streams for a client are delivered with a single connection to the OpenTok Media Router (even if they are published by different clients). The benefits of enabling single peer connection include reduced client resource consumption, improved rate control, and, in case of mobile native devices, support for larger sessions. When single peer connection is disabled (the default), the client will use a separate connection to the OpenTok Media Router for each audio/video bundle.
Single peer connection is only available in routed sessions (sessions that use the Vonage Video API Media Router). To enable single peer connection, use the following client SDK APIs:
singlePeerConnection property of the options you pass into OT.initSession() Session.Builder.setSinglePeerConnection()OTSessionSettings.singlePeerConnectionotc_session_settings_set_single_peer_connection()otc_session_settings_set_single_peer_connection()SinglePeerConnection property of the Session.Builder classenableSinglePeerConnection property of the options prop of the OTSession componentWhen you create a session, you can set the archive mode so that the session is archived automatically. This only applies to routed sessions (sessions that use the OpenTok Media Router). By default, sessions are not automatically archived.
When you create a session, you can set the IP address that Vonage will use to situate the session in its global network. If no location hint is set when you create the session (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Set location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. Specify an IP address that is representative of the geographical location for the session.
When possible, do not reuse session IDs between different video chat conversations. Instead, generate new session IDs for each distinct video chat on your application.
This is important, especially when using OpenTok Inspector. In Inspector, session quality scores and data are indexed by session ID. A session ID that is reused for multiple conversations is more difficult to debug using Inspector, and sessions with re-used session IDs tend to report lower aggregate quality scores than the actual experienced call quality.
Modern cloud auto-scaling makes it necessary to establish a minimum rotation time for services. Any sessions lasting more than 8 hours might be disconnected, as they may reside in services that are scaling out or scaling in.
Version 2.30.0 and later of the Vonage Video API client SDKs includes a session migration feature that seamlessly transfers all participants in a session to a new server during server rotation. This feature ensures session continuity with minimal disruption to participants. See Server rotation and session migration.
Note for clients using versions of the client SDKs lower than 2.30.0: We recommend that, for sessions planned to last longer than 8 hours, you migrate connected users to a new session before any potential timeout/reconnection events. This will ensure the best user experience.
Clients are also disconnected from a session if they do not publish or subscribe to streams within 4 hours of connecting.
You can use session monitoring to get notifications when sessions stop or time out and when a group of Video API servers for a session is scheduled to be rotated.
For more information, see Server Rotation.
Use a relayed instead of a routed session, if you have only two participants (or maybe even three) and you are not using archiving. Using relayed sessions reduces the latency between participants, reduces the points of failure and you can get better quality video and audio in most cases.
Routed sessions are required if you want to archive your session. They are recommended if you have more than two or three participants in the session.
For more information, see The OpenTok Media Router and media modes.
While working on a test version of your app, you can obtain a test session ID using a Project Page of of your Video API account.
You can also use one of the OpenTok server-side libraries or the OpenTok REST API to generate a session:
You can also use the OpenTok REST API to create a session.
If you need to dynamically generate multiple session IDs, use one of the OpenTok server-side libraries or the OpenTok REST API — not the Project Page.