接入概述

服務端 REST API（OpenAPI）供你的業務服務端呼叫，用來管理使用者、好友、群組和聊天室，傳送和查詢訊息，上傳和管理檔案，查詢線上狀態和通話等。本頁說明所有介面共用的約定，閱讀具體介面前請先了解。

使用服務端 SDK

Go、Python 和 Node.js 可以直接使用服務端 SDK，它替你管理 App Token、重試、分頁和回撥校驗。

請求地址

所有介面的地址都由三部分組成：

text

https://{host}/{org_name}/{app_name}/{接口路径}

部分	說明
`host`	服務的接入域名，開通服務時提供；私有化部署時為你部署的服務地址
`org_name`	租戶的唯一標識，註冊時由系統生成，不能修改
`app_name`	應用名稱，建立應用時填寫，租戶內唯一，不能修改

org_name 和 app_name 用 # 連起來就是應用的 AppKey，例如 1100250925#demo，客戶端登入時使用它。

文件中的請求示例使用以下環境變數，複製到終端前先設定好：

bash

export IM_API="https://api.example.com"    # 接入地址，不带末尾的斜杠
export ORG="1100250925"                    # org_name
export APP="demo"                          # app_name
export APP_TOKEN="<App Token>"             # 见《鉴权与 App Token》

第一個請求

從換取 App Token 到發出第一條訊息。$CLIENT_ID、$CLIENT_SECRET 在控制檯概覽的“接入憑證”中檢視：

bash

# 1. 用应用的凭据换取 App Token。默认 7 天有效，请缓存复用，不要每次调用前都换取
export APP_TOKEN=$(curl -s -X POST "$IM_API/$ORG/$APP/token" \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}" \
  | jq -r .access_token)

# 2. 创建两个用户
curl -X POST "$IM_API/$ORG/$APP/users" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "username": "alice" }'
curl -X POST "$IM_API/$ORG/$APP/users" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "username": "bob" }'

# 3. 以 alice 的身份给 bob 发一条文本消息
curl -X POST "$IM_API/$ORG/$APP/messages" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{ "from": "alice", "to_user": "bob", "client_msg_id": "first-msg-001", "type": "text", "body": { "text": "你好" } }'

接下來按業務需要檢視介面一覽。下面幾節是所有介面共用的約定。

請求頭

請求頭	說明
`Authorization`	`Bearer <App Token>`，換取 App Token 的介面除外，見鑑權與 App Token
`Content-Type`	有請求體時必須為 `application/json`
`X-Request-ID`	可選。你為這次請求生成的唯一標識，最長 64 個字元，只能包含字母、數字和 `-`、`_`、`.`；不傳時由服務端生成。響應頭中總會返回 `X-Request-ID`，排查問題時請提供它

資料格式

JSON：請求體和響應體都是 JSON，欄位名使用小寫加下劃線（如 created_at）。請求體必須是一個 JSON 物件，最大 1 MiB。請求中出現介面不認識的欄位、欄位型別不對，都返回 400 invalid_argument，便於儘早發現拼寫錯誤。
ID 是字串：所有 ID（如 message_id、group_id、app_id）都以字串返回，請求中也傳字串。ID 是 64 位整數，超出 JavaScript 能精確表示的範圍，按數字處理會丟失精度。
時間：以 UTC 時間的 RFC 3339 格式返回，精確到毫秒，如 2026-09-25T08:30:00.000Z，請按使用者所在時區顯示。表示時長的欄位以秒為單位，欄位名以 _seconds 結尾。
使用者標識：介面中一律用使用者名稱（username）表示使用者。使用者名稱不區分大小寫，服務端統一轉為小寫，響應中的使用者名稱都是小寫。
空值：可選欄位沒有值時一般返回 null，而不是省略欄位；個別響應（如批次操作中每一項的結果）只包含有值的欄位，以介面文件為準。
快取：介面的響應都是實時資料，請不要在中間層快取。

響應與狀態碼

成功時返回 2xx 狀態碼：

狀態碼	含義
`200 OK`	成功，響應體為結果
`201 Created`	建立成功，響應體為建立的物件
`204 No Content`	成功，沒有響應體（如刪除）

失敗時返回 4xx 或 5xx 狀態碼和統一的錯誤結構，程式請根據 code 判斷錯誤型別，message 只用於展示和記錄：

json

{
  "error": {
    "code": "not_found",
    "message": "用户不存在",
    "request_id": "QHDK7PQXPV3LFKEFLF37DST5RR"
  }
}

部分錯誤另帶 details 物件說明具體原因。全部錯誤碼見錯誤碼。

分頁

列表介面使用遊標分頁：

引數	位置	說明
`limit`	查詢引數	每頁條數，預設 20，取值 1 到 100（個別介面另有說明）
`cursor`	查詢引數	下一頁的遊標，第一頁不傳

響應中 items 為本頁資料，next_cursor 為下一頁的遊標，沒有下一頁時為 null。個別介面（如查詢通話列表、查詢會話免打擾）沒有下一頁時返回空字串 ""，請統一以 next_cursor 為 null 或空字串判斷沒有下一頁：

json

{
  "items": [{ "username": "alice" }],
  "next_cursor": "40c8blUXcfK_XCDGHVSvyWRqlgXc27iUTSJmxGuuazqyS9K3..."
}

遊標由服務端生成，請原樣傳回，不要解析或拼接。遊標只在同一種查詢中有效：改變篩選條件後請從第一頁開始。數量有限的列表（如使用者的登入裝置）不分頁，只返回 items。

部分介面按自己的方式翻頁（如按訊息序號翻頁的歷史訊息），以介面文件為準。

併發修改與 version

可修改的物件帶有版本號（如使用者的 version、群組的 info_version），每次修改加一。修改時可以在請求中帶上讀取到的版本號 version：

帶 version 時，只有版本號一致才會修改，否則返回 409 version_conflict，說明資料已被其他請求修改，請重新讀取後再決定是否修改；
不帶 version 時直接覆蓋（個別介面要求必須帶，以介面文件為準）。

只修改請求中出現的欄位，沒有出現的欄位保持不變。

批次介面

批次介面（如批次建立使用者、批次新增好友、批次傳送訊息）一次最多處理 100 項（個別介面另有說明）。各項分別處理、互不影響：部分失敗時整體仍返回 200 OK，響應中列出每一項的結果，失敗的項帶錯誤碼和說明。響應的具體格式以各介面的文件為準，例如批次建立使用者分別列出成功和失敗的項：

json

{
  "created": [{ "username": "bob", "status": "active" }],
  "failed": [{ "username": "alice", "code": "already_exists", "message": "用户名已被占用" }]
}

批次介面按項數計入呼叫額度，見限流與應用狀態。

重試與冪等

網路超時後，你無法確定上一次請求是否已經成功。重試前請了解介面的冪等性，各介面的文件會寫明重複呼叫的結果，常見規則：

建立：用唯一的名稱或 ID 防止重複，重複提交返回 409 already_exists，可視為上次已成功；
刪除：重複刪除時，不同介面返回 404 not_found、204 No Content，或 200 OK 且 changed 為 false（如刪除好友、移出黑名單），以介面文件為準，都可視為上次已成功；
設定狀態（如封禁、禁言、加入黑名單）：重複呼叫的結果相同；
傳送訊息：帶上你生成的 client_msg_id，重試時返回第一次寫入的訊息，不會重複傳送，見傳送訊息。

對 429 rate_limited 請按 Retry-After 響應頭等待後重試；對 5xx 和網路錯誤請用指數退避重試。

介面一覽

分類	內容
使用者	建立、查詢、修改、刪除使用者，密碼與封禁，登入憑證與登入裝置，全域性禁言
好友與黑名單	好友關係、好友申請、黑名單、加好友方式
群組	群的建立與管理、群成員、群黑名單、入群申請與邀請
訊息	傳送單聊和群聊訊息，查詢與匯出，撤回、編輯與置頂
會話	會話列表、歷史訊息、未讀數與已讀、刪除會話
檔案	上傳訊息附件、頭像和群檔案，換取下載地址，查詢和刪除檔案，群檔案列表，儲存用量
聊天室	聊天室的建立、查詢、修改與解散，聊天室屬性，線上成員、禁言、封禁和白名單，傳送、查詢和撤回聊天室訊息
音影片	查詢通話、結束通話和移出成員、通話統計
離線推送	使用者的推送設定、會話免打擾和推送裝置
內容安全	稽核配置與詞庫、稽核記錄與結論、使用者違規與統計、代使用者舉報
線上狀態	查詢使用者是否線上、在哪些平臺線上，最近線上時間
AI 對話	AI 機器人的管理；以機器人的身份流式寫入回覆，對接你自己的大模型
事件回撥	回撥概述、驗證回撥請求、事件回撥、同步回撥

獨立 RTC 頻道約定

獨立 RTC 頻道的介面分兩部分：

	你的服務端管理頻道	客戶端參會
路徑	`/{org_name}/{app_name}/rtc/channels/…`	`/client/v1/rtc/…`
令牌	App Token	使用者自己的 User Token
文件	頻道管理	客戶端頻道會話

你的服務端不能替客戶端領取媒體憑據。另外幾條約定：

channel_id 由你指定，區分大小寫；會話 ID 和毫秒累計值都按字串儲存。
頻道資料、票據、成員和媒體授權的響應都不允許快取（no-store），票據只放在 HTTPS 的 JSON 請求體中。
重試時保持同一個鍵：建立頻道用同一個頻道 ID，移出和撤銷票據用同一個 operation_id，客戶端加入用同一個 client_session_id。同一個鍵不能換引數或換使用者使用。
簽發票據不是冪等的，不要自動重試；響應丟失不代表沒有簽發。
關閉頻道、退出返回 202 時表示還在非同步清理。

語言協商

請求頭帶 Accept-Language: en 或 Accept-Language: zh-TW 時，錯誤的 message 按英語或繁體中文返回。相關響應帶 Content-Language 和 Vary: Accept-Language，錯誤物件還可能帶 message_key、message_params，見可選文案後設資料。

語言隻影響給人看的文字，code、details、介面路徑和許可權都不變，所以不要解析 message 判斷業務。完整規則、賬號的語言偏好和 SDK 的文案目錄見語言與本地化。

接入概述 ​

請求地址 ​

第一個請求 ​

請求頭 ​

資料格式 ​

響應與狀態碼 ​

分頁 ​

併發修改與 version ​

批次介面 ​

重試與冪等 ​

介面一覽 ​

獨立 RTC 頻道約定 ​

語言協商 ​

接入概述

請求地址

第一個請求

請求頭

資料格式

響應與狀態碼

分頁

併發修改與 version

批次介面

重試與冪等

介面一覽

獨立 RTC 頻道約定

語言協商