Session Migration: Setup and Configuration

This guide provides detailed setup instructions and code examples for enabling session migration across all supported platforms. For an overview of server rotation and its impact on sessions, see Server Rotation and Session Migration.

Overview

Vonage Video API media servers are periodically rotated as part of normal cloud maintenance, autoscaling, and infrastructure updates. Sessions running for more than 8 hours are especially likely to be affected.

Session Migration is available from SDK version 2.30.0 and reached General Availability (GA) in SDK 2.31.0 (August 2025).

How It Works

1. The Vonage backend detects that a media server hosting a session is scheduled for rotation.
2. A sessionNotification event is sent to your server callback endpoint — at 4 hours and again at 1 hour before the rotation.
3. If session migration is enabled, the platform automatically migrates all eligible connections to a new media server.
4. Clients reconnect transparently with minimal downtime. Reconnection typically completes within a few seconds.

What Is Migrated Automatically vs. What Requires Manual Action

When a session migration occurs, not all services are handled automatically. Use the table below to understand what your application needs to handle.

Enabling Automatic Session Migration

Client SDK (Web / Native)

Enable session migration by passing sessionMigration: true when initializing a session:

Web (JavaScript)

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

iOS (Swift)

let settings = OTSessionSettings()
settings.sessionMigration = true
let session = OTSession(apiKey: apiKey, sessionId: sessionId, delegate: self, settings: settings)

Android (Kotlin)

val settings = Session.SessionProperties.Builder()
    .sessionMigration(true)
    .build()
val session = Session(context, apiKey, sessionId, settings)

React Native

// Pass sessionMigration in the OTSession options prop
<OTSession
  apiKey={apiKey}
  sessionId={sessionId}
  token={token}
  options={{ sessionMigration: true }}
>

SIP (Dial API)

To enable session migration for SIP connections, include sessionMigration: true in your Dial API request body:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Audio Connector (Connect API)

To enable session migration for Audio Connector WebSocket connections, include sessionMigration: true in your Connect API request body:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "websocket": {
    "uri": "wss://your-websocket-server.example.com",
    "sessionMigration": true
  }
}

Video Connector (Python SDK)

To enable session migration for the Video Connector, set enable_migration=True in your session settings:

from vonage_video_connector import VonageVideoClient
from vonage_video_connector.models import SessionSettings

session_settings = SessionSettings(enable_migration=True)
client = VonageVideoClient()
client.connect(
    application_id="<application-id>",
    session_id="<session-id>",
    token="<token>",
    session_settings=session_settings
)

Manually Triggering Session Migration

In addition to automatic migration during server rotation, you can manually trigger a session migration using the REST API. This is useful for:

• Proactively migrating a session before a scheduled rotation (for example, at the 7.5-hour mark)
• Testing and simulating server rotation behavior in your application
• Giving customers control over when migration occurs (for example, during a break in a long meeting)

Migrate Session API

Method:

URI:

/v2/project/<projectId>/session/<sessionId>/migrate

Headers:

Example request:

Response Codes

Handling sessionNotification Events

The Vonage platform sends sessionNotification callback events to your server before a scheduled rotation. You can use these to proactively notify users or trigger a manual migration at a convenient time.

Example callback payload:

{
  "sessionId": "<session-id>",
  "projectId": "<project-id>",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "remainingTime": 3600
}

To receive these events, configure a session monitoring callback URL in your Vonage API Dashboard.

Notes

• Session Migration applies only to media server rotation. It does not cover SIP server or TURN server rotation, which are handled separately by the platform.
• sessionMigration defaults to false and must be explicitly enabled on every client connection that should be automatically reconnected. Connections without this flag will be closed during migration.
• The minimum SDK version required is 2.30.0. Ensure all clients are on SDK 2.30.0 or later.
• For SIP and Audio Connector connections, the external call leg (SIP or WebSocket) remains connected during migration. Media connections are re-established on the new server. A brief silence may occur on the endpoint during the switch.
• Archiving, Broadcasting, Experience Composer, and Live Captions must be restarted manually after migration. For Experience Composer, restart on the same session ID — the migrated session retains the same session ID on the new server.
• After migration, the new server provides a 10-minute grace window to allow clients to reconnect and services to resume. During this window, any reconnection attempt or API request (such as starting an archive) is automatically directed to the new server.
• The Migrate Session API prevents multiple concurrent migrations. If a migration is already in progress, the API returns a 409 error with code 15214. If called too soon after session creation or a previous migration, it returns 409 with code 15215.
• For sessions approaching 8 hours, consider proactively triggering migration at the 7.5-hour mark using the Migrate Session API to avoid disruption during peak usage.
• Monitor sessionNotification events — use the 4-hour and 1-hour warnings to proactively inform users or schedule a manual migration at a low-traffic moment.