Skip to Content
操作指南聊天室代理的部門授權

把部門資料表分享給聊天室代理

情境：營運部的「訂單」資料表要分享給一個聊天室，而且代理只能看指定欄位；經理明確開啟該系統後，代理才應看見它。

前置條件

你需要部門 22222222-2222-4222-8222-222222222222 的部門管理者權限（在該部門 role ≥ CAN_MANAGE_DEPARTMENT，或公司管理者）才能在步驟 1 建立並指派標籤——只有資料表 moderator 身分、沒有該角色的人在那一步會收到 403 Insufficient permissions for department-level access.——另外需要資料表 moderator 權限來管理 grant。聊天室必須已啟用部門自訂表格的代理工作範圍；grant 與代理工作範圍是各自獨立的開關，帶標籤的資料表還需要聊天室的洞察設定（步驟 4）。

以下 private 請求都使用使用者 access token。先從資料表回應的 settings.column_mapping 取得穩定的內部欄位 ID；不要把顯示名稱放進 visible_columns。

步驟

1. 建立系統標籤並指派資料表

若「訂單系統」標籤已存在，可直接使用既有 tag_id。否則先呼叫 tags.create 建立標籤，再以 tags.assignTable 指派部門資料表。

POST /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/table-tags
Content-Type: application/json
 
{
  "name": "訂單系統",
  "description": "訂單與出貨資料",
  "color": "#2563EB"
}
POST /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/table-tags/44444444-4444-4444-8444-444444444444/tables/33333333-3333-4333-8333-333333333333

保留建立或查得的 tag_id。洞察設定是以標籤為單位，不是以單一資料表為單位。

2. 對聊天室建立最小 grant

這個 upsert 同時定義讀寫權限與欄位投影。範例只允許內部成員讀取全部資料列，禁止新增與編輯，並只顯示「訂單編號」和「狀態」兩個內部欄位 ID；對應操作是 chatroomPermissions.grant。

PUT /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/tables/33333333-3333-4333-8333-333333333333/chatroom-permissions/11111111-1111-4111-8111-111111111111
Content-Type: application/json
 
{
  "audience": "internal",
  "can_read": "all",
  "can_insert": false,
  "can_edit": "none",
  "visible_columns": [
    "col_55555555_5555_4555_8555_555555555555",
    "col_66666666_6666_4666_8666_666666666666"
  ]
}

visible_columns 屬於這一筆 grant；同一張表分享給另一個聊天室時，可使用不同投影。

3. 從兩側驗證 ACL

先由 moderator 透過 chatroomPermissions.list 列出部門表 grants，再由聊天室成員以 tables.shared 列出分享進來的表。

GET /private/module/custom_tables/department/22222222-2222-4222-8222-222222222222/tables/33333333-3333-4333-8333-333333333333/chatroom-permissions
GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/shared

第二個回應應包含「訂單」，但可讀資料仍會套用該 grant 的 audience、列權限與欄位投影。加入聊天室本身不會自動產生 grant。對分享表完全沒有權利的成員（不能讀、編輯或新增，也不是管理者或版主），在 tables/shared 中看不到這張表。

4. 為聊天室的代理開啟已標記的系統

帶有部門標籤的分享部門資料表，要等到它的某個標籤在聊天室的洞察設定中啟用，才會載入該房間的代理：由聊天室 manager 送出 PUT /private/chatrooms/setting/custom-table-tags/{chatroom_id} 與 {"tag_ids": […]}（replace-set），或讓 department scope 的 IaC 文件帶一行 insight_selection。洞察設定屬於聊天室設定，不在本手冊範圍內，而且它不會改變 ACL。

5. 驗證代理可見性

在聊天室開啟一個新的代理回合，要求列出可用的自訂表格。若 ACL grant、部門資料表代理工作範圍與洞察 opt-in 都成立，代理會看見「訂單」，且只取得 grant 允許的欄位。洞察切換不會放寬 REST ACL。

另一道門：同一個房間裡的外部 client

以上全部走的是內部受眾。步驟 2 的 grant 寫 audience: "internal"，涵蓋的是聊天室 1111… 裡的公司使用者；它不會給同一個房間裡的外部 client 任何權限。

「外部 client」才是正確的說法，而且這個區分不是措辭問題：平台會把任何解析出來、且 platform 不是 agent 的 client 標記為外部，也就是 LINE（含群組與聊天室情境）、Messenger、Instagram——以及 Web 頻道的訪客。Moderator 可以直接授權給他們——替這個房間建立 audience: "external" 的聊天室 grant，或建立個別 client grant（clientPermissions.grant）。在此之外，AI 還以 custom_tables_apply_permission 與 custom_tables_use_passphrase 提供自助路徑，但只針對該 client 名單內的表：它自己房間的聊天室資料表，以及以 audience: "external" 分享進這個房間、或已有 client grant 的部門資料表（公司資料表永遠不會進入 agent 名單）。每一部分也取決於 agent job 的自訂資料表 scope（聊天室資料表需要 chatroom scope，部門資料表需要 department scope），而帶有部門 tag 的分享部門資料表，只有在它的某個 tag 於此房間啟用為 Insight 系統時才會載入——已有 client grant 的資料表則略過這項 Insight 檢查。上面那張「訂單」表只分享給內部受眾，所以無法申請——custom_tables_apply_permission 會回答這個聊天室裡找不到該表——直到 moderator 加上一筆 external 受眾的 grant（即使所有層級都是 none）。通行碼也依同一份名單運作：client-access 設定存在於聊天室、部門與公司資料表，所以分享給房間 external 受眾的部門資料表上的通行碼是可用的。

在 v5.7.0 之前，agent 協定把那一節命名為「Social Media Channel Access Tools」，並告訴模型那些工具「只提供給社群媒體 client」。於是 Web 頻道訪客明明手上握著這兩個工具，卻被告知它們不是給自己用的，那條取得存取權的路從來沒有被提出來——訪客只看到一張讀不到的表，也沒有任何辦法開口要。這一節現在叫「External Client Access Tools」，並明確列出 Web 頻道。

有兩件事要分清楚。這兩個工具不存在，代表 client 名單內的每一張表都已授予讀取、新增與編輯——名單外的表（例如上面的「訂單」）根本不會觸發這些工具，因此 client 實際上是被擋在門外。而且這條路徑不會把 REST ACL 放寬到 moderator 決定之外：核准會寫入一筆明確的 client 列（granted_via: "review"），帶有 moderator 選定的層級與條件、沒有 visible_columns（欄位 ACL 仍然適用）。這一列會取代該 client 的房間 external 受眾 grant，所以決定其存取權的是核准內容，而不是房間 grant 的欄位投影。Moderator 這一側的審核佇列見 Grant 類型與 row policy，AI 那一側見 Agent 工具箱。

你會看到什麼

grant 清單會保留聊天室、audience、讀寫能力與兩個 visible_columns；tables/shared 會列出部門表。代理的新回合能找到這張表，但看不到投影之外的欄位。

常見錯誤

不要在此處猜測狀態碼；直接查看 grant 錯誤表與分享表錯誤表。

試試看

在 API Playground 依序選擇 tags.create、tags.assignTable、chatroomPermissions.grant 與 tables.shared。

Last updated on
指南總覽連結、彙總與查找