> 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/api-integration/endpoint-behaviors/conversation-visibility-events.md).

# 對話可見權限與即時事件

說明整合端如何理解對話可見權限、即時事件與未讀數的一致性。

整合後台對話功能時，請把「使用者可以查看哪些對話」視為同時約束列表、未讀數與即時事件的同一項權限。一般成員只會收到自己可查看的對話事件；具備完整對話查看權限的成員，才會收到該對話平台的所有事件。

## REST 與即時事件的差異 <a href="#rest-and-realtime" id="rest-and-realtime"></a>

* 收件匣 REST 回應中的未讀數，會依目前登入成員可查看的對話計算。
* 對話 REST 回應仍保留收件匣未讀數欄位，以維持既有 API 回應格式。
* 即時事件不攜帶組織共用的未讀數。收到事件後，整合端應重新取得收件匣資料，再更新畫面上的未讀徽章。

{% hint style="warning" %}
不要用即時事件中的收件匣資料覆寫個人化未讀數，也不要假設同一組織的所有成員都能看到相同對話。
{% endhint %}

## 權限變更後的處理 <a href="#permission-change" id="permission-change"></a>

即時連線會在建立連線時計算成員可接收的對話範圍。管理員調整成員的對話查看權限後，整合端應重新建立即時連線，讓新的事件範圍生效；REST 查詢則會依當下權限回傳資料。

## 整合檢查清單 <a href="#integration-checklist" id="integration-checklist"></a>

1. 使用一般成員與擁有者兩種身分測試，不要只用擁有者帳號驗證。
2. 確認一般成員不會收到不可查看對話的建立、更新、事件或已讀通知。
3. 收到即時事件後重新讀取收件匣資料，確認未讀數與對話列表一致。
4. 權限變更後重新連線，再驗證事件範圍。

{% hint style="info" %}
若要了解角色與聯絡人的權限差異，請參考[角色（Role）和聯絡人（Contact）的差異](/tech/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/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.