Recovering from Service Disruptions with the Vonage Video API

Introduction

Real-time video applications are expected to be always-on. Whether you're powering a Telehealth consultation, a Financial Advisory session, or a large-scale virtual event, your end users have zero tolerance for unexplained drops. When something goes wrong on the platform side, the difference between a seamless recovery and a frustrated user often comes down to one thing: whether your application is listening.

Over the past couple of years, the Vonage Video API platform has shipped a significant set of resilience capabilities: service disruption callbacks, automatic session migration, and self-healing infrastructure. A lot of this has been announced in SDK release notes and roadmap webinars, but it hasn't been pulled together in one place. This post does exactly that.

If you built your application before 2023, there's a good chance you're not taking advantage of any of the latest features we’ve shipped. In this article, we’ll go through these features to make sure you’re making full use of what Vonage can offer. 

How the Platform Handles Disruptions

Before diving into what your application should do, it helps to understand what the platform does automatically.

The Vonage Video API runs across 11+ regional data centers with redundant infrastructure and continuous health checks. When a server needs to be rotated or fails unexpectedly, the platform's monitoring system detects the issue and triggers recovery. For most disruptions, the platform self-heals without any action required from you or your users.

But "most" isn't "all." For the cases where a session, broadcast, archive, or SIP call is impacted, the platform now sends your application server a callback - immediately, without waiting for a status page update. Your job is to listen for that callback and act on it.

Step 1: Register Your Callback URLs

Service disruption callbacks are only delivered if you have callback URLs configured on your project. Without them, none of the events described below will reach your application server.

Vonage Video Dashboard

1. Log in to your Vonage API Dashboard.

2. Go to Applications and select your Video-enabled application (or create a new one).

3. Click Edit, scroll to Capabilities → Video.

4. Under Session Monitoring, enter your callback URL for session events.

5. Configure separate callback URLs for Archiving, SIP Call Monitoring, and Experience Composer as needed.

6. Click Save.

OpenTok Environment (TokBox Account Portal)

1. Log in to your Vonage Video API Account.

2. Select the project you want to configure.

3. Scroll to Project Settings.

4. Under each service (Session Monitoring, Archiving, SIP Call Monitoring), click Configure and enter your callback URL.

Callback delivery and retry: The platform uses an exponential backoff retry policy. If your server is temporarily unavailable, callbacks are retried starting at 5 seconds, doubling up to a maximum of 15 minutes, for up to 24 hours. After 24 hours, the individual event is dropped. Make sure your callback endpoint returns a 200 response promptly to acknowledge receipt.

Firewall rules: If your callback server restricts inbound traffic by IP, allow the Vonage callback service IP range: 216.147.0.0/18.

Step 2: Handle Service Disruption Callbacks

Service disruption callbacks are standard webhook POST requests sent to your registered URLs. They use existing event formats with new reason codes that indicate an unexpected platform-side failure - not a normal client disconnect.

Here is what to expect for each service and what to do when you receive it.

Video Session

When a Video API media server shuts down unexpectedly, you'll receive a sessionDestroyed event at your session monitoring callback URL:

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "sessionDestroyed",
  "reason": "forceDisconnected",
  "timestamp": 1700000000000
}

The key signal here is "reason": "forceDisconnected" - this indicates a platform-side shutdown, not a normal client disconnect.

Recovery action: Create a new session and reconnect your endpoints. Do not reuse the destroyed session ID. A session is terminated one minute after the last participant disconnects, and attempting to reconnect to a destroyed session can result in connections landing on servers that are no longer able to serve traffic. Session creation takes milliseconds, so there is no practical reason to cache and reuse session IDs across separate calls.

SIP Interconnect

If there is an unexpected outage on the SIP service, you'll receive a callDestroyed callback at your SIP monitoring URL:

{
  "sessionId": "YOUR_SESSION_ID",
  "projectId": "YOUR_PROJECT_ID",
  "event": "callDestroyed",
  "reason_code": "703",
  "reason_message": "Unexpected Clearing",
  "timestamp": 1700000000000
}

reason_code: 703 is the signal for an unexpected platform-side clearing, as opposed to a normal call teardown 700).

Recovery action: Redial the SIP endpoint using the Dial API to re-establish the SIP call.

Broadcast

Two types of broadcast disruption callbacks are possible, both delivered to your broadcast monitoring URL:

RTMP/HLS URL error (while in started status):

• For RTMP: you'll receive "status": "error" for each affected RTMP endpoint URL.

• For HLS: you'll receive "hlsStatus": "error" on the HLS endpoint.

Internal server failure:

{
  "status": "failed",
  "reason": "Internal server failure",
  "event": "broadcast"
}

Recovery action: Reissue a new broadcast on the same session using the Broadcast API, then update the broadcast URL for any client endpoints that were consuming the stream.

Archive (Recording)

{
  "id": "ARCHIVE_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure"
}

Recovery action: Reissue a new archive on the same session using the Archive API. Note that content recorded up to the point of failure may be partially available - check the archive status after the disruption.

Experience Composer

{
  "id": "RENDER_ID",
  "sessionId": "YOUR_SESSION_ID",
  "status": "failed",
  "reason": "Internal server failure",
  "event": "render"
}

Recovery action: Start a new Experience Composer render on the session using the Render API.

Step 3: Enable Session Migration

Service disruption callbacks tell you when something has gone wrong so you can react. Session Migration goes one step further - it keeps your live session connected automatically when the underlying server is rotated, so participants never need to manually reconnect.

Session Migration went Generally Available in Client SDK 2.31 (August 2025).

What it covers

Session Migration handles the live session layer:

• Live video sessions (all participants reconnect automatically)

• SIP calls via the Dial API

• Audio Connector WebSockets via the Connect API

Important: Session Migration covers the live session only. Archives, broadcasts, and Experience Composer renders running at the time of a rotation are not migrated automatically - use the disruption callbacks described above to handle those services.

Enabling session migration for Web and Native SDKs

Pass sessionMigration: true when initialising the session:

// JavaScript SDK

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

The same option is available in the iOS, Android, Windows, Linux, and macOS SDKs - refer to the Server Rotation guide for platform-specific syntax.

Enabling session migration for SIP (Dial API)

Include sessionMigration: true in the Dial API request body:

{
  "sessionId": "YOUR_SESSION_ID",
  "token": "YOUR_TOKEN",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Enabling session migration for Audio Connector (Connect API)

The same sessionMigration: true flag applies in the Connect API request body.

Note: sessionMigration defaults to false and must be explicitly set. We recommend enabling it for all production sessions, particularly for long-running sessions or those in healthcare, finance, or other high-stakes contexts where a manual reconnect would be disruptive.

Best Practices

Keep the following in mind:

Handle callbacks idempotently. Your callback handler may receive the same event more than once in edge cases. Make sure your recovery logic (re-dialing SIP, restarting an archive, etc.) is safe to call multiple times without creating duplicate resources.

Respond quickly with a 200. The platform considers a callback delivered only when it receives a 200 HTTP response. If your handler takes too long to respond, the platform may retry. Acknowledge receipt immediately and process the recovery logic asynchronously if needed.

Test your recovery paths before going to production. The Vonage Video Playground and Session Inspector are useful tools for observing session events and validating that your callback handler is receiving and processing events correctly.

Don't reuse destroyed session IDs. This is worth repeating. A session is terminated one minute after the last participant disconnects. Reconnecting to a destroyed session ID can land connections on servers that are shutting down. Always create a fresh session.

Conclusion

The Vonage Video API platform is designed to self-heal, but your application needs to be a willing partner in that process. Here's the short version:

Further reading

• Server Rotation and Session Migration guide

• Session Monitoring guide

• Video REST API reference

• How to Configure Session Monitoring Callbacks