设置拉黑状态

拉黑或取消拉黑一个用户，返回操作后的关系与权限。

POST /app/sdk/friends/block

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数

JSON Body

参数	类型	必填	说明
user_id	string	是	目标用户的外部 user_id，1–64 字符，不含控制字符。
blocked	boolean	是	true 拉黑，false 取消拉黑。

请求示例

curl 'https://example.com/app/sdk/friends/block' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"user_id":"linzhou","blocked":true}'

使用说明

• 只提交上表字段，操作结果以返回的 relation 和 permissions 为准。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
code	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msg	string	成功通常为 ok，失败时为错误说明。
data	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
ip_region	string | null	IP 属地展示文字；没有信息时为 null。
conversation_id	string	与此人的单聊会话 ID。
user	User	目标用户资料。
presence	Presence	目标用户在线状态。
relation	Relation	本人和目标用户的好友关系。
conversation_settings	ConversationSettings	本人对此会话的设置。
permissions	ProfilePermissions	当前可执行的操作。
event_id	string | null	与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

展开完整返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "ip_region": null,
    "conversation_id": "friend_bGluemhvdQ",
    "user": {
      "id": "1025",
      "user_id": "linzhou",
      "username": "linzhou",
      "nickname": "林舟",
      "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
      "signature": "把每一次出发安排妥当",
      "profile_updated_at": 1792301400000
    },
    "presence": {
      "online": true,
      "online_updated_at": 1792301400000
    },
    "relation": {
      "status": "friend",
      "blocked": true,
      "remark": "",
      "display_name": "林舟",
      "initial": "L",
      "updated_at": 1792301400000
    },
    "conversation_settings": {
      "available": true,
      "pinnable": true,
      "pinned": false,
      "muted": false
    },
    "permissions": {
      "message": false,
      "set_remark": true,
      "add_friend": false,
      "block_user": true,
      "report_user": true
    },
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c"
  }
}

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

用户资料 · 在线状态 · 与当前用户的关系 · 个人会话设置 · 用户资料页操作权限

用户资料（User）

字段	类型	说明
id	string	IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
user_id	string	宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
username	string | null	可用于精确搜索的账号；没有设置时为 null。
nickname	string	显示昵称。
avatar	string	头像地址。
signature	string	个性签名；未设置时为空字符串。
profile_updated_at	integer	公开资料最后更新时间，Unix 毫秒时间戳。

在线状态（Presence）

字段	类型	说明
online	boolean	当前是否在线。
online_updated_at	integer	在线状态最后更新时间，Unix 毫秒时间戳。

与当前用户的关系（Relation）

字段	类型	说明
status	string	friend 表示好友；stranger 表示非好友。
blocked	boolean	本人是否已拉黑对方。
remark	string	本人对好友的备注；没有备注时为空字符串。
display_name	string	当前账号应显示的名称，优先使用备注。
initial	string	显示名首字母分组：A–Z 或 #。
updated_at	integer	关系最后更新时间；没有关系记录时为 0，Unix 毫秒时间戳。

个人会话设置（ConversationSettings）

字段	类型	说明
available	boolean	是否已存在可设置的会话记录。
pinnable	boolean	当前是否可以置顶。
pinned	boolean	本人是否已置顶。
muted	boolean	本人是否已开启免打扰。

用户资料页操作权限（ProfilePermissions）

字段	类型	说明
message	boolean	当前是否允许发送消息。
set_remark	boolean	当前是否允许设置备注。
add_friend	boolean	当前是否允许发送好友申请。
block_user	boolean	当前是否允许设置拉黑状态。
report_user	boolean	当前是否允许举报此用户。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回用户、好友与申请接口列表 · HTTP 请求约定