How Events Work in the Video API

The Vonage Video API is event-driven: every change to a session, stream, or optional module emits documented callbacks to client SDK objects (Session, Publisher, Subscriber) and to any server endpoints you register. By wiring handlers to those callbacks—and reviewing them later with tools such as Video Inspector or Archiving Inspector—you can react immediately, keep participants informed, and maintain an audit trail of session health.

Event Flow in a Video Session

1. Connect and join: A client connects to a session and begins publishing or subscribing to streams.
2. Emit lifecycle events: SDK objects (Session, Publisher, Subscriber, Stream) and optional modules — such as archiving, broadcast/live streaming, experience composer, live captions, transcription, and SIP interconnect — dispatch events describing lifecycle and media changes (see the optional-module table below for the full catalog).
3. Dispatch events: The Vonage cloud forwards events to other participants and, when configured, to your webhook endpoints.
4. React in your app: Update UI state in the client, trigger business logic on the server, and record noteworthy events for later analysis. Together, these capabilities let you observe, respond, and recover dynamically — all through a unified event model.

Where Video Events Come From

Client SDKs

Session

• Lifecycle: sessionConnected, connectionDestroyed.
• Stream changes: streamCreated, streamPropertyChanged.
• Signaling: signal, signal:type.
• Optional modules: Client-facing callbacks for archiving, transcription, live captions, and broadcast control. See the module guides linked below for full coverage.

Publisher

• Media state: videoEnabled / videoDisabled, audioEnabled / audioDisabled.
• Network/quality: networkQualityLevelChanged, videoDisableWarning.
• Optional modules: Device-permission prompts (accessDialogOpened, accessDenied) and diagnostics (audioLevelUpdated) live in the publishing guides.

Subscriber

• Media state: videoEnabled / videoDisabled.
• Network/quality: videoDisableWarning, videoDisableWarningLifted.
• Optional modules: audioLevelUpdated, layout callbacks, and other subscriber helpers appear in the customization guides.

Callback families

Observability tools

• Video Inspector exposes session event timelines for debugging.
• Archiving Inspector shows a timeline of archiving status changes for archive workflows.
• Insights API and Video usage reports aggregate event counts for analytics.
• The Session Monitoring guide explains how to track when sessions start and stop and how to surface current session state for operational teams (for example, in your own dashboards).

Working with client event handlers

Event handler patterns are similar across SDKs. The example below shows the JavaScript SDK:

session.on('streamCreated', event => {
  const stream = event.stream;
  session.subscribe(stream, 'subscriberContainer', {
    insertMode: 'append',
    width: '100%',
    height: '100%'
  });
});

publisher.on('networkQualityLevelChanged', event => {
  updateNetworkBadge(event.networkQualityLevel);
});

session.on('signal:layout', event => {
  applyLayout(event.data);
});

Apply the same pattern across the native SDKs: iOS (OTSessionDelegate), Android (Session.SessionListener), Windows (Session event handlers), and Linux (otc_session_callbacks) by binding the equivalent observers for each platform.

For complete event lists, see the platform references: JavaScript Session events, iOS OTSessionDelegate callbacks, Android Session.SessionListener, Windows Session API, and Linux session callbacks.

Handling Server Callbacks

• Register callback URLs in the Vonage Video API dashboard or via the Video REST API.
• Validate incoming requests, implement retries, and review the signing/backoff policy described in Verifying Webhooks.
• Process payloads quickly: enqueue work and respond with 200 OK to avoid retries blocking your queue.
• Log request bodies alongside metadata such as session ID, connection ID, and stream ID so you can correlate server callbacks with client-side events.

Choosing Where to React

• Handle transient UX updates in the client: Use SDK events to toggle UI indicators (mute icons, reconnection banners) or prompt the user to refresh.
• Escalate persistent issues to the server: Forward stream or connection failures to your backend to alert operators or trigger automated workflows.
• Persist audit data: Store critical callbacks (for example sessionDestroyed, archive failed) for compliance and post-incident reviews.
• Test with tooling: Reproduce issues by replaying session logs in the Video Inspector or exporting metrics via the Insights API.

Event Reference Cheat Sheet

Additional Resources

• Joining a session
• Publishing streams
• Signaling guide
• Session monitoring guide
• Audio fallback and network resilience
• Verifying Webhooks