发送好友申请

向一个用户申请添加好友。已有对方发来的反向申请时，服务器可能直接建立好友关系。

POST /app/sdk/friends/request

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

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

请求参数

JSON Body

参数	类型	必填	说明
`user_id`	string	是	目标用户的外部 user_id，1–64 字符，不含控制字符。
`request_id`	string	是	本次操作的去重 ID，1–64 位字母、数字、点、下划线、冒号或连字符。同一次操作重试时保持不变。
`message`	string	是	申请说明，最长 255 字符，可换行，也可为空字符串。
`source`	string	是	入口来源：search 搜索、profile 资料页、qr 二维码。

请求示例

bash

curl 'https://example.com/app/sdk/friends/request' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"user_id":"linzhou","request_id":"outing-20261018-01","message":"我是行政部陈悦，一起确认秋日海岸出游安排吧。","source":"search"}'

使用说明

四个字段都要提交，message 不需要说明时传空字符串。
网络重试使用原 request_id，不要创建一条新的申请。

返回参数

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

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

data 字段

字段	类型	说明
`event_id`	string \| null	与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。
`created`	boolean	是否新建了申请；相同请求重试时通常为 false。
`automatically_accepted`	boolean	是否因为已有反向申请而自动成为好友。
`unread_notice_count`	integer	当前账号的未读申请数，0–100。
`item`	Notice	当前申请。
`profile`	UserProfile	操作后的用户资料、关系与权限。

返回示例

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

展开完整返回示例

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
    "created": true,
    "automatically_accepted": false,
    "unread_notice_count": 0,
    "item": {
      "notice_id": "3101",
      "type": "friend_request",
      "direction": "sent",
      "status": "pending",
      "message": "我是行政部陈悦，一起确认秋日海岸出游安排吧。",
      "source": "search",
      "created_at": 1792301400000,
      "updated_at": 1792301400000,
      "handled_at": null,
      "actor": {
        "id": "1024",
        "user_id": "chenyue",
        "username": "chenyue",
        "nickname": "陈悦",
        "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
        "signature": "一起发现沿途的风景",
        "profile_updated_at": 1792301400000
      },
      "recipient": {
        "id": "1025",
        "user_id": "linzhou",
        "username": "linzhou",
        "nickname": "林舟",
        "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
        "signature": "把每一次出发安排妥当",
        "profile_updated_at": 1792301400000
      },
      "subject": null,
      "group": null,
      "permissions": {
        "accept": true,
        "reject": true
      }
    },
    "profile": {
      "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": false,
        "remark": "",
        "display_name": "林舟",
        "initial": "L",
        "updated_at": 1792301400000
      },
      "conversation_settings": {
        "available": true,
        "pinnable": true,
        "pinned": false,
        "muted": false
      },
      "permissions": {
        "message": true,
        "set_remark": true,
        "add_friend": false,
        "block_user": true,
        "report_user": true
      }
    }
  }
}

返回对象字段

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

申请或邀请 · 用户资料 · 群资料 · 申请处理权限 · 用户资料与好友关系 · 在线状态 · 与当前用户的关系 · 个人会话设置 · 用户资料页操作权限

申请或邀请（Notice）

字段	类型	说明
`notice_id`	string	申请 ID；读取时为十进制字符串，提交处理请求时使用正整数。
`type`	string	friend_request 好友申请、group_join_request 入群申请、group_invitation 群邀请。
`direction`	string	received 表示收到的申请，sent 表示本人发出的申请。
`status`	string	pending 待处理、accepted 已同意、rejected 已拒绝、expired 已过期、revoked 已撤销。
`message`	string	申请说明；可能为空字符串。
`source`	string	申请来源，例如 search、profile、qr；由具体业务产生。
`created_at`	integer	申请创建时间，Unix 毫秒时间戳。
`updated_at`	integer	申请最后更新时间，Unix 毫秒时间戳。
`handled_at`	integer \| null	申请处理时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
`actor`	User	发起人资料。
`recipient`	User	接收人资料。
`subject`	User \| null	群邀请中被邀请人的资料；其他申请通常为 null。
`group`	Group \| null	关联群资料；好友申请为 null。
`permissions`	NoticePermissions	当前账号能否同意或拒绝。

用户资料（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 毫秒时间戳。

群资料（Group）

字段	类型	说明
`group_id`	string	公开群 ID，群相关请求使用这个值。
`owner_id`	string	群主的外部 user_id。
`name`	string	群名称。
`avatar`	string	群头像地址。
`avatar_custom`	boolean	是否由用户上传头像；false 表示服务器生成的组合头像。
`announcement`	string \| null	群公告正文；没有公告时为 null。
`announcement_author_id`	string \| null	最近一次公告发布者的外部 user_id；没有公告时可为 null。
`announcement_author_name`	string \| null	公告发布者的显示名；没有公告时可为 null。
`announcement_updated_at`	integer	公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
`status`	string	群状态：active 正常、disabled 停用、dissolved 已解散。
`all_muted`	boolean	是否开启全员禁言。
`join_approval_required`	boolean	扫码加入是否需要群主或管理员审批。
`member_count`	integer	当前成员人数。
`unread_mode`	string	未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
`last_mid`	string	最新消息 ID；还没有消息时为 "0"。
`last_seq`	string	最新消息在群内的序号；没有消息时为 "0"。
`last_message_at`	integer	最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
`conversation_updated_at`	integer	群会话内容最后更新时间，Unix 毫秒时间戳。
`created_at`	integer	建群时间，Unix 毫秒时间戳。
`updated_at`	integer	群资料最后更新时间，Unix 毫秒时间戳。

申请处理权限（NoticePermissions）

字段	类型	说明
`accept`	boolean	当前账号是否可以同意此申请。
`reject`	boolean	当前账号是否可以拒绝此申请。

用户资料与好友关系（UserProfile）

字段	类型	说明
`ip_region`	string \| null	IP 属地展示文字；没有信息时为 null。
`conversation_id`	string	与此人的单聊会话 ID。
`user`	User	目标用户资料。
`presence`	Presence	目标用户在线状态。
`relation`	Relation	本人和目标用户的好友关系。
`conversation_settings`	ConversationSettings	本人对此会话的设置。
`permissions`	ProfilePermissions	当前可执行的操作。

在线状态（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 请求约定

用户预置与 Token

首页与会话

消息

上传与下载

用户、好友与申请

群与成员

搜索

音视频通话

随附宿主账号

设备与推送

举报与诊断

发送好友申请

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

申请或邀请（Notice）

用户资料（User）

群资料（Group）

申请处理权限（NoticePermissions）

用户资料与好友关系（UserProfile）

在线状态（Presence）

与当前用户的关系（Relation）

个人会话设置（ConversationSettings）

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

错误处理

发送好友申请 ​

请求参数 ​

JSON Body ​

请求示例 ​

使用说明 ​

返回参数 ​

data 字段 ​

返回示例 ​

返回对象字段 ​

申请或邀请（Notice） ​

用户资料（User） ​

群资料（Group） ​

申请处理权限（NoticePermissions） ​

用户资料与好友关系（UserProfile） ​

在线状态（Presence） ​

与当前用户的关系（Relation） ​

个人会话设置（ConversationSettings） ​

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

错误处理 ​

发送好友申请

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

申请或邀请（Notice）

用户资料（User）

群资料（Group）

申请处理权限（NoticePermissions）

用户资料与好友关系（UserProfile）

在线状态（Presence）

与当前用户的关系（Relation）

个人会话设置（ConversationSettings）

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

错误处理