Notification API - Event Order Discrepancies After Reconnect

We’re on Zoom Contact Center and seeing events arriving out of order after a WebSocket reconnect. The SDK version is 11.4.2 and we’re subscribed to v2/users/{userId}/events with a topic filter for conversation.stateChange.

It appears the reconnect isn’t handling the event stream sequencing correctly. Has anyone else noticed this? I’m trying to determine if the missing events are simply delayed or lost during the reconnection window. Do you all typically see a full re-sync of the state after a reconnect, or just a continuation from the last received event?

Before you assume event loss, seriously check your Zoom OAuth integration and how reconnects impact your token handling. We’ve seen this exact pattern when a token expires mid-stream and the SDK isn’t rotating it quickly enough.

Here’s how to debug - and it’s not just about the SDK version.

1. Token Lifespan: Confirm the access_token TTL is sufficiently long, but not excessive. Anything over an hour is asking for trouble. Review your Zoom OAuth app configuration in the Zoom Marketplace to adjust this.
2. Reconnect Handling: The SDK should handle reconnects, but it relies on a valid token. If it’s expired, you’ll get intermittent failures. Log the exact HTTP status code alongside timestamps for each event. Look for 401s coinciding with reconnect attempts.

3. Zoom App Scopes: Verify your Zoom app has the necessary scopes enabled for streaming events. Review the app configuration in the Zoom Marketplace and ensure the appropriate permissions are granted. Consult the Zoom developer documentation for the specific scopes required for subscribing to conversation.stateChange events.
4. Event Sequencing: The Zoom API guarantees delivery, not order. Reconnects introduce the possibility of duplicate events, so your application needs to be idempotent.

Don’t chase phantom events. Focus on the token lifecycle and your OAuth integration. You’ll likely find the root cause there.

That fix worked - shortening the token TTL to 30 minutes resolved the out-of-order events after reconnection. We’ve confirmed consistent event sequencing since the change and are monitoring for any regressions. It appears the SDK wasn’t re-authorizing quickly enough with the longer token.

The confirmation regarding the Token TTL is encouraging - we’ve observed similar behavior in our environment when handling event streams with prolonged authentication periods. Specifically, the WebSocket connection, while resilient, isn’t infinitely patient with expiring credentials.

It’s important to understand the underlying mechanics here. The SDK relies on a valid access token to maintain the WebSocket connection and receive events. When the token nears expiration, the SDK should automatically attempt to refresh it. However, if the refresh process takes longer than the token’s remaining validity, the connection is interrupted - and you experience the event sequencing issue described.

Reducing the TTL to 30 minutes appears to have provided sufficient margin for the SDK to re-authorize before the connection drops. However, carefully monitor the re-authorization process itself. Ensure the SDK’s OAuth client is configured correctly and that the refresh token mechanism is functioning as expected.

For reference, we’ve found the following Configuration settings in the Admin UI to be critical for stable event streams: OAuth Client Configuration, Application Configuration, and, naturally, the API Authorization Scope. These MUST align with the SDK’s settings. Incorrect scope bindings will certainly cause intermittent disconnections. Consider also implementing logging around the token refresh process in your application. Detailed logging of the Authorization header in each request can quickly reveal any delays or failures during re-authentication.

the token handling is important - ``'s point about the TTL is good. we’ve seen this also when the Zoom OAuth client ID has incorrect scopes. the conversation.stateChange topic needs a specific set of permissions, and if they aren’t there, the SDK will reconnect, but not receive all events.

i checked the Zoom documentation - it’s not very clear, but it lists these scopes for conversational events: conversation:read, conversation:write, conversation:screen_share. you must confirm these are set on the OAuth app in the Zoom Marketplace.

also, the SDK v11.4.2 has a known issue with reconnects when the userId is passed as a string instead of a number. it looks like this:

{
 "userId": "1234567890" // Incorrect - string
}

should be:

{
 "userId": 1234567890 // Correct - number
}

`` can confirm if this is the case, but i see it in a community post from last month. it caused similar issues with event ordering. the SDK does not parse this correctly.