会话 API

会话模块提供会话列表、置顶/草稿/提醒级别设置、未读清零以及会话标签的添加、移除与查询。

模块概览​

项目值
接口数量20
幂等接口3
路径前缀/im/v2
请求方法POST(JSON 请求体)
鉴权方式App-Key / Nonce / Timestamp / Signature(见 鉴权与签名)
响应信封{ code, msg?, data?, requestId? }

接口列表​

接口方法路径说明幂等
用户会话列表POST/im/v2/conversation/list用户会话列表(置顶优先/updatedAt 倒序)。否
设置会话置顶/草稿/提醒级别POST/im/v2/conversation/settings设置会话置顶/草稿/提醒级别(服务端代操作)。否
清空会话未读POST/im/v2/conversation/unread/clear清空会话未读。是
将会话归入标签POST/im/v2/conversation/tag/set将会话归入标签(同一会话可属多个标签,最多 20 个)。是
将会话从标签移除POST/im/v2/conversation/tag/remove将会话从标签移除。否
查询用户的会话标签POST/im/v2/conversation/tag/list查询用户的会话标签(tag 省略返回全部标签及其会话)。否
查询单个会话属性POST/im/v2/conversation/attribute/get查询单个会话属性:置顶、免打扰(notificationLevel/mute)、未读数、草稿、@ 计数、标签与最后一条消息;会话不存在返回缺省值(不创建会话)。覆盖融云 /conversation/attribute/get.json。否
查询用户按会话类型设置的默认通知级别POST/im/v2/conversation/type/notification/get查询用户按会话类型设置的默认通知级别:0 全部通知 / 1 仅 @ / 2 免打扰;未设置返回 0。conversationType 支持 1 单聊 / 2 群 / 3 聊天室 / 6 系统 / 10 超级群。覆盖融云 /conversation/type/notification/get.json。否
设置用户按会话类型的默认通知级别POST/im/v2/conversation/type/notification/set设置用户按会话类型的默认通知级别(0 全部 / 1 仅 @ / 2 免打扰),按 {app}:{user}:{conversationType} 持久化。覆盖融云 /conversation/type/notification/set.json(unpushLevel/isMuted 均可作为入参别名)。是
创建会话标签POST/im/v2/conversation/tag/create创建会话标签:tagName ≤16 字符;tagId 可选(≤32 字符,[A-Za-z0-9_.-],缺省由 tagName 派生);单用户最多 20 个标签(超出 1031)。覆盖融云 /conversation/tag/create.json。否
重命名会话标签POST/im/v2/conversation/tag/update重命名会话标签(tagId 不变)。覆盖融云 /conversation/tag/update.json。否
删除会话标签POST/im/v2/conversation/tag/delete删除会话标签,同时清除标签内会话引用;标签不存在返回 1032。覆盖融云 /conversation/tag/delete.json。否
查询用户全部标签POST/im/v2/conversation/tag/get查询用户全部标签(含 conversationCount),按创建顺序返回。覆盖融云 /conversation/tag/get.json。否
把会话加入标签POST/im/v2/conversation/tag/conversations/add把会话加入标签:单次 ≤100 条(items 支持对象数组或 "type:target" 字符串),幂等;单标签最多 1000 个会话(超出 1033)。覆盖融云 /conversation/tag/conversations/add.json。否
把会话移出标签POST/im/v2/conversation/tag/conversations/remove把会话移出标签:单次 ≤100 条,幂等。覆盖融云 /conversation/tag/conversations/remove.json。否
分页查询标签内会话POST/im/v2/conversation/tag/conversations/get分页查询标签内会话(含 top、unreadCount、lastMessageAt;limit 默认 50 上限 200)。覆盖融云 /conversation/tag/conversations/get.json。否
查询某个会话所属标签列表POST/im/v2/conversation/tag/of/conversation查询某个会话所属标签列表。覆盖融云 /conversation/tag/of/conversation.json。否
标签内未读汇总POST/im/v2/conversation/tag/unread/get标签内未读汇总(unreadCount 消息总数 + unreadConversations 有未读的会话数)。覆盖融云 /conversation/tag/unread/get.json。否
标签内置顶/取消置顶会话POST/im/v2/conversation/tag/top/set标签内置顶/取消置顶会话,同时更新会话 is_pinned;会话不在标签内返回 1034。覆盖融云 /conversation/tag/top/set.json。否
删除会话记录POST/im/v2/conversation/delete删除会话记录(列表项/未读/草稿/置顶),历史消息保留;同时从该用户所有标签移除;幂等(removed=false 表示本就不存在)。覆盖融云 /conversation/delete.json。否

接口约定​

  • 完整请求地址 = 部署域名 + /im/v2 + 接口路径;所有接口使用 POST。
  • 请求头必须携带 App-Key / Nonce / Timestamp / Signature;签名规则见鉴权与签名。
  • 响应统一为 { code, msg?, data?, requestId? };code = 0 表示成功。
  • 列表类接口使用 limit 分页,单页上限见限频与限制。

相关说明​