回撥配置
回撥讓 IM 服務把應用內的變化推送到你的業務服務端（事件回撥），並在使用者發訊息、加好友、加群之前詢問你的服務端（同步回撥），說明見回撥概述。本頁介紹如何在控制檯中新增回撥地址、選擇事件、開啟同步回撥，以及檢視投遞記錄和重新投遞。
回撥在應用詳情的“回撥”標籤頁中管理，下面有三個子標籤頁：
| 子標籤頁 | 內容 |
|---|---|
| 回撥地址 | 新增、修改、驗證、測試、暫停和刪除回撥地址；點選地址的名稱開啟詳情，檢視簽名金鑰、投遞佇列、請求記錄和統計，批次重新投遞 |
| 同步回撥 | 開啟和設定發訊息前、發聊天室訊息前、加好友前、加群前四種同步回撥，測試和檢視統計 |
| 事件目錄 | 全部事件型別、說明和 data 的示例 |
誰可以操作
回撥會把使用者資料和訊息內容發到你指定的地址，新增地址或訂閱等於開通一條資料外發的通道，所以修改配置只開放給 owner 和 admin，其中改變“資料發到哪裡、發哪些資料”的操作還要重新驗證身份：
| 操作 | owner | admin | developer | 重新驗證身份 |
|---|---|---|---|---|
| 檢視回撥地址、同步回撥的設定、事件目錄、投遞佇列、請求記錄和統計 | ✓ | ✓ | ✓ | |
| URL 驗證、測試傳送、測試同步回撥 | ✓ | ✓ | ✓ | |
| 暫停和恢復地址，重新投遞 | ✓ | ✓ | ✓ | |
| 修改地址的名稱、合併、超時、併發和速率，減少訂閱的事件、收緊過濾條件 | ✓ | ✓ | ||
| 提前結束舊金鑰的寬限期 | ✓ | ✓ | ||
| 新建和刪除地址，修改 URL，增加訂閱的事件，放寬過濾條件 | ✓ | ✓ | ✓ | |
| 輪換籤名金鑰 | ✓ | ✓ | ✓ | |
| 開啟、關閉和設定同步回撥 | ✓ | ✓ | ✓ |
developer 看不到“新建地址”“修改”“刪除”“輪換”和同步回撥的“設定”按鈕。全部寫操作都記入操作日誌，日誌中不記錄簽名金鑰和事件內容。租戶被暫停或處於登出冷靜期時，“回撥”頁只能檢視，不能修改，也不能驗證、測試和重新投遞。
新建回撥地址
在“回撥地址”中點選右上角的“新建地址”（每個應用最多 5 個地址，滿 5 個時按鈕不可用），填寫：
| 欄位 | 說明 |
|---|---|
| 名稱 | 1 到 64 個字元，如“業務系統”“訊息歸檔” |
| URL | 接收回撥的地址，只允許 https 和公網域名，埠為 443 或 1024 到 65535，規則見地址的要求 |
| 訂閱的事件 | 至少選擇一種。按類別分組，每組的第一項“類別.*”訂閱這一類的全部事件（包括以後新增的），見訂閱事件 |
| 不回撥服務端發起的操作 | 開啟後，你的服務端透過 OpenAPI 和你在控制檯的操作引起的事件不再傳送，撤回訊息除外，見過濾條件 |
| 刪除使用者時不回撥連帶的變化 | 開啟後，刪除使用者連帶解除的好友關係和退出的群不再逐條傳送 |
| 訊息的會話型別 | 訊息事件接收單聊、群聊，還是都接收 |
| 接收群提示訊息 | 訊息抄送是否包括群提示，預設不包括 |
| 每批事件數 | 1 到 100，預設 1。大於 1 時一次請求合併多個事件，適合訊息抄送等量大的事件 |
| 超時（毫秒） | 1000 到 10000，預設 5000 |
| 最大併發 | 1 到 50，預設 10 |
| 每秒請求數 | 1 到 1000，預設 100，不能超過應用的上限（輸入框下方顯示，預設 500，全部地址合計） |
點選“儲存”，按提示重新驗證身份。儲存成功後：
- 彈出對話方塊顯示這個地址的簽名金鑰（
cbs_開頭），只顯示這一次，請複製儲存到接收端的配置中，然後點選“我已儲存金鑰”。忘記儲存時可以輪換金鑰； - 系統立即向 URL 傳送一次 URL 驗證，對話方塊中顯示驗證的結果。透過後地址的狀態為“正常”，開始投遞事件；沒有透過的為“待驗證”，不投遞事件。
URL 驗證和測試傳送每個應用合計每分鐘最多 20 次。額度用完時地址照常儲存為“待驗證”，對話方塊提示稍後在列表中點選“驗證”。
先調通簽名，再驗證
接收端還沒有準備好時也可以先儲存地址：用“測試”傳送一個事件，對照結果中的請求體調通簽名校驗，再點選“驗證”。簽名的校驗方法和示例程式碼見驗證回撥請求。
回撥地址列表
| 列 | 說明 |
|---|---|
| 名稱 | 點選開啟地址詳情 |
| URL | 查詢引數的值顯示為 ***，見下文 |
| 訂閱 | 訂閱的事件數，滑鼠懸停顯示全部 |
| 狀態 | 待驗證、正常、已暫停、自動停用、平臺停用，含義見地址的狀態；滑鼠懸停顯示停用的原因。有同步回撥繫結這個地址時另顯示“同步回撥”標籤 |
| 健康 | “正常”，或“自 … 起失敗”（滑鼠懸停顯示最近的錯誤和失敗時間）；熔斷中、積壓的條數 |
| 操作 | 修改、驗證、測試、暫停或恢復、刪除 |
列表上方顯示應用全部地址合計的每秒請求數上限，以及回撥請求的出口 IP（平臺配置了時），可以把這些 IP 加入接收端的防火牆白名單。
驗證
點選“驗證”，系統向地址傳送一次 URL 驗證，顯示結果：成功或失敗、失敗的原因（如“連線失敗”“非 2xx 狀態碼”“challenge 不正確”）、HTTP 狀態碼、耗時、對方的 IP 和響應的開頭部分。“待驗證”的地址驗證透過後變為“正常”；其他狀態的地址驗證不改變狀態，只用於檢查接收端是否可用。
測試傳送
點選“測試”，選擇一種事件型別（不要求已訂閱），系統用事件目錄中的示例資料構造一個事件（test 為 true）立即傳送，不寫入投遞佇列。結果中除了驗證結果中的各項，還有本次發出的完整請求體，便於除錯簽名。測試不要求地址已經透過驗證，被平臺停用的地址除外。
修改地址
點選“修改”，修改各項設定後儲存。URL 留空表示不修改：列表中顯示的 URL 已經把查詢引數的值替換為 ***，修改 URL 時請填寫完整的新 URL（查詢引數的值為 *** 時不能儲存）。
- 需要重新驗證身份：修改 URL、增加訂閱的事件（把
group.*換成group.created不算增加，反過來算），或放寬過濾條件（關閉“不回撥服務端發起的操作”“刪除使用者時不回撥連帶的變化”，開啟“接收群提示訊息”，增加訊息的會話型別）時。其他修改不需要。 - 修改 URL 後：地址回到“待驗證”，系統立即對新的 URL 傳送一次驗證，顯示結果；驗證透過之前不投遞事件，繫結在這個地址上的同步回撥也按失敗處理（失敗策略為“拒絕”的會拒絕相應的操作）。請先把同步回撥改綁到其他地址，或暫時改為“放行”。
- 修改訂閱和過濾條件隻影響之後的事件，已經排隊的照常傳送。
- 兩個人同時修改同一個地址時，後儲存的會提示資料已被修改，重新整理後重新修改即可。
暫停與恢復
接收端停機維護時，可以點選“暫停”：事件照常排隊、不傳送，恢復後繼續傳送。每個事件從排隊起 24 小時仍未發出的轉為投遞失敗（從排隊時起算，不是從暫停時起算），可以在 7 天內重新投遞。暫停不影響同步回撥。
點選“恢復”：
- “已暫停”的地址直接恢復為“正常”；
- “自動停用”的地址（持續失敗 24 小時後被系統停用，見持續失敗與自動停用）先傳送一次 URL 驗證，透過後恢復為“正常”，沒有透過時保持停用並顯示驗證的結果。恢復後，再批次重新投遞停用前投遞失敗的事件；停用期間發生的事件沒有排隊，不會補發。
“待驗證”的地址不能恢復，請點選“驗證”。
刪除地址
owner 和 admin 點選“刪除”並確認（需要重新驗證身份）。刪除後立即停止投遞，繫結這個地址的同步回撥同時關閉，排隊中的事件和請求記錄隨後刪除，不能恢復。
被平臺停用的地址
地址被平臺停用時（通常是地址指向了不屬於你的第三方），狀態為“平臺停用”，詳情頂部顯示停用的原因。停用期間不投遞事件，繫結它的同步回撥按失敗處理；你不能修改它的 URL、刪除、驗證、測試和重新投遞，它仍計入 5 個地址的上限。如有異議請聯絡我們，由平臺恢復。
地址詳情
點選地址的名稱開啟詳情，頂部是地址的設定和健康狀況：
| 專案 | 說明 |
|---|---|
| 狀態、地址 ID | 地址 ID 即請求頭 X-IM-Endpoint-Id |
| 每批 / 超時、併發 / 每秒 | 當前的設定；平臺調低了應用的上限時，實際生效的每秒請求數會更小，並註明“受應用上限限制” |
| 最近成功、最近失敗 | 最近一次事件回撥成功、失敗的時間和失敗的原因 |
| 持續失敗 | 從最近一次成功之後開始失敗的時間；持續 1 小時會通知 owner 和 admin，持續 24 小時自動停用 |
| 積壓 | 待投遞的事件數和上限（預設 50 萬），以及最早一條的排隊時間，每 30 秒左右統計一次 |
| 熔斷 | 正常、熔斷中、試探中，見重試 |
| 驗證時間 | 最近一次透過 URL 驗證的時間 |
| 簽名金鑰 | 當前金鑰的版本和前 8 個字元，見下文 |
下方有四個標籤頁：投遞佇列、請求記錄、統計、批次重新投遞。
簽名金鑰
詳情中只顯示金鑰的前 8 個字元（如 cbs_Le8E…），用於辨認，完整的金鑰只在新建地址和輪換時顯示一次。
- 輪換：
owner和admin點選“輪換”，填寫舊金鑰的寬限期（1 到 168 小時，預設 24 小時），確認並重新驗證身份後，對話方塊顯示新金鑰（只顯示這一次）。新金鑰立即生效；寬限期內每個請求同時帶新舊兩個簽名，接收端用哪一個都能校驗透過，詳情中顯示“舊金鑰 … 的寬限期至 …”。寬限期還沒結束時不能再次輪換。 - 提前結束寬限期：接收端都換成新金鑰後，點選“提前結束寬限期”，之後只用新金鑰簽名，還在用舊金鑰的接收端會校驗失敗。不需要重新驗證身份。
不停機更換金鑰的步驟見輪換金鑰。金鑰不會自動過期。
投遞佇列
按狀態檢視這個地址的投遞：
| 狀態 | 內容 |
|---|---|
| 待投遞 | 正在排隊或等待重試的事件，按下次傳送的時間排列 |
| 失敗（預設顯示） | 24 小時內沒有投遞成功的事件，保留 7 天，可以重新投遞 |
| 已投遞 | 投遞成功的事件，保留 1 小時 |
可以按事件型別篩選，或在“按事件 ID 查詢”中輸入事件 ID（如接收端日誌中的 events[].id）查詢這個事件對這個地址的投遞。列表顯示事件型別、事件 ID、狀態、傳送次數、最近的錯誤和狀態碼、下次傳送或完成的時間、排隊時間。
- 詳情：檢視事件的發生時間、傳送次數、最近一次請求的 ID 和事件的
data。訊息類事件（訊息抄送、訊息編輯、聊天室的訊息抄送）不顯示body和ext；投遞成功後不保留內容。 - 重新投遞：失敗的事件可以點選“重新投遞”，事件回到待投遞，傳送次數清零，24 小時的期限重新計算。地址必須是“正常”或“已暫停”（暫停時排隊，恢復後傳送）。
請求記錄
每次向這個地址發出的請求，保留 7 天，可以按結果（成功、失敗）和型別（事件、同步回撥、URL 驗證、測試）篩選：
| 列 | 說明 |
|---|---|
| 時間、型別 | 重新投遞的請求另有“重新投遞”標籤 |
| 名稱 | 事件型別或同步回撥的型別；合併傳送的註明事件數 |
| 第幾次 | 事件的第幾次傳送 |
| 結果 | 成功（同步回撥另顯示結果，如 allow、reject、modify、fallback_allow），或失敗的原因 |
| HTTP、耗時、對方 IP | 對方返回的狀態碼、請求的耗時和實際連線的 IP |
展開一行可以看到請求 ID（即請求頭 X-IM-Request-Id）、包含的事件 ID、錯誤的說明、對方響應的開頭部分和請求體的大小。請求記錄不儲存事件的內容。URL 驗證、測試、重新投遞和失敗的請求基本全部記錄，成功的請求按抽樣記錄，完整的數量見統計。
失敗的原因：
| 原因 | 說明 |
|---|---|
| 域名解析失敗 | URL 中的域名無法解析 |
| 解析到了非公網地址或被出口代理拒絕 | 實際要連線的 IP 不是公網地址，連線前已拒絕 |
| 連線失敗 | 連線被拒絕、不可達或連線超時 |
| TLS 握手失敗 | 證書無效、過期或與域名不符 |
| 超時 | 在超時時間之內沒有讀完響應 |
| 非 2xx 狀態碼 | 對方返回了 4xx、5xx 等，括號中為狀態碼 |
| 返回了跳轉（不跟隨） | 對方返回了 3xx |
| 響應過大 | 同步回撥、URL 驗證的響應超過上限 |
| 響應無效 | 同步回撥返回了 2xx，但響應體不符合要求，見同步回撥的響應 |
| challenge 不正確 | URL 驗證的響應中沒有正確的 challenge |
統計
最近 24 小時或 7 天的統計，保留 90 天：
- 按事件型別：每種事件的排隊數、投遞成功數、失敗數、丟棄數（積壓達到上限，或線上狀態、聊天室的事件因緩衝已滿被丟棄）、跳過數（地址不是正常或暫停狀態，或應用不可用時沒有生成投遞）；
- 按小時：請求數、失敗數、超時數、熔斷時跳過的次數、平均和最大耗時、投遞成功的事件數、事件從發生到投遞成功的平均和最大延遲。
批次重新投遞
接收端故障修復後，可以按失敗的時間批次重新投遞：選擇失敗時間的範圍（相差不超過 7 天），可以只選幾種事件型別，點選“重新投遞”。每次最多處理 1 萬個事件，提示“還有更多”時再提交一次。地址必須是“正常”或“已暫停”，“自動停用”的地址請先恢復。
同步回撥
“同步回撥”中列出四種同步回撥，說明見同步回撥：
| 列 | 說明 |
|---|---|
| 同步回撥 | 發訊息前（message.before_send）、發聊天室訊息前（chatroom.before_send）、加好友前（friend.before_add）、加群前（group.before_join） |
| 狀態 | 已開啟或未開啟。開啟了、但繫結的地址處於“待驗證”或“平臺停用”時另顯示“地址不可用”：這時不發請求，按失敗策略處理，失敗策略為“拒絕”的會拒絕全部相應的操作 |
| 繫結地址 | 呼叫的回撥地址 |
| 等待 | 等待響應的時間 |
| 失敗時 | 放行或拒絕 |
| 操作 | 設定、測試、統計 |
設定同步回撥
owner 和 admin 點選“設定”，儲存時需要重新驗證身份：
| 欄位 | 說明 |
|---|---|
| 開啟 | 開啟或關閉這種同步回撥。關閉時保留其他設定 |
| 呼叫的地址 | 開啟時必須選擇。“待驗證”和“平臺停用”的地址不能選擇 |
| 等待時間（毫秒） | 100 到 3000，預設 1000。實際等待的時間不超過操作方剩餘的時間：訊息的全部傳送前檢查合計 3 秒，聊天室訊息合計 500 毫秒 |
| 超時、出錯或響應無效時 | 放行（預設）或拒絕，見失敗時的處理 |
| 呼叫條件 | 因型別而不同：發訊息前為傳送入口、會話型別、訊息型別、是否包括只推線上的訊息、是否包括編輯；發聊天室訊息前為傳送入口、訊息型別、優先順序；加好友前為階段（傳送申請、同意申請）；加群前為入群方式和群型別。不滿足條件的操作直接放行。各項見同步回撥 |
儲存後通常 1 秒內生效。開啟“失敗時拒絕”之前，請確認接收端穩定：接收端故障時，全應用的相應操作都會失敗。
測試和統計
- 測試：用示例資料向繫結的地址傳送一次同步回撥請求（不要求地址已透過驗證），顯示是否成功、你的服務端的決定（如
allow），或響應無效的原因。沒有繫結地址時不能測試。 - 統計：最近 24 小時每小時的呼叫次數，放行、拒絕、改寫和失敗的次數，超時、時間不足、熔斷、地址不可用而沒有發出請求的次數，失敗後按策略放行和拒絕的次數，以及平均耗時。
事件目錄
“事件目錄”列出全部可以訂閱的事件型別、所屬類別和說明，可以按類別篩選，展開一行檢視 data 的示例，即測試傳送時使用的資料。各事件的欄位說明見事件回撥。
訂閱獨立頻道事件
頻道事件在音影片類別中，型別以 rtc_channel. 開頭，完整列表見頻道事件。選擇 rtc_channel.* 訂閱全部 9 種頻道事件；通話的 rtc.* 不包含它們。配置變化的內部通知不會作為回撥發給你。增加訂閱同樣要按本頁的規則重新驗證身份，接收端要能處理重複和亂序到達的事件。