会话接口
开发建议
会话数据是系统中仅次于消息数据的第二大体量的实体,发生在这个上面的事件和操作都非常频繁,因此强烈建议对接系统的时候,在自己的系统中维护一份会话数据,仅在数据缺失的情况下调用下述接口进行数据补齐同步,并根据系统的事件推送实时的更新会话数据,这样可以保证系统的稳定性和性能,如果所有数据均依赖一下接口,可能会因为频率限制等因素导致系统不稳定
获取指定会话
使用场景
此接口适合在接收到某一个会话事件推送之后,当通过事件中的chatId
找不到对应的会话信息时,调用此接口获取会话信息 因为这个事件大多数情况是建议在通过事件进行触发,因此这个接口有频率调用限制,当前限制为300次/30秒 如果有大批量获取会话数据的需求,请使用下面的获取会话列表接口
GET https://ex-api.botorange.com/chat/get
参数:
名称 | 类型 | 是否必须 | 备注 |
---|---|---|---|
token | string | 是 | 调用接口凭证, 获取方式 |
chatId | string | 是 | 希望获取数据的chatId |
参数需要通过url传入,例如:
GET https://ex-api.botorange.com/chat/get?token={your-token}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|---|---|---|
code | number | 是 | 返回码 |
data | object | 是 | 对应的会话数据 |
data.chatId | string | 是 | 会话的chatId |
data.assigneeId | string | 是 | 当前会话分配的人,如果为空字符串说明当前对话处于未分配状态uid |
data.botId | string | 是 | 当前会话所属的托管账号, 详见botId |
data.type | int | 是 | 会话类型,0代表私聊会话,1代表群聊会话 |
data.wxid | string | 是 | 当前会话的wxid,如果是私聊会话,详见imContactId,如果是群聊会话,详见imRoomId |
data.avatarUrl | string | 是 | 当前会话的头像链接地址 |
data.name | string | 是 | 当前会话的名字,如果是私聊会话,且当前好友有备注,则这个值为备注,如果没有备注,则为昵称,如果是群聊会话,则是群名 |
data.extraInfo | string | 否 | 当前会话的额外信息,如果是私聊会话,且当前好友有备注,则这个值为昵称,如果没有备注,则此值为空,如果是群聊会话,这个值是当前群的成员数量 |
data.contactType | int | 否 | 仅私聊会话有这个值,0是未知类型,1是个人微信,2是公众号,3是企业微信 |
data.coworker | boolean | 否 | 仅私聊会话有这个值,当前会话对象是否为企业内部成员 |
data.corporation | string | 否 | 仅私聊会话有这个值,标识当前账号所属的组织名字 |
data.externalUserId | string | 否 | 仅私聊会话有这个值,为当前对象的externalUserId |
data.wecomChatId | string | 否 | 仅群聊会话有这个值,为当前对象的wecomChatId |
获取会话列表
注意
此接口用来批量拉取对应小组内的所有会话数据,因为数据量比较大,且系统内的数据库是读写分离的,因此这个接口拉取到的数据可能会有延迟不准确的情况,
GET https://ex-api.botorange.com/chat/list
参数:
名称 | 类型 | 是否必须 | 备注 |
---|---|---|---|
token | string | 是 | 调用接口凭证, 获取方式 |
iterator | string | 否 | 用来遍历所有数据的迭代器,如果不传,则从最近创建出来的会话开始返回数据,这个值可以从接口的返回值里获取的 |
pageSize | number | 否 | 获取数据的页数大小,默认值 10,最大值 1000 |
参数需要通过url传入,例如:
GET https://ex-api.botorange.com/chat/list?iterator=xxx&pageSize=100&token={your-token}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|---|---|---|
code | number | 是 | 返回码 |
nextIterator | string | 否 | 下一页需要传入的迭代器,仅当下一页存在数据的时候才会返回,如果当前没有下一页数据了,则此值不存在 |
chats | array | 是 | 对应的会话数据数组 |
chats.chatId | string | 是 | 会话的chatId |
chats.assigneeId | string | 是 | 当前会话分配的人,如果为空字符串说明当前对话处于未分配状态uid |
chats.botId | string | 是 | 当前会话所属的托管账号, 详见botId |
chats.type | int | 是 | 会话类型,0代表私聊会话,1代表群聊会话 |
chats.wxid | string | 是 | 当前会话的wxid,如果是私聊会话,详见imContactId,如果是群聊会话,详见imRoomId |
chats.avatarUrl | string | 是 | 当前会话的头像链接地址 |
chats.name | string | 是 | 当前会话的名字,如果是私聊会话,且当前好友有备注,则这个值为备注,如果没有备注,则为昵称,如果是群聊会话,则是群名 |
chats.extraInfo | string | 否 | 当前会话的额外信息,如果是私聊会话,且当前好友有备注,则这个值为昵称,如果没有备注,则此值为空,如果是群聊会话,这个值是当前群的成员数量 |
chats.contactType | int | 否 | 仅私聊会话有这个值,0是未知类型,1是个人微信,2是公众号,3是企业微信 |
chats.coworker | boolean | 否 | 仅私聊会话有这个值,当前会话对象是否为企业内部成员 |
chats.corporation | string | 否 | 仅私聊会话有这个值,标识当前账号所属的组织名字 |
chats.externalUserId | string | 否 | 仅私聊会话有这个值,为当前对象的externalUserId |
chats.wecomChatId | string | 否 | 仅群聊会话有这个值,为当前对象的wecomChatId |
分配会话
POST https://ex-api.botorange.com/chat/assign
参数:
名称 | 类型 | 是否必须 | 备注 |
---|---|---|---|
token | string | 是 | 调用接口凭证, 获取方式 |
chatId | string | 是 | 要被分配的会话id |
assigneeId | string | 否 | 需要将会话分配给的成员,非必传,当参数不存在的时候,会将当前会话释放 |
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|---|---|---|
code | number | 是 | 返回码 |
错误码
错误码 | 含义 |
---|---|
0 | 成功 |
-1 | 传入的 chatId 不合法,通过这个 chatId 无法找到对应的会话 |
-2 | 传入的 assignId 不合法,通过这个 assignId 无法找到对应的企业成员 |
关闭会话
和分配会话给空的区别
细心的开发者可能会发现,这个接口调用的结果,和上面的分配会话接口传assignId为空很像,那为什么还会有这个接口呢?
其实这个接口,是做了以下两件事情
- 将当前会话取消分配(和分配会话给空的表现一致)
- 清除当前会话的未读数量
所以可以看出来,这个接口额外会将会话的未读数清空,这样表示当前的这个会话已经不再需要任何人去回复处理了
POST https://ex-api.botorange.com/chat/close
参数:
名称 | 类型 | 是否必须 | 备注 |
---|---|---|---|
token | string | 是 | 调用接口凭证, 获取方式 |
chatId | string | 是 | 要被关闭的会话id |
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|---|---|---|
code | number | 是 | 返回码 |
错误码
错误码 | 含义 |
---|---|
0 | 成功 |
-1 | 传入的 chatId 不合法,通过这个 chatId 无法找到对应的会话 |
-2 | 当前会话没有被分配给任何人,无法关闭会话 |
接收会话事件
当发生会话状态变更的时候,系统会自动调用设置好的回调地址,将会话变更的事件内容推送到指定的服务器上
- 具体的地址为
{回调地址}/chat
,例如配置的是abc.com
,则消息回调会调用abc.com/chat
- 地址需要接收一个
POST
类型的请求,数据为json
类型,格式如下
{
"data": ChatEventData // 见下面消息格式
}
事件格式
示例数据
{
"eventId": "2422188041612737714", // unique event message id
"chatId": "5e469a2b8d429806b0fef189", // juzi system chatId
"type": 0,
"opUserId": "5e123a2b8d123806b0fef189",
"assigneeUserId": "611233218dfdf806babaf189",
"timestamp": 1585995128441, // event timestamp
"token": "5dbe8221fc191f13bc072908", // token
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|---|---|---|
eventId | string | 是 | 事件id,全局唯一 |
chatId | string | 是 | 聊天id(表示一个托管账号和一个客户或群) |
type | number | 是 | 消息类型(详情见下方 SystemMsgType ) |
opUserId | string | 否 | 操作用户的 uid |
assigneeUserId | string | 否 | 被分配的用户的 uid |
timestamp | number | 是 | 消息的时间(ms) |
token | string | 是 | 秒回token |
Type
枚举的定义如下
enum SystemMsgType {
ASSIGN_CHAT = 0, // 手动分配会话
MARK_AS_READ = 1, // 将会话标为已读
CLOSE_CHAT = 2, // 关闭会话
AUTO_ASSIGN = 3, // 自动(系统)分配会话
API_ASSIGN = 7, // 通过 API 分配会话(暂不支持,先行预留这个枚举值,后续支持)
}
opUserId
和 assigneeUserId
是否存在
不同类型事件里 注意:assigneeUserId 可能是空字符串
事件 ASSIGN_CHAT
,AUTO_ASSIGN
,API_ASSIGN
中,assigneeUserId
有可能为空字符串,在如下情况下会出现:
当前的会话分配操作将一个已分配的会话置成了未分配状态,此时的 assigneeUserId
即为空
Type | opUserId | assigneeUserId |
---|---|---|
ASSIGN_CHAT | 一定存在 | 一定存在 |
MARK_AS_READ | 一定存在 | 不存在 |
CLOSE_CHAT | 一定存在 | 不存在 |
AUTO_ASSIGN | 不存在 | 一定存在 |
API_ASSIGN | 不存在 | 一定存在 |