> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/conversation-visibility-events.md).

# 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 <a href="#rest-and-realtime" id="rest-and-realtime"></a>

* 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.

{% hint style="warning" %}
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.
{% endhint %}

## Handling Permission Changes <a href="#permission-change" id="permission-change"></a>

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 <a href="#integration-checklist" id="integration-checklist"></a>

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.

{% hint style="info" %}
To understand the permission differences between roles and contacts, see [Differences Between Roles and Contacts](/tech/en/serve/contacts/role-vs-contact.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/conversation-visibility-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.