Sessions

To connect to a session, you have to specify the session you want to connect to using its session ID.

Each session ID identifies a unique 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 on 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.

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:

• The media mode (whether or not to use the Media Router).
• The archiving preference (whether to automatically archive the session).
• A location hint (to specify the geo-location of the session).

The Media Router and media modes

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 TURN server to relay audio-video streams. (Prior to version 2.2, the server SDKs referred to these sessions as peer-to-peer sessions. However, even when using those SDKs, sessions will still use the TURN server to relay streams if firewall restrictions block peer-to-peer streaming). TLS 1.3 and a strong certificate of at least 3072 bits are used for session negotiation.

• Routed — The session uses the Media Router to route audio-video streams between clients. The Media Router provides the following benefits:

  • TLS 1.3 and a strong certificate of at least 3072 bits are used for all signaling.

  • The 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 Media Router, a publisher sends one stream once to the router and it forwards it to each subscribing client.)

  • The 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 Media Router supports the archiving feature, which lets you record, save, and retrieve sessions.

  • In sessions that use the Media Router, lowering the frame rate for a published video proportionally reduces the bandwidth the stream uses.

  • The Media Router supports the scalable video feature. Scalable video can greatly improve the quality of video in multi-party sessions.

  • For clients using the iOS and Android SDKs, relayed sessions support only two clients connected to the session. The Media Router supports additional clients for multiparty sessions on mobile devices.

  • The Media Router supports the SIP interconnect feature, which lets you connect sessions to SIP gateways.

• 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 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 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). For a complete guide including use cases, configuration details, code samples, and interaction with other features, see the Single Peer Connection developer guide.

  To enable single peer connection, use the following client SDK APIs:

  • Web SDK - See the singlePeerConnection property of the options you pass into OT.initSession()
  • Android SDK — Session.Builder.setSinglePeerConnection()
  • iOS SDK — OTSessionSettings.singlePeerConnection
  • Linux SDK — otc_session_settings_set_single_peer_connection()
  • macOS SDK — otc_session_settings_set_single_peer_connection()
  • Windows SDK — SinglePeerConnection property of the Session.Builder class
  • React Native SDK - The enableSinglePeerConnection property of the options prop of the OTSession component

• Media Mesh optimization: The platform uses Media Mesh to automatically optimize routed sessions by connecting each participant to the media router in their nearest regional datacenter. This reduces latency and improves quality, particularly for geographically distributed sessions.

  Media Mesh is enabled by default and requires no configuration. To override this optimization and restrict media to a specific region, see Regional Media Zones.

Adaptive media routing

Adaptive media routing (AMR) is a performance optimization for routed sessions. AMR evaluates each publisher's subscriber count individually. When a publisher has only one subscriber and no features that require the Media Router are in use (e.g., archiving, live streaming, SIP, etc.), the platform relays that publisher's media peer-to-peer to the subscriber instead of routing it through the Media Router. This reduces latency and can improve audio and video quality.

The session remains a routed session at all times. AMR does not change the session's media mode — it only changes the media path used under the hood. Your application code, tokens, and server-side session configuration stay exactly the same. The switch between peer-to-peer relaying and Media Router relaying is handled transparently by the client SDKs.

When AMR uses peer-to-peer relaying

AMR will relay media directly between a publisher and its subscriber (bypassing the Media Router in the media path) when all of the following are true:

• The publisher has exactly one subscriber.
• None of the features listed in the next section are active.

For example, a session with four publishers and four subscribers can remain entirely in peer-to-peer relaying as long as each publisher has only one subscriber and no Media Router features are in use.

When AMR switches to the Media Router

The platform transitions a publisher's media to flow through the Media Router when any of the following conditions apply:

• A publisher has more than one subscriber (for example, a second client subscribes to the same published stream).
• Archiving is started (including sessions with automatic archiving enabled).
• Live-streaming broadcasts are started.
• SIP interconnect is used.
• Experience Composer is rendering the session.
• Audio Connector is active.
• Live Captions are enabled.

Once any trigger activates, all publishers' media will be routed seamlessly through the Media Router.

SDK support

AMR was introduced in OpenTok.js v2.24.7 and version 2.27.0 of the Android, iOS, Windows, macOS, Linux, and React Native client SDKs. Clients on older SDK versions in a routed session will always use the Media Router.

Implications for debugging and development

AMR is transparent to your application logic, but there are a few things to be aware of during development and troubleshooting:

• Inspector may show erroneous clientDisconnection events when a publisher's media transitions from peer-to-peer relaying to the Media Router (for example, when a second client subscribes to a stream). These events do not represent actual disconnections — the participants remain connected throughout the transition. This is a known issue in Inspector.

• MediaStream objects may change during transitions. When AMR switches between peer-to-peer relaying and the Media Router, the underlying MediaStream for a subscriber is replaced. If your application accesses MediaStream objects directly (for example, to render video in custom <video> elements), you must handle this change with one of the following:

  • Recommended: Use the Media Stream Available API (available in OpenTok.js v2.27.7+). The mediaStreamAvailable event on Publisher and Subscriber objects automatically accounts for any changes caused by AMR, delivering the correct MediaStream whenever a transition occurs.

  • Legacy approach (pre-v2.27.7): Listen for the play event on the Subscriber's video element to detect when the MediaStream has been replaced, and update your custom rendering accordingly. See the Accessing MediaStream Objects for Subscribers guide.

• Connection and stream events continue to fire normally. You do not need to handle AMR transitions in your session event listeners. The streamCreated, streamDestroyed, connectionCreated, and connectionDestroyed events reflect the actual state of participants, not the underlying media path.

Interaction with other features

• Single Peer Connection (SPC): SPC is only active when media flows through the Media Router. While AMR is relaying a publisher's media peer-to-peer, SPC does not apply for that stream. Once the stream transitions to the Media Router, SPC takes effect if it is enabled.

• End-to-end encryption: End-to-end encryption works with AMR. Media is encrypted regardless of whether it flows peer-to-peer or through the Media Router.

• Audio fallback: Subscriber audio fallback is a Media Router feature that applies normally once a stream is routed through the Media Router. However, while AMR is relaying a publisher's media peer-to-peer, Publisher audio fallback automatically disable the video to safeguard the audio stream, if needed. Once the stream transitions to the Media Router, both publisher and subscriber audio fallback apply as normal.

• Simulcast and Scalability: While AMR is relaying media peer-to-peer, scalable video is automatically disabled regardless of the codec in use. When the stream transitions to the Media Router, scalable video behavior depends on the codec and the application's scalable video setting in the dashboard:

  • VP8: If scalable video is set to On or Auto in the dashboard, simulcast is automatically enabled on the routed leg once the transition to the Media Router occurs.
  • VP9: Scalable video is enabled by default when routed through the Media Router.
  • H.264: Scalable video is not supported and remains off by default in all cases.

  For more details on scalable video settings and codec support, see the Scalable video guide.

Archive mode

When 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 Media Router).

By default, sessions are not automatically archived.

Location hints

When you create a session, you can set the IP address that the Vonage video platform will use to select the best server to control the session in its global network.

If no location hint is set when you create the session (which is recommended), the session control server is selected based on the location of the first client connecting to the session.

Set a location hint 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.

For media streaming, the system will always use the location hint to connect to the nearest media server (SFU), ensuring that media traffic is routed through the most optimal server for the client’s geographic location.

Best practices when creating sessions

Session ID reuse

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 the Session 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.

Enable session migration or limit sessions to 8 hours

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.

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.

Choosing Relayed vs. Routed session type

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 Media Router and media modes.

Creating sessions

While working on a test version of your app, you can obtain a test session ID from the BUILD & MANAGE > Applications page of your Vonage Account.

Your credentials can also be found on the Dashboard, please follow our getting started guide to learn more.

For your own implementation please checkout the server-side SDKs.

If you need to dynamically generate multiple session IDs, use the server-side SDKs not the Project Page.

Use the session ID with a client SDK to connect to a video session.

You will also need to generate a token for each user connecting to the session.

The Media Router provides the following benefits:

• The Media Router can decrease bandwidth usage in multiparty sessions. (When the mediaMode property is set to RELAYED, each client must send a separate audio-video stream to each client subscribing to it.)
• The 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 for that client (without affecting other clients), and the client receives audio only. If the client's connectivity improves, the video stream is restored.
• The Media Router supports the Archiving feature, which lets you record, save, and retrieve sessions.

Creating a relayed session

In a relayed session, clients will attempt to send streams directly between each other.

However, if clients cannot connect due to firewall restrictions, the session uses the TURN server to relay audio-video streams.

Follow our step-by-step tutorials to learn how to generate relayed sessions

Creating an automatically recorded session

You can create a session that is automatically archived.

For more information, see the Archiving guide.

Using sessions in client applications

Use the session ID in the client SDK to connect to a session.

You will also need to generate a token for each user connecting to the session.