批量取消订阅用户在线状态

在线状态（Presence）表示用户的当前状态信息。除了环信 IM 内置的在线和离线状态，你还可以添加自定义在线状态，例如忙碌、马上回来、离开、接听电话、外出就餐等。本文展示如何调用环信即时通讯 RESTful API 实现用户在线状态（Presence）订阅，包括设置用户在线状态信息、批量订阅和获取在线状态、取消订阅以及查询订阅列表。

关于用户的在线、离线和自定义状态的定义，详见 用户在线状态管理。

功能说明

一次最多可取消订阅 100 个用户的在线状态。

功能开通

使用 Presence 功能前，你需要在 环信控制台 开通。详见 环信控制台文档。

调用频率上限

100 次/秒/App Key

请求 URL

DELETE https://{host}/{org_name}/{app_name}/users/{username}/presence

参数	类型	是否必需	描述
username	String	是	为该用户 ID 取消订阅的在线状态。

关于请求 URL 中的其他参数说明，详见 请求 URL 参数介绍。

请求示例

curl -X DELETE 'https://XXXX/XXXX/XXXX/users/wzy/presence' \
-H 'Authorization: Bearer <YourAppToken>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'  \
-d '["c1"]'

请求 header 参数

关于 Content-Type、Accept 和 Authorization 字段的说明，详见 请求 header 参数说明。

请求 body 参数

参数	类型	是否必需	描述
users	JSON Array	是	要取消订阅在线状态的用户 ID 数组，例如 ["user1", "user2"]，最多可传 100 个用户 ID。

响应示例

{"result":"ok"}

响应 body 字段

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
result	String	是否成功取消订阅用户的在线状态。若成功，返回 "ok"，失败则返回相应的错误原因。

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	illegal_argument	usernames cannot be null	要取消订阅在线状态的用户 ID 数组为空。	保证要取消订阅在线状态的用户 ID 数组为非空值。
400	illegal_argument	too many unsub presences	取消订阅在线状态的用户列表超过了 100 个用户 ID。	控制取消订阅在线状态的用户列表在 100 个用户 ID 以内。
400	service open exception	the app not open presence	没有开通 Presence 服务。	联系商务开通 Presence 服务。
401	unauthorized	Unable to authenticate (OAuth)	token 不合法，可能过期或 token 错误。	使用新的 token 访问。

关于其他错误，你可以参考 响应状态码 了解可能的原因。