Working with streams

View as Markdown

Each Realtime Media Streams (RTMS) stream for a Zoom Phone call follows a predictable flow. It starts when a call connects, continues while your app connects to the required servers, receives stream data, and maintains the connection, and ends when the call ends or the stream stops.

Streams have the following states:

State
INACTIVEDefault state. The session is not active yet.
INITIALIZEThe session is initializing.
STARTEDThe session has started.
PAUSEDThe session has been paused either by the consumer or the user.
RESUMEDThe paused session has been resumed.
STOPPEDThe session is being stopped by the consumer, user, or the call ending.

Prerequisites

To process RTMS data, your app needs the appropriate event subscriptions and scopes. For more information, see Adding RTMS to your app.

Once your app is configured, RTMS streams follow these steps:

Step 1: RTMS is started

Phone RTMS streams start automatically when a call starts. An admin turns this on for each user in the phone system policy settings, and the user can stop the stream during the call if you turn on user controls.

The streaming experience is controlled by the following settings. An admin chooses these settings for each user when turning on RTMS. For more information, see Turn on RTMS for phone users.

  • Automatic start starts RTMS as soon as a phone call begins, and ends RTMS when the call ends.
  • User controls let the user stop RTMS during a call from the Zoom client.
  • Audio notifications play a recorded message to inform the callee that the call is being recorded in real time.

Step 2: App receives streaming notification

Zoom sends phone.call_rtms_started webhook events when RTMS streaming starts. You can then use the information in the event to establish a signaling connection in the next step. The server_urls value can contain one URL for each media protocol, separated by commas, such as wss:// and srt://.

To receive notifications when new streams are available, create an HTTP POST handler in your web app. This handler acts as the endpoint for incoming webhook events. In your app settings, provide the URL of this endpoint. For more information, see Subscribe to RTMS events.

After you receive an event, verify the event's signature to ensure it's from a trusted source.

Store the server_urls value from the phone.call_rtms_started event for the stream. The phone.call_rtms_interrupted event doesn't include server_urls, so you need the stored value if you reconnect. For more information, see Failover and reconnection.

Step 3: App establishes signaling connection

Establishing a signaling connection to an RTMS server enables your app to establish and manage a WebSocket connection with the RTMS server. It begins with a signed handshake and includes messages for session readiness, state updates, and stream control.

The signaling connection provides lifecycle updates for the media connections, such as when they start, stop, or encounter an interruption event.

When you have the connection details and know a stream is available, you can start the connection to the signaling server. Split the server_urls value on commas, and select the wss:// URL, because an srt:// URL can't be used for signaling.

  1. Create a signature that your app uses to securely connect to the RTMS server. Replace client_id and secret with your app's Client ID and Client Secret, and call_id and rtms_stream_id with the call_id and rtms_stream_id from the streaming notification event.

HMACSHA256(client_id + "," + call_id + "," + rtms_stream_id, secret);

  1. Your app sends a signaling handshake request with the call_id and rtms_stream_id from the streaming notification event, the signature you just created, and protocol_version set to 2. If the handshake is successful, your app receives a signaling handshake response confirming the connection and containing the media server locations.

Once your app has successfully established a signaling connection, it can establish the media connections.

Step 4: App establishes the media connections

For each media type, split its value in media_server.server_urls on commas. If you use protocol V2, a value can include an srt:// URL as well as a wss:// URL. Select the wss:// URL to connect over WebSockets, or the srt:// URL to connect over SRT. For SRT setup, see Connecting over SRT.

Use the URLs listed in media_server.server_urls in the signaling handshake response to establish media WebSocket connections. Zoom Phone streams provide two media types: audio and transcript. Open one media connection for each type.

  1. Your app sends a media handshake request with the call_id and rtms_stream_id from the streaming notification, the signature you created in Step 3, and media_type set to 1 for audio or 8 for transcript. If the handshake is successful, your app receives a media handshake response confirming the connection.
  1. Your app sends a client ready ACK message to the signaling connection to indicate readiness to receive media.

Now that the connections are made, your app can receive media data.

Step 5: App receives media data

Once the connections are established, your app receives continuous streams of:

For more information about working with media data, see Handling media data.

Your app also receives call events during the stream, such as when participants join or leave, or when the call is held, resumed, or transferred. For the full list, see Zoom Phone events.

Step 6: App maintains connections

Throughout the stream, your app must:

If a connection is interrupted, see Failover and reconnection for more information on reestablishing the connection.

Step 7: Stream ends

The RTMS stream ends when:

  • The call ends
  • The user stops streaming (stop_reason 2)
  • A connection error ends the stream (stop_reason 10)

Your app receives a phone.call_rtms_stopped notification indicating the stream has ended. The stop_reason field explains why. For the possible values, see RTMS_STOP_REASON.