Conversation Visibility Permissions and Real-Time Events

Explains how integrations should handle conversation visibility permissions, real-time events, and unread count consistency.

When integrating backend conversation features, treat “which conversations a user can view” as a single permission that applies consistently to lists, unread counts, and real-time events. Regular members receive events only for conversations they can view. Only members with permission to view all conversations receive every event from the conversation platform.

Differences Between REST and Real-Time Events

• The unread count in an inbox REST response is calculated based on the conversations visible to the currently signed-in member.

• Conversation REST responses retain the inbox unread count field to preserve the existing API response format.

• Real-time events do not include an organization-wide shared unread count. After receiving an event, the integration should retrieve the inbox data again before updating the unread badge on the screen.

Do not overwrite a personalized unread count with inbox data from a real-time event, and do not assume that every member of the same organization can view the same conversations.

Handling Permission Changes

When a real-time connection is established, the range of conversation events that the member can receive is determined. After an administrator changes a member's conversation visibility permissions, the integration should re-establish the real-time connection so that the new event scope takes effect. REST queries return data according to the permissions in effect at the time of the request.

Integration Checklist

1. Test with both a regular member and an owner; do not validate only with an owner account.

2. Confirm that regular members do not receive creation, update, event, or read notifications for conversations they cannot view.

3. After receiving a real-time event, retrieve the inbox data again and confirm that the unread count matches the conversation list.

4. Reconnect after permissions change, then verify the event scope again.

To understand the permission differences between roles and contacts, see Differences Between Roles and Contacts.