泡泡 IM

外观

读取首页数据 ​

SDK 登录后读取未读数、可用功能、媒体限制和第一页会话。无业务参数，发送空对象即可。

POST /app/sdk/sync

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

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

请求参数 ​

无业务参数，JSON Body 发送 {} 即可。

请求示例 ​

bash
curl 'https://example.com/app/sdk/sync' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{}'

使用说明 ​

  • 这里只返回首页所需数据，通话状态不放在 sync 中。
  • 会话超过 50 项时，用 conversations.next_cursor 继续读取会话列表。

返回参数 ​

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

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

data 字段 ​

字段类型说明
unreadUnread当前账号的未读数。
configuration_revisioninteger功能和媒体配置的版本号。配置更新后重新读取即可获得最新限制。
capabilitiesCapabilities当前开放的功能。
media_limitsMediaLimits当前媒体上传限制，后台可调整。
conversationsConversationPage第一页会话。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "unread": {
      "message": 0,
      "notice": 0
    },
    "configuration_revision": 1,
    "capabilities": {
      "direct_chat": true,
      "group_chat": true,
      "add_friend": true,
      "create_group": true,
      "voice": true,
      "emoji": true,
      "image": true,
      "video": true,
      "file": true,
      "contact_card": true,
      "read_receipt": true,
      "typing_indicator": true,
      "forward": true,
      "group_qrcode": true,
      "group_member_add_friend": true,
      "report_user": true,
      "stranger_chat": true,
      "voice_call": true,
      "video_call": true
    },
    "media_limits": {
      "image": {
        "max_bytes": 8388608
      },
      "voice": {
        "max_bytes": 10485760,
        "max_duration_ms": 60000
      },
      "video": {
        "max_bytes": 8388608
      },
      "file": {
        "max_bytes": 8388608
      }
    },
    "conversations": {
      "items": [
        {
          "conversation_id": "friend_bGluemhvdQ",
          "type": "friend",
          "target_id": "linzhou",
          "name": "林舟",
          "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
          "member_count": null,
          "group_role": null,
          "all_muted": false,
          "send_forbidden_until": 0,
          "last_mid": "8601",
          "last_seq": "18",
          "read_seq": "18",
          "peer_read_seq": "17",
          "announcement_updated_at": 0,
          "announcement_unread": false,
          "mention_unread": false,
          "updated_at": 1792301401000,
          "last_message_time": 1792301401000,
          "last_message": {
            "mid": "8601",
            "conversation_seq": "18",
            "sender_id": "chenyue",
            "sender_name": null,
            "type": "text",
            "status": "normal",
            "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
            "file_name": null,
            "created_at": 1792301401000,
            "updated_at": 1792301401000
          },
          "unread_count": 0,
          "pinned": false,
          "muted": false,
          "state": "chatting",
          "peer": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "peer_presence": {
            "online": true,
            "online_updated_at": 1792301400000
          }
        }
      ],
      "next_cursor": null,
      "has_more": false
    }
  }
}

返回对象字段 ​

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

未读数量 · 可用功能 · 媒体上传限制 · 资源大小限制 · 语音限制 · 会话列表分页 · 会话 · 最后一条消息摘要 · 用户资料 · 在线状态 · 群资料

未读数量（Unread） ​

字段类型说明
messageinteger未读消息数，0–100；100 表示至少 100 条。
noticeinteger未读申请数，0–100；100 表示至少 100 条。

可用功能（Capabilities） ​

字段类型说明
direct_chatboolean是否开放单聊功能；false 时界面应隐藏或关闭相应入口。
group_chatboolean是否开放群聊功能；false 时界面应隐藏或关闭相应入口。
add_friendboolean是否开放添加好友功能；false 时界面应隐藏或关闭相应入口。
create_groupboolean是否开放创建群功能；false 时界面应隐藏或关闭相应入口。
voiceboolean是否开放发送语音功能；false 时界面应隐藏或关闭相应入口。
emojiboolean是否开放表情功能；false 时界面应隐藏或关闭相应入口。
imageboolean是否开放发送图片功能；false 时界面应隐藏或关闭相应入口。
videoboolean是否开放发送视频功能；false 时界面应隐藏或关闭相应入口。
fileboolean是否开放发送文件功能；false 时界面应隐藏或关闭相应入口。
contact_cardboolean是否开放发送名片功能；false 时界面应隐藏或关闭相应入口。
read_receiptboolean是否开放已读回执功能；false 时界面应隐藏或关闭相应入口。
typing_indicatorboolean是否开放正在输入提示功能；false 时界面应隐藏或关闭相应入口。
forwardboolean是否开放转发功能；false 时界面应隐藏或关闭相应入口。
group_qrcodeboolean是否开放群二维码功能；false 时界面应隐藏或关闭相应入口。
group_member_add_friendboolean是否开放从群成员添加好友功能；false 时界面应隐藏或关闭相应入口。
report_userboolean是否开放举报功能；false 时界面应隐藏或关闭相应入口。
stranger_chatboolean是否开放与非好友聊天功能；false 时界面应隐藏或关闭相应入口。
voice_callboolean是否开放语音通话功能；false 时界面应隐藏或关闭相应入口。
video_callboolean是否开放视频通话功能；false 时界面应隐藏或关闭相应入口。

媒体上传限制（MediaLimits） ​

字段类型说明
imageByteLimit图片大小限制。
voiceVoiceLimit语音大小及长度限制。
videoByteLimit视频大小限制。
fileByteLimit普通文件大小限制。

资源大小限制（ByteLimit） ​

字段类型说明
max_bytesinteger单个文件允许的最大字节数。

语音限制（VoiceLimit） ​

字段类型说明
max_bytesinteger单个文件允许的最大字节数。
max_duration_msinteger语音最长时长，单位毫秒。

会话列表分页（ConversationPage） ​

字段类型说明
itemsConversation[]本页会话，最多 50 项。
next_cursorstring | null下一页游标；没有下一页时为 null。
has_moreboolean是否还有下一页。

会话（Conversation） ​

字段类型说明
conversation_idstring会话 ID。读取消息、发送消息和修改会话状态时直接使用此值。
typestringfriend 表示单聊，group 表示群聊。
target_idstring单聊为对方的外部 user_id；群聊为公开 group_id。
namestring当前账号看到的会话名称，可能已应用个人备注。
avatarstring会话头像地址。
member_countinteger | null群成员数；单聊为 null。
group_rolestring | null本人在群中的角色：owner 群主、admin 管理员、member 成员；单聊为 null。
all_mutedboolean群是否开启全员禁言；单聊为 false。
send_forbidden_untilinteger本人禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。
last_midstring最新消息 ID；没有消息时为 "0"。
last_seqstring最新消息序号；没有消息时为 "0"。
read_seqstring | null本人已读到的消息序号。未提供个人状态的共享事件可为 null。
peer_read_seqstring | null单聊对方已读到的序号；群聊为 null。
announcement_updated_atinteger群公告更新时间；单聊为 0，Unix 毫秒时间戳。
announcement_unreadboolean本人是否有未读群公告；单聊为 false。
mention_unreadboolean是否存在尚未读到的群内 @ 提醒；单聊为 false。
updated_atinteger会话最后更新时间，Unix 毫秒时间戳。
last_message_timeinteger最新消息时间；没有消息时为 0，Unix 毫秒时间戳。
last_messageLastMessage | null最后一条消息摘要；没有消息时为 null。
unread_countinteger本人未读消息数，范围 0–100；100 表示至少 100 条。
pinnedboolean本人是否置顶。
mutedboolean本人是否开启免打扰。
statestringchatting 表示显示在会话列表，hidden 表示隐藏。
peerUser仅单聊返回，对方完整资料；群聊不返回此字段。
peer_presencePresence | null单聊对方在线状态；群聊或暂时没有状态时为 null。
groupGroup仅群聊返回，完整群资料；单聊不返回此字段。

最后一条消息摘要（LastMessage） ​

字段类型说明
midstring消息 ID。
conversation_seqstring这条消息在当前会话中的序号。
sender_idstring | null发送者的外部 user_id；系统消息为 null。
sender_namestring | null群消息发送者的显示名；单聊中可为 null。
typestringtext 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。
statusstringnormal 正常、recalled 已撤回、deleted 已被当前账号删除。
textstring | null文字或摘要文本；没有文本、已撤回或已删除时为 null。
file_namestring | null文件名称；非文件消息或内容已清除时为 null。
created_atinteger发送时间，Unix 毫秒时间戳。
updated_atinteger消息最后更新时间，Unix 毫秒时间戳。

用户资料（User） ​

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

在线状态（Presence） ​

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

群资料（Group） ​

字段类型说明
group_idstring公开群 ID，群相关请求使用这个值。
owner_idstring群主的外部 user_id。
namestring群名称。
avatarstring群头像地址。
avatar_customboolean是否由用户上传头像；false 表示服务器生成的组合头像。
announcementstring | null群公告正文；没有公告时为 null。
announcement_author_idstring | null最近一次公告发布者的外部 user_id；没有公告时可为 null。
announcement_author_namestring | null公告发布者的显示名；没有公告时可为 null。
announcement_updated_atinteger公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
statusstring群状态：active 正常、disabled 停用、dissolved 已解散。
all_mutedboolean是否开启全员禁言。
join_approval_requiredboolean扫码加入是否需要群主或管理员审批。
member_countinteger当前成员人数。
unread_modestring未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
last_midstring最新消息 ID；还没有消息时为 "0"。
last_seqstring最新消息在群内的序号；没有消息时为 "0"。
last_message_atinteger最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
conversation_updated_atinteger群会话内容最后更新时间，Unix 毫秒时间戳。
created_atinteger建群时间，Unix 毫秒时间戳。
updated_atinteger群资料最后更新时间，Unix 毫秒时间戳。

错误处理 ​

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

返回首页与会话接口列表 · HTTP 请求约定

Copyright © 泡泡 IM