推送裝置與設定

從你的服務端檢視和修改使用者的推送設定和會話免打擾，或排查使用者的推送裝置。免打擾和預覽方式的效果見離線推送。

要做什麼	介面
和你 App 裡的“勿擾模式”“通知只顯示傳送者”開關同步	修改推送設定
和你 App 裡某個群的“訊息免打擾”同步	設定會話免打擾、取消會話免打擾
排查使用者收不到推送	查詢推送裝置，再看排查收不到推送
換了賬號的手機還收到前一個賬號的推送	解綁推送裝置

例如，替 alice 開啟 8 小時的勿擾：

bash

curl -X PATCH "$IM_API/$ORG/$APP/users/alice/push-settings" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "dnd": { "duration_seconds": 28800 } }'

與客戶端共用一份設定：使用者在客戶端修改的也是同一份設定，雙方的修改互相覆蓋，以最後一次為準。
修改後通知使用者的裝置：推送設定或會話免打擾有變化時，使用者全部線上的裝置收到 push.settings_changed 通知，客戶端據此更新本地的設定。沒有變化的修改（changed 為 false）不通知。
版本號：推送設定和會話免打擾共用一個版本號 settings_version，任何一項有變化都加一，客戶端用它判斷本地的設定是否最新。
使用者的狀態：使用者不存在或已刪除時，各介面返回 404 not_found；刪除使用者時，他的推送設定、會話免打擾和推送裝置一併刪除。被封禁的使用者的設定保留，但他的推送裝置隨登入一起失效。
本頁的介面只計入應用的 OpenAPI 呼叫額度，應用處於只讀狀態時都可以呼叫。

查詢推送設定

GET/{org_name}/{app_name}/users/{username}/push-settings

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱

請求示例

bash

curl "$IM_API/$ORG/$APP/users/zhangsan/push-settings" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，響應體為推送設定物件。使用者從未設定過時：

json

{
  "dnd": null,
  "quiet_hours": null,
  "preview": null,
  "effective_preview": "full",
  "settings_version": 0
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	使用者不存在或已刪除

修改推送設定

修改使用者的全域性免打擾、夜間免打擾和預覽方式，只給出要修改的欄位，沒有給出的保持不變。

設定與當前相同時不算修改，changed 為 false，版本號不變。全域性免打擾以相同的時長再開啟一次（到期時間相差不超過 1 分鐘），同樣不算修改，到期時間不變。
全域性免打擾的時長從本次呼叫時開始計算，到期後自動關閉，使用者的裝置不會另外收到通知。

PATCH/{org_name}/{app_name}/users/{username}/push-settings

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱

請求體

欄位	型別	必填	說明
`dnd`	Object	否	全域性免打擾。`null` 關閉；`{ "duration_seconds": 28800 }` 開啟一段時間，時長為 1 到 315360000 秒（10 年）；`{ "duration_seconds": null }` 或 `{}` 一直開啟
`quiet_hours`	Object	否	夜間免打擾。`null` 關閉；或者為 `start`、`end`、`timezone` 三項，都必填：`start`、`end` 為開始和結束的時刻，格式為 `HH:MM`（24 小時制，兩位數，如 `07:30`），兩者不能相同，`end` 早於 `start` 表示跨過午夜；`timezone` 為 IANA 時區名稱，如 `Asia/Shanghai`，不接受 `GMT+8` 這類寫法
`preview`	String	否	預覽方式：`full` 顯示傳送者和內容，`sender_only` 只顯示傳送者，`none` 都不顯示；`null` 清除使用者的選擇，改用應用執行策略的 `push_default_preview`

請求示例

開啟 8 小時的全域性免打擾，設定每天 22:00 到次日 07:30 的夜間免打擾，通知只顯示傳送者：

bash

curl -X PATCH "$IM_API/$ORG/$APP/users/zhangsan/push-settings" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dnd": { "duration_seconds": 28800 },
    "quiet_hours": { "start": "22:00", "end": "07:30", "timezone": "Asia/Shanghai" },
    "preview": "sender_only"
  }'

響應

成功返回 200 OK，響應體為修改後的推送設定物件，另加 changed 欄位，表示這次是否有變化。

json

{
  "dnd": { "until": "2026-10-05T03:20:47.124Z" },
  "quiet_hours": { "start": "22:00", "end": "07:30", "timezone": "Asia/Shanghai" },
  "preview": "sender_only",
  "effective_preview": "sender_only",
  "settings_version": 1,
  "changed": true
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.reason` 為 `invalid_duration`：時長不在 1 到 315360000 秒之間
400	`invalid_argument`	`details.reason` 為 `invalid_quiet_hours`：時刻的格式不對，或開始等於結束
400	`invalid_argument`	`details.reason` 為 `invalid_timezone`：時區不是 IANA 時區名稱
400	`invalid_argument`	`details.reason` 為 `invalid_preview`：預覽方式不是 `full`、`sender_only`、`none`
400	`invalid_argument`	沒有 `details.reason`：請求體中有不認識的欄位，或 `dnd` 不是物件也不是 `null`，`details.field` 指出欄位
404	`not_found`	使用者不存在或已刪除

查詢會話免打擾

查詢使用者設定了免打擾的單聊和群。已經到期的、單聊對方已刪除的不返回，所以一頁的條數可能少於 limit，是否還有下一頁只看 next_cursor。

GET/{org_name}/{app_name}/users/{username}/push-settings/conversations

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁條數，1 到 500，預設 100
`cursor`	String	否	下一頁的遊標，取自上一頁的 `next_cursor`，第一頁不傳
`known_version`	Number	否	只用於第一頁：你儲存的 `settings_version`。與當前的版本號相同時，只返回 `not_modified` 為 `true` 和版本號，`items` 為空陣列

請求示例

bash

curl "$IM_API/$ORG/$APP/users/zhangsan/push-settings/conversations?limit=100" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`settings_version`	Number	當前的版本號，從未設定過為 0
`not_modified`	Boolean	第一頁帶的 `known_version` 與當前版本號相同時為 `true`
`items`	Array<Object>	會話免打擾，每項為會話免打擾物件，按會話型別（`group` 在前）和會話排序
`next_cursor`	String	下一頁的遊標，沒有下一頁時為空字串

json

{
  "settings_version": 4,
  "not_modified": false,
  "items": [
    {
      "conversation_type": "group",
      "target": "100311272729346048",
      "mode": "mention_only",
      "until": null,
      "updated_at": "2026-10-04T19:21:19.963Z"
    },
    {
      "conversation_type": "single",
      "target": "lisi",
      "mode": "none",
      "until": "2026-10-05T19:21:20.019Z",
      "updated_at": "2026-10-04T19:21:20.022Z"
    }
  ],
  "next_cursor": ""
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 不在 1 到 500 之間，`known_version` 不是非負整數，或 `cursor` 無效
404	`not_found`	使用者不存在或已刪除

設定會話免打擾

為使用者設定一個單聊或一個群的免打擾，已有設定的覆蓋為本次的方式和時長。以相同的方式和時長再設定一次（到期時間相差不超過 1 分鐘，或都一直有效），changed 為 false，到期時間不變。

設定群免打擾時使用者必須是群成員。使用者退出或被移出群后，這個群的免打擾隨之刪除，重新入群時從正常推送開始。

PUT/{org_name}/{app_name}/users/{username}/push-settings/conversations/single/{peer}

PUT/{org_name}/{app_name}/users/{username}/push-settings/conversations/group/{group_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱
`peer`	String	單聊的對方使用者名稱，不能是使用者本人
`group_id`	String	群 ID

請求體

欄位	型別	必填	說明
`mode`	String	是	免打擾方式：`none` 不推送這個會話的訊息；`mention_only` 只在有人 @ 本人時推送，只能用於群
`duration_seconds`	Number	否	時長，單位為秒，1 到 315360000（10 年），從本次呼叫時開始計算，到期後自動恢復正常推送。省略或為 `null` 表示一直有效

請求示例

群裡只在有人 @ 本人時推送：

bash

curl -X PUT "$IM_API/$ORG/$APP/users/zhangsan/push-settings/conversations/group/100311272729346048" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "mention_only"
  }'

與 lisi 的單聊 1 天內不推送：

bash

curl -X PUT "$IM_API/$ORG/$APP/users/zhangsan/push-settings/conversations/single/lisi" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "none",
    "duration_seconds": 86400
  }'

響應

成功返回 200 OK，響應體為設定後的會話免打擾物件，另加 changed（這次是否有變化）和 settings_version（設定後的版本號）。

json

{
  "conversation_type": "single",
  "target": "lisi",
  "mode": "none",
  "until": "2026-10-05T19:21:20.019Z",
  "updated_at": "2026-10-04T19:21:20.022Z",
  "changed": true,
  "settings_version": 4
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.reason` 為 `invalid_mode`：`mode` 缺失或取值不對，或單聊設定了 `mention_only`
400	`invalid_argument`	`details.reason` 為 `invalid_duration`：時長不在 1 到 315360000 秒之間
400	`invalid_argument`	`details.reason` 為 `self_conversation`：單聊的對方是使用者本人
403	`not_group_member`	使用者不是這個群的成員，或群已解散
404	`not_found`	使用者或單聊的對方不存在或已刪除；群不存在
409	`limit_exceeded`	`details.reason` 為 `conversation_setting_limit`：使用者的會話免打擾已有 10000 個

取消會話免打擾

取消使用者對一個單聊或一個群的免打擾，恢復正常推送。沒有設定過（或已經到期）時同樣返回成功，changed 為 false，可以放心重試。取消群免打擾時不檢查成員身份，群不存在或使用者已經不在群中也可以呼叫。

DELETE/{org_name}/{app_name}/users/{username}/push-settings/conversations/single/{peer}

DELETE/{org_name}/{app_name}/users/{username}/push-settings/conversations/group/{group_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱
`peer`	String	單聊的對方使用者名稱
`group_id`	String	群 ID

請求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/users/zhangsan/push-settings/conversations/single/lisi" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`changed`	Boolean	這次是否取消了一項有效的設定
`settings_version`	Number	取消後的版本號

json

{
  "changed": true,
  "settings_version": 5
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`details.reason` 為 `self_conversation`：單聊的對方是使用者本人
404	`not_found`	使用者或單聊的對方不存在或已刪除

查詢推送裝置

查詢使用者登記了推送的裝置和令牌，按 session_id 升序排列。每臺裝置對應使用者的一次登入，與查詢登入裝置返回的 session_id 相同；登入了但沒有登記推送的裝置（包括 Web 等不能登記的平臺、使用者關閉了通知的裝置）不在其中。裝置數受登入裝置數的上限約束，結果不分頁。

GET/{org_name}/{app_name}/users/{username}/push-devices

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱

請求示例

bash

curl "$IM_API/$ORG/$APP/users/zhangsan/push-devices" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK。items 為登記了推送的裝置，每項為推送裝置物件；沒有時為空陣列。

json

{
  "items": [
    {
      "session_id": "100310865395318784",
      "device_id": "5f0c2a9e-7d1b-4c7e-9a51-2f6d0f3b8c11",
      "platform": "ios",
      "language": "zh-Hans-CN",
      "tokens": [
        { "kind": "alert", "priority": 1, "credential": "ios-prod", "channel": "apns", "token": "6abf38…f665" },
        { "kind": "voip", "priority": 1, "credential": "ios-prod", "channel": "apns", "token": "13b7b7…32c0" }
      ],
      "badge": 6,
      "login_at": "2026-10-04T19:19:33.998Z",
      "updated_at": "2026-10-04T19:19:48.452Z"
    },
    {
      "session_id": "100310865730863104",
      "device_id": "a3d91c07-58e2-4f6b-b1c4-7e0f2d9a6c35",
      "platform": "android",
      "language": "zh-CN",
      "tokens": [
        { "kind": "alert", "priority": 1, "credential": "xiaomi-main", "channel": "xiaomi", "token": "Lx9Qw2…Kd3P" },
        { "kind": "alert", "priority": 2, "credential": "fcm-global", "channel": "fcm", "token": "cR5tY8…nM0q" }
      ],
      "badge": 0,
      "login_at": "2026-10-04T19:19:34.079Z",
      "updated_at": "2026-10-04T19:27:20.056Z"
    }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	使用者不存在或已刪除

解綁推送裝置

刪除使用者一臺裝置的推送登記，這臺裝置隨即收不到這個使用者的離線推送。

只解綁推送，不影響登入：裝置不會下線，App 下次啟動或重新登記時又會恢復推送。要讓裝置徹底不再收到推送，請踢掉這臺裝置，或封禁使用者。
裝置沒有登記推送（包括已經解綁過）時返回 404 not_found，重試時可以把它當作成功。
使用者的裝置不會收到解綁的通知。

DELETE/{org_name}/{app_name}/users/{username}/push-devices/{session_id}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`username`	String	使用者名稱
`session_id`	String	裝置的會話 ID，取自查詢推送裝置的 `session_id`

請求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/users/zhangsan/push-devices/100310865730863104" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 204 No Content，沒有響應體。

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	使用者不存在或已刪除；這臺裝置沒有登記推送、已經解綁，或者不屬於這個使用者

資料結構

推送設定物件

欄位	型別	說明
`dnd`	Object	全域性免打擾，沒有開啟或已經到期時為 `null`。`until` 為到期時間，為 `null` 表示一直開啟
`quiet_hours`	Object	夜間免打擾，沒有設定時為 `null`。`start`、`end` 為開始和結束的時刻（`HH:MM`，24 小時制），`end` 早於 `start` 表示跨過午夜，開始時刻算在時段內、結束時刻不算；`timezone` 為計算時段使用的 IANA 時區名稱
`preview`	String	使用者選擇的預覽方式：`full`、`sender_only`、`none`。沒有選擇時為 `null`
`effective_preview`	String	實際生效的預覽方式：使用者選擇過的取使用者的選擇，否則取應用執行策略的 `push_default_preview`
`settings_version`	Number	推送設定和會話免打擾共用的版本號，任何一項有變化都加一；從未設定過為 0

json

{
  "dnd": { "until": null },
  "quiet_hours": { "start": "22:00", "end": "07:30", "timezone": "Asia/Shanghai" },
  "preview": "sender_only",
  "effective_preview": "sender_only",
  "settings_version": 2
}

會話免打擾物件

欄位	型別	說明
`conversation_type`	String	會話型別：`single` 單聊，`group` 群聊
`target`	String	單聊為對方的使用者名稱，群聊為群 ID
`mode`	String	免打擾方式：`none` 不推送；`mention_only` 只在有人 @ 本人時推送（只用於群）
`until`	String	到期時間，為 `null` 表示一直有效
`updated_at`	String	最近一次設定的時間

json

{
  "conversation_type": "group",
  "target": "100311272729346048",
  "mode": "mention_only",
  "until": null,
  "updated_at": "2026-10-04T19:21:19.963Z"
}

推送裝置物件

欄位	型別	說明
`session_id`	String	裝置的會話 ID，與登入裝置物件的 `session_id` 相同
`device_id`	String	裝置標識，登入時由客戶端提交
`platform`	String	裝置平臺：`ios`、`macos`、`android` 或 `harmony`
`language`	String	裝置登記的語言（BCP 47），通知按它選擇模板的語言；沒有登記時為 `null`，使用應用執行策略的 `push_default_language`
`tokens`	Array<Object>	裝置的推送令牌，普通令牌按優先順序在前，VoIP 令牌在後，每項的欄位見下表
`badge`	Number	這臺裝置當前的角標計數：App 最近一次上報的值，加上之後推送的條數
`login_at`	String	這次登入的時間
`updated_at`	String	推送登記最近一次更新的時間，App 每次登記都會更新

tokens 中每項的欄位：

欄位	型別	說明
`kind`	String	`alert` 普通令牌；`voip` VoIP 令牌，只用於 iOS 的來電
`priority`	Number	普通令牌的優先順序，從 1 開始，傳送時先用小的；VoIP 令牌為 1
`credential`	String	令牌所屬的憑據名稱。憑據已刪除、令牌還沒有清理時為空字串
`channel`	String	推送通道：`apns`、`fcm`、`huawei`、`harmony`、`xiaomi`、`oppo`、`vivo`、`honor`、`meizu`
`token`	String	遮蓋後的令牌：只顯示前 6 位和後 4 位，中間為 `…`

json

{
  "session_id": "100310865730863104",
  "device_id": "a3d91c07-58e2-4f6b-b1c4-7e0f2d9a6c35",
  "platform": "android",
  "language": "zh-CN",
  "tokens": [
    { "kind": "alert", "priority": 1, "credential": "xiaomi-main", "channel": "xiaomi", "token": "Lx9Qw2…Kd3P" },
    { "kind": "alert", "priority": 2, "credential": "fcm-global", "channel": "fcm", "token": "cR5tY8…nM0q" }
  ],
  "badge": 0,
  "login_at": "2026-10-04T19:19:34.079Z",
  "updated_at": "2026-10-04T19:27:20.056Z"
}

推送裝置與設定 ​

查詢推送設定 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

修改推送設定 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢會話免打擾 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

設定會話免打擾 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

取消會話免打擾 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢推送裝置 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

解綁推送裝置 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

推送設定物件 ​

會話免打擾物件 ​

推送裝置物件 ​

推送裝置與設定

查詢推送設定

路徑引數

請求示例

響應

錯誤

修改推送設定

路徑引數

請求體

請求示例

響應

錯誤

查詢會話免打擾

路徑引數

查詢引數

請求示例

響應

錯誤

設定會話免打擾

路徑引數

請求體

請求示例

響應

錯誤

取消會話免打擾

路徑引數

請求示例

響應

錯誤

查詢推送裝置

路徑引數

請求示例

響應

錯誤

解綁推送裝置

路徑引數

請求示例

響應

錯誤

資料結構

推送設定物件

會話免打擾物件

推送裝置物件