会话接口

开发建议

会话数据是系统中仅次于消息数据的第二大体量的实体,发生在这个上面的事件和操作都非常频繁,因此强烈建议对接系统的时候,在自己的系统中维护一份会话数据,仅在数据缺失的情况下调用下述接口进行数据补齐同步,并根据系统的事件推送实时的更新会话数据,这样可以保证系统的稳定性和性能,如果所有数据均依赖一下接口,可能会因为频率限制等因素导致系统不稳定

获取指定会话

使用场景

此接口适合在接收到某一个会话事件推送之后,当通过事件中的chatId找不到对应的会话信息时,调用此接口获取会话信息 因为这个事件大多数情况是建议在通过事件进行触发,因此这个接口有频率调用限制,当前限制为300次/30秒 如果有大批量获取会话数据的需求,请使用下面的获取会话列表接口

GET https://ex-api.botorange.com/chat/get

参数:

名称类型是否必须备注
tokenstring调用接口凭证, 获取方式
chatIdstring希望获取数据的chatId

参数需要通过url传入,例如:

GET https://ex-api.botorange.com/chat/get?token={your-token}

返回参数说明:

参数类型必定存在备注
codenumber返回码
dataobject对应的会话数据
data.chatIdstring会话的chatId
data.assigneeIdstring当前会话分配的人,如果为空字符串说明当前对话处于未分配状态uid
data.botIdstring当前会话所属的托管账号, 详见botId
data.typeint会话类型,0代表私聊会话,1代表群聊会话
data.wxidstring当前会话的wxid,如果是私聊会话,详见imContactId,如果是群聊会话,详见imRoomId
data.avatarUrlstring当前会话的头像链接地址
data.namestring当前会话的名字,如果是私聊会话,且当前好友有备注,则这个值为备注,如果没有备注,则为昵称,如果是群聊会话,则是群名
data.extraInfostring当前会话的额外信息,如果是私聊会话,且当前好友有备注,则这个值为昵称,如果没有备注,则此值为空,如果是群聊会话,这个值是当前群的成员数量
data.contactTypeint仅私聊会话有这个值,0是未知类型,1是个人微信,2是公众号,3是企业微信
data.coworkerboolean仅私聊会话有这个值,当前会话对象是否为企业内部成员
data.corporationstring仅私聊会话有这个值,标识当前账号所属的组织名字
data.externalUserIdstring仅私聊会话有这个值,为当前对象的externalUserId
data.wecomChatIdstring仅群聊会话有这个值,为当前对象的wecomChatId

获取会话列表

注意

此接口用来批量拉取对应小组内的所有会话数据,因为数据量比较大,且系统内的数据库是读写分离的,因此这个接口拉取到的数据可能会有延迟不准确的情况,

GET https://ex-api.botorange.com/chat/list

参数:

名称类型是否必须备注
tokenstring调用接口凭证, 获取方式
iteratorstring用来遍历所有数据的迭代器,如果不传,则从最近创建出来的会话开始返回数据,这个值可以从接口的返回值里获取的
pageSizenumber获取数据的页数大小,默认值 10,最大值 1000

参数需要通过url传入,例如:

GET https://ex-api.botorange.com/chat/list?iterator=xxx&pageSize=100&token={your-token}

返回参数说明:

参数类型必定存在备注
codenumber返回码
nextIteratorstring下一页需要传入的迭代器,仅当下一页存在数据的时候才会返回,如果当前没有下一页数据了,则此值不存在
chatsarray对应的会话数据数组
chats.chatIdstring会话的chatId
chats.assigneeIdstring当前会话分配的人,如果为空字符串说明当前对话处于未分配状态uid
chats.botIdstring当前会话所属的托管账号, 详见botId
chats.typeint会话类型,0代表私聊会话,1代表群聊会话
chats.wxidstring当前会话的wxid,如果是私聊会话,详见imContactId,如果是群聊会话,详见imRoomId
chats.avatarUrlstring当前会话的头像链接地址
chats.namestring当前会话的名字,如果是私聊会话,且当前好友有备注,则这个值为备注,如果没有备注,则为昵称,如果是群聊会话,则是群名
chats.extraInfostring当前会话的额外信息,如果是私聊会话,且当前好友有备注,则这个值为昵称,如果没有备注,则此值为空,如果是群聊会话,这个值是当前群的成员数量
chats.contactTypeint仅私聊会话有这个值,0是未知类型,1是个人微信,2是公众号,3是企业微信
chats.coworkerboolean仅私聊会话有这个值,当前会话对象是否为企业内部成员
chats.corporationstring仅私聊会话有这个值,标识当前账号所属的组织名字
chats.externalUserIdstring仅私聊会话有这个值,为当前对象的externalUserId
chats.wecomChatIdstring仅群聊会话有这个值,为当前对象的wecomChatId

分配会话

POST https://ex-api.botorange.com/chat/assign

参数:

名称类型是否必须备注
tokenstring调用接口凭证, 获取方式
chatIdstring要被分配的会话id
assigneeIdstring需要将会话分配给的成员,非必传,当参数不存在的时候,会将当前会话释放

返回参数说明:

参数类型必定存在备注
codenumber返回码

错误码

错误码含义
0成功
-1传入的 chatId 不合法,通过这个 chatId 无法找到对应的会话
-2传入的 assignId 不合法,通过这个 assignId 无法找到对应的企业成员

关闭会话

和分配会话给空的区别

细心的开发者可能会发现,这个接口调用的结果,和上面的分配会话接口传assignId为空很像,那为什么还会有这个接口呢?

其实这个接口,是做了以下两件事情

  • 将当前会话取消分配(和分配会话给空的表现一致)
  • 清除当前会话的未读数量

所以可以看出来,这个接口额外会将会话的未读数清空,这样表示当前的这个会话已经不再需要任何人去回复处理了

POST https://ex-api.botorange.com/chat/close

参数:

名称类型是否必须备注
tokenstring调用接口凭证, 获取方式
chatIdstring要被关闭的会话id

返回参数说明:

参数类型必定存在备注
codenumber返回码

错误码

错误码含义
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
}

参数说明:

参数类型必定存在备注
eventIdstring事件id,全局唯一
chatIdstring聊天id(表示一个托管账号和一个客户或群)
typenumber消息类型(详情见下方 SystemMsgType
opUserIdstring操作用户的 uid
assigneeUserIdstring被分配的用户的 uid
timestampnumber消息的时间(ms)
tokenstring秒回token

Type 枚举的定义如下

enum SystemMsgType {
  ASSIGN_CHAT = 0,   // 手动分配会话
  MARK_AS_READ = 1,  // 将会话标为已读
  CLOSE_CHAT = 2,    // 关闭会话
  AUTO_ASSIGN = 3,   // 自动(系统)分配会话
  API_ASSIGN = 7,    // 通过 API 分配会话(暂不支持,先行预留这个枚举值,后续支持)
}

不同类型事件里 opUserIdassigneeUserId 是否存在

注意:assigneeUserId 可能是空字符串

事件 ASSIGN_CHATAUTO_ASSIGNAPI_ASSIGN 中,assigneeUserId 有可能为空字符串,在如下情况下会出现:

当前的会话分配操作将一个已分配的会话置成了未分配状态,此时的 assigneeUserId 即为空

TypeopUserIdassigneeUserId
ASSIGN_CHAT一定存在一定存在
MARK_AS_READ一定存在不存在
CLOSE_CHAT一定存在不存在
AUTO_ASSIGN不存在一定存在
API_ASSIGN不存在一定存在
最近更新:
Contributors: windmemory, wangjingbo