線上狀態

從你的服務端查詢使用者是否線上，例如使用者不線上時改用簡訊、郵件通知他。

curl -X POST "$IM_API/$ORG/$APP/presence/query" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "usernames": ["alice", "bob"] }'

使用者至少有一臺裝置與服務端保持著長連線就是線上（客戶端 SDK 登入後會建立並保持長連線；只登入、沒建立長連線的裝置不算）。返回的線上狀態包括：

內容	欄位
是否線上	online
線上的平臺，取值同登入時上報的平臺（ios、android、harmony、web、windows、macos、linux、mini_program、other）	platforms
最近一次離線的時間，離線時才有	last_seen_at

需要實時得知上線、下線，可以訂閱事件回撥 presence.changed。它是盡力而為的事件，可能丟失，關鍵判斷請以本頁介面的查詢結果為準。

• 後臺也算線上：移動端 App 切到後臺後，只要連線還在，仍算線上。本頁介面不區分前臺和後臺。
• 離線的判定有延遲：使用者正常退出或關閉連線時立即變為離線；裝置異常斷網時，服務端在連線空閒超時後才發現（預設前臺 90 秒、後臺 360 秒），這段時間內仍顯示線上。網路切換時新連線會替換舊連線，不會出現“先離線再上線”。
• 資料保留：最近離線時間保留 30 天，30 天內沒有上線過的使用者 last_seen_at 為 null、version 為 0。

與應用執行策略的關係

執行策略中與線上狀態有關的設定只限制客戶端（使用者之間）檢視線上狀態，對本頁的介面都不生效，服務端總能查詢任意使用者、看到最近離線時間：

策略	預設值	對客戶端的作用
presence_enabled	關閉	開啟後，客戶端才能查詢和訂閱其他使用者的線上狀態
presence_scope	friends	客戶端能看到誰的線上狀態：friends 只能看好友的，all 可以看應用內任何使用者的
presence_last_seen_visible	開啟	關閉後，客戶端只能看到對方是否線上，看不到最近離線時間

設定方法見執行策略。

批次查詢線上狀態

一次查詢最多 100 個使用者的線上狀態。無論查詢多少個使用者，都只計一次呼叫。

POST/{org_name}/{app_name}/presence/query

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
usernames	Array<String>	是	要查詢的使用者名稱，1 到 100 個。不區分大小寫，重複的只返回一次

請求示例

curl -X POST "$IM_API/$ORG/$APP/presence/query" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["alice", "bob", "carol", "nobody"]
  }'

響應

成功返回 200 OK，items 中每一項為線上狀態物件，順序與請求中的一致；不存在或已刪除的使用者不出現在結果中。

{
  "items": [
    {
      "username": "alice",
      "online": true,
      "platforms": ["ios", "windows"],
      "last_seen_at": null,
      "version": 1790968803807
    },
    {
      "username": "bob",
      "online": false,
      "platforms": [],
      "last_seen_at": "2026-10-02T19:12:04.903Z",
      "version": 1790968324903
    },
    {
      "username": "carol",
      "online": false,
      "platforms": [],
      "last_seen_at": null,
      "version": 0
    }
  ]
}

示例中 alice 在 iOS 和 Windows 上都線上，bob 已離線，carol 從未上線過。

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	usernames 為空或超過 100 個，details.field 為 usernames
500	internal	details.reason 為 dependency_unavailable：線上狀態服務暫時不可用，按 Retry-After 響應頭等待後重試

查詢使用者的線上狀態

查詢單個使用者的線上狀態。

GET/{org_name}/{app_name}/users/{username}/presence

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	使用者名稱，不區分大小寫

請求示例

curl "$IM_API/$ORG/$APP/users/alice/presence" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為線上狀態物件。

{
  "username": "alice",
  "online": true,
  "platforms": ["ios", "windows"],
  "last_seen_at": null,
  "version": 1790968803807
}

這個介面只返回線上的平臺，不返回每臺裝置的資訊。使用者登入了哪些裝置見查詢登入裝置（登入不等於線上）；每條長連線的平臺、前後臺狀態、IP 地址和連線時間，可以在控制檯的使用者詳情中檢視。

錯誤

HTTP 狀態碼	code	說明
404	not_found	使用者不存在或已刪除
500	internal	details.reason 為 dependency_unavailable：線上狀態服務暫時不可用，按 Retry-After 響應頭等待後重試

資料結構

線上狀態物件

欄位	型別	說明
username	String	使用者名稱
online	Boolean	是否線上：至少有一臺裝置保持著長連線（包括在後臺的裝置）
platforms	Array<String>	線上的平臺，按字母排序，同一平臺有多臺裝置線上時只出現一次；離線時為空陣列
last_seen_at	String	最近一次變為離線的時間。線上時為 null；30 天內沒有上線過的使用者也為 null
version	Number	線上狀態的版本號，每次變化（上線、離線、線上的平臺增減）都會變大，可以用來判斷兩次查詢之間是否有變化、丟棄較舊的結果。從未上線過或 30 天沒有變化的使用者為 0

{
  "username": "bob",
  "online": false,
  "platforms": [],
  "last_seen_at": "2026-10-02T19:12:04.903Z",
  "version": 1790968324903
}