# 小组控制台接口（legacy）

# 关于token

在小组控制台上添加微信号并扫码登录以后，在智能对话 ==> API接入页面即可找到自己的token

# 关于频率限制

每个秒回token的频次限制是500次/30s。当超过频率限制之后，接口将返回http状态码429，其返回的数据结构将和正常的返回值不同，body为一个字符串。

# 发送消息

# 发消息url为 https://ex-api.botorange.com/message/send

对于 externalRequestId 字段，采用幂等的处理方式。发送POST请求，请求数据为json格式，如下

text类型消息

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 0, // MessageType, check below
  "payload": {
    "text": "Hello World",
    "mention": [] // mention list, you can only set it when you send text message to room,
  },
  "externalRequestId": "1", // nullable, 会在回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

image类型消息

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 1, // MessageType, check below
  "payload": {
    "url": "https://s3.cn-north-1.amazonaws.com.cn/xiaoju-material/public/rc-upload-1585297566308-2_1585297937120_%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E7%BE%A4%E5%8F%91%E5%9B%BE(1).png",
    "size": 1024 // image size, nullable
  },
  "externalRequestId": "1", // nullable, 会在回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

link类型消息

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 2, // MessageType, check below
  "payload": {
    "sourceUrl": "http://mp.weixin.qq.com/s?__biz=MzA3MTA0ODYyOA==&mid=2651161429&idx=1&sn=30ee392b35dc2ac91b9408e3b25dc196&chksm=84c2af8eb3b526986e242cff11e11697dd54350a1b6bfff6082c7973fb51f170876b201bc690&mpshare=1&scene=1&srcid=&sharer_sharetime=1586011571343&sharer_shareid=fc884800739cdc7215d6a289dd736e76#rd",
    "title": "中国顶尖的技术社区们在一个群里，会聊什么",
    "summary": "微软加入群聊并发布一条重磅消息",
    "imageUrl": "https://mp.weixin.qq.com/mp/qrcode?scene=10000004&size=102&__biz=MzA3MTA0ODYyOA==&mid=2651161429&idx=1&sn=30ee392b35dc2ac91b9408e3b25dc196&send_time=",
  },
  "externalRequestId": "1", // nullable, 会在回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

file类型消息

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 3, // MessageType, check below
  "payload": {
    "name": "句子互动引流获客",
    "url": "https://s3.cn-northwest-1.amazonaws.com.cn/xiaoju-message-payload-bucket/message/5cd4dbbf454e8b4cc7b4c496/1576906142438/%E5%8F%A5%E5%AD%90%E7%A7%92%E5%9B%9E%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D.pdf",
    "size": 1024 // file size, nullable
  },
  "externalRequestId": "1", // nullable, 会在回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

miniProgram类型消息

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 4, // MessageType, check below
  "payload": {
    "appid": "gh_e3b81975fe3c@app",
    "description": "", // optional, can be empty string
    "pagePath": "pages/stat/index.html",
    "thumbKey": "", // optional, can be empty
    "iconUrl": "https://s3.cn-north-1.amazonaws.com.cn/xiaoju-material/public/rc-upload-1585297566308-2_1585297937120_%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E7%BE%A4%E5%8F%91%E5%9B%BE(1).png", // MiniProgram icon
    "thumbUrl": "https://s3.cn-north-1.amazonaws.com.cn/xiaoju-material/public/rc-upload-1585297566308-2_1585297937120_%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E7%BE%A4%E5%8F%91%E5%9B%BE(1).png", // MiniProgram thumbnail
    "title": "北京健康宝",
    "username": "wxfe0e405895cafdf9"
  },
  "externalRequestId": "1", // nullable, 会在发送消息回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

video类型消息(只支持mp4格式)

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 5, // MessageType, check below
  "payload": {
    "url": "https://juzi-work-material-prod.s3.cn-northwest-1.amazonaws.com.cn/public/juziwork_rc-upload-1587696968707-5_5.mp4"
  },
  "externalRequestId": "1", // nullable, 会在回调中原样带回的字段，需要保证唯一（当不唯一时报错）
}

channel(视频号)类型消息

TIP

仅限内测使用，需要联系客服申请内测

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 7,
  "payload": {
     "avatarUrl": "<url>",
     "coverUrl": "<url>",
     "description": "abc",
     "feedType": 4,
     "nickname": "wany",
     "thumbUrl": "<url>",
     "url": "<url>",
     "extras": ""
  },
  "externalRequestId": "1"
}

voice(语音)类型消息

TIP

仅限内测使用，需要联系客服申请内测

语音仅支持silk格式

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 8,
  "payload": {
     "duration": 3.20,
     "voiceUrl": "<url>"
  },
  "externalRequestId": "1"
}

emoticon(表情)类型消息

TIP

仅限内测使用，需要联系客服申请内测

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": 9,
  "payload": {
     "imageUrl": "<url>"
  },
  "externalRequestId": "1"
}

返回格式如下

{
  "code": 0,
  "message": "",
  "data": {
    "requestId": ""
  }
}

code具体原因说明

0: 发送成功

-1: 无效的chatId

-2: 机器人未找到（chatId对应的机器人未找到，可能已经删除）

-3: 机器人不在线

-4: 机器人开启了养号模式，不能使用api发送消息

-6: 只支持mp4格式视频

-7: 当前账号不支持api，需高级版本或者开启api权限

-9: 加入队列失败(即将新增)

requestId具体说明

requestId: 本次发送消息的请求id

chatId为系统中生成的id，需提前获取或一直保存请求中的messageType和payload遵循如下格式，messageType需要和payload格式对应，否则会报错

enum MessageType {
  TEXT = 0,
  IMAGE = 1,
  URL_LINK = 2,
  FILE = 3,
  MINI_PROGRAM = 4,
  VIDEO = 5,
}

文本消息类型payload

{
  "text": "你好啊，我是句子互动的商务", // message content
  "mention": ["wxid_rr9ej1o8xv9h21"] // mention list, when send message to room, can set mention list, nullable
}

图片类型payload

{
  "url": "https://s3.cn-north-1.amazonaws.com.cn/xiaoju-material/public/rc-upload-1585297566308-2_1585297937120_%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E7%BE%A4%E5%8F%91%E5%9B%BE(1).png", // image url
  "size": 1024 // image size, nullable
}

图文链接类型payload

{
  "sourceUrl": "http://mp.weixin.qq.com/s?__biz=MzA3MTA0ODYyOA==&mid=2651161429&idx=1&sn=30ee392b35dc2ac91b9408e3b25dc196&chksm=84c2af8eb3b526986e242cff11e11697dd54350a1b6bfff6082c7973fb51f170876b201bc690&mpshare=1&scene=1&srcid=&sharer_sharetime=1586011571343&sharer_shareid=fc884800739cdc7215d6a289dd736e76#rd", // link address
  "title": "中国顶尖的技术社区们在一个群里，会聊什么", // title
  "summary": "微软加入群聊并发布一条重磅消息" // description
  "imageUrl": "https://mp.weixin.qq.com/mp/qrcode?scene=10000004&size=102&__biz=MzA3MTA0ODYyOA==&mid=2651161429&idx=1&sn=30ee392b35dc2ac91b9408e3b25dc196&send_time=" // thumbnail url
}

文件类型

{
  "name": "句子互动介绍", // display name
  "url": "https://s3.cn-northwest-1.amazonaws.com.cn/xiaoju-message-payload-bucket/message/5cd4dbbf454e8b4cc7b4c496/1576906142438/%E5%8F%A5%E5%AD%90%E7%A7%92%E5%9B%9E%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D.pdf", // file url address
  "size": 1024 // file size, nullable
}

# 接收消息

# 当收到消息时，系统会调用设置好的回调地址

具体的地址为{回调地址}/message，例如配置的是abc.com，则消息回调会调用abc.com/message
地址需要接收一个POST类型的请求，数据为json类型，格式如下

{
  "data": {
    "messageId": "2422188041612737714", // wechat messageId
    "chatId": "5e469a2b8d429806b0fef189", // juzi system chatId
    "avatar": "http://wx.qlogo.cn/mmhead/ver_1/JiceV4HzlY2MAg0ZEfcytbic6GcibRj2FLK6oDFsR4FafVFnPBQ6Kc1Wqur2KmN8ult3Zf4cxqp2L64daRN5V7oWfIk5k4BTDMTqZQVo0Fpsj8/132", // contact or room avatar
    "roomTopic": "我的亲友团", // room topic nullable
    "roomId": "7215325536@chatroom", // room wxid nullable
    "contactName": "小北", // message conact name
    "contactId": "wxid_rr9ej1o8xv9h21",
    "payload": MessagePayload,
    "type": MsgType,
    "timestamp": 1585995128441, // message timestamp
    "token": "5dbe8221fc191f13bc072908", // token
    "botId": "5d0c86971150c017984cee66", // botId
    "contactType": 1,
    "coworker": false, // is coworker or not
    "botId": "5d0c86971150c017984cee77",
    "botWxid": "1688851085873555",
    "botWeixin": "123",
  }
}

# 返回参数说明：

参数	类型	必定存在	备注
messageId	string	否	消息id
chatId	string	是	聊天id（表示一个bot和一个客户）
avatar	string	是	客户或者群头像
roomTopic	string	否	群名
roomId	string	否	群wxid
contactName	string	是	客户名
contactId	string	是	客户wxid
payload	object	是	消息具体内容（详情见下方）
type	number	是	消息类型（详情见下方msgType）
timestamp	number	是	消息的时间（ms）
token	string	是	秒回token
contactType	number	是	客户的类型（详情见下方contactType）
coworker	bool	是	是否为内部员工
botId	string	是	bot的账号id
botWxid	string	是	bot的wxid
botWeixin	string	是	bot的企业微信userId

# 相应的枚举的格式如下

enum msgType {
  Unknown = 0,     // 未知
  Attachment = 1,  // 文件
  Audio = 2,       // 语音
  Contact = 3,     // 名片
  ChatHistory = 4, // 聊天历史
  Emoticon = 5,    // 表情
  Image = 6,       // 图片
  Text = 7,        // 文字
  Location = 8,    // 位置
  MiniProgram = 9, // 小程序
  Money = 10,      // 钱相关
  Recalled = 11,   // 撤回消息
  Url = 12,        // 图文消息
  Video = 13,      // 视频
  RoomInvitation = 9999,  // 入群邀请
  System = 10000,         // 秒回系统消息
  WechatSystem = 10001,   // 企业微信系统消息
}

enum ContactType {
  Unknown = 0,      // 未知类型的联系人
  Individual = 1,   // 微信个人号
  Official = 2,     // 公众号
  Corporation = 3,  // 企业微信号
}

enum GenderType {
  Unknown = 0,    // 未知
  Male    = 1,    // 男
  Female  = 2,    // 女
}

enum RoomInvitationStatus {
  CREATED = 0,    // 已发送
  SUCCESS = 1,    // 成功
  ERROR = 2,      // 失败
}

enum SystemMsgType {
  RECALL_MESSAGE_FAILED = 5,
  ROOM_JOIN_MEMBER = 6,
}

enum WechatSystemPayloadType {
  RoomJoin = 0,     // 入群
  RoomLeave = 1,    // 离群
  RoomTopic = 2,    // 群名称变更
}

# 相应的payload的格式如下

# Unknown类型：

{
  "payload": {
    "content": "",
  }
}

# 参数说明：

参数	类型	必定存在	备注
content	string	是	消息内容转成字符串

# Attachment类型：

{
  "payload": {
    "name": "单.xlsx",
    "fileUrl": "https://xxx95.xlsx",
    "size": 0,
  }
}

# 参数说明：

参数	类型	必定存在	备注
name	string	是	文件名
fileUrl	string	是	文件地址
size	number	否	文件大小

# Audio类型：

{
  "payload": {
    "voiceUrl": "https://xxx.mp3",
    "duration": 2.52,
  }
}

# 参数说明：

参数	类型	必定存在	备注
voiceUrl	string	是	语音地址
duration	number	是	时长

# Contact类型：

{
  "payload": {
    "avatar": "https://xxx";
    "coworker": false;
    "friend": false;
    "gender": 1;
    "wxid": "1688849967837777";
    "name": "我";
    "type": 3;
    "weixin": "wonMj_CgAA2QjLWcRIn3vuFN9b7mj222";
  }
}

# 参数说明：

参数	类型	必定存在	备注
avatar	string	是	头像
coworker	bool	是	是否为内部员工
friend	bool	是	是否为好友
gender	number	是	性别（详情请见GenderType）
wxid	string	是	wxid
name	string	是	名字
type	number	是	类型（详情见下方contactType）
weixin	string	是	微信号/企业微信(名字全拼)

# ChatHistory类型：

{
  "payload": {
    "content": ""
  }
}

# 参数说明：

参数	类型	必定存在	备注
content	string	是	消息内容转成字符串

# Emoticon类型：

{
  "payload": {
    "imageUrl": "https://xxx.gif",
  }
}

# 参数说明：

参数	类型	必定存在	备注
imageUrl	string	是	表情地址

# Image类型：

{
  "payload": {
    "imageUrl": "https://xxx.png",
    "size": 125995,
    "artwork": {
      "url": "https://xxx.png",
      "height": 2000,
      "width": 1440,
    },
  }
}

# 参数说明：

参数	类型	必定存在	备注
imageUrl	string	是	压缩图片地址
size	number	否	图片大小
artwork	object	否	原图数据
artwork.url	string	是	原图地址
artwork.height	number	是	原图高
artwork.width	number	是	原图宽

# Text类型：

{
  "payload": {
    "text": "我通过了你的联系人验证请求，现在我们可以开始聊天了",
  }
}

# 参数说明：

参数	类型	必定存在	备注
text	string	是	消息内容
mention	array	否	被@的人的wxid

# Location类型：

{
  "payload": {
    "content": "",
  }
}

# 参数说明：

参数	类型	必定存在	备注
content	string	是	消息内容转成字符串

# MiniProgram类型：

{
  "payload": {
    "appid": "gh_e3b8eee343c@app",
    "description": "健康宝",
    "pagePath": "pages/stat/index.html",
    "thumbUrl": "https://xxx.png",
    "title": "健康宝",
    "username": "wxfe0e405895ca2323",
    "iconUrl": "http://xxx",
  }
}

# 参数说明：

参数	类型	必定存在	备注
appid	string	是	关联的公众号ID
description	string	是	小程序描述
pagePath	string	是	跳转路径
thumbKey	string	否	封面图加密数据
thumbUrl	string	否	封面图url
title	string	是	小程序标题
username	string	是	小程序ID
iconUrl	string	否	icon地址

# Money类型：

{
  "payload": {
    "content": "",
  }
}

# 参数说明：

参数	类型	必定存在	备注
content	string	是	消息内容转成字符串

# Recalled类型：

{
  "payload": {
    "content": "1069468",
  }
}

# 参数说明：

参数	类型	必定存在	备注
content	string	是	消息id

# Url类型：

{
  "payload": {
    "title": "123",
    "description": "456",
    "thumbnailUrl": "https://xxxx.png",
    "url": "https://xxx/user/login",
  }
}

# 参数说明：

参数	类型	必定存在	备注
title	string	是	标题
description	string	是	描述
thumbnailUrl	string	是	封面图地址
url	string	是	跳转地址

# Video类型：

{
  "payload": {
    "videoUrl": "https://xxx.MP4",
  }
}

# 参数说明：

参数	类型	必定存在	备注
videoUrl	string	是	视频地址
duration	number	否	时长
thumbnailUrl	string	否	封面图地址

# RoomInvitation类型：

{
  "payload": {
    "roomTopic": "测试群聊",
    "avatarUrl": "https://xxx",
    "invitaterName": "black sheep",
    "inviteModelId": "",
    "inviteStatus": 0,
  }
}

# 参数说明：

参数	类型	必定存在	备注
roomTopic	string	是	群名
avatarUrl	string	是	群头像
invitaterName	string	是	邀请者名字
inviteModelId	string	否	邀请者记录id
inviteStatus	number	否	邀请状态（详情见RoomInvitationStatus）

# System类型：

{
  "payload": {
    "type": SystemMsgType,
    "subPayload": SystemSubPayload,
  }
}

SystemSubPayload

{
  "RecallFailedPayload": {
    "messageId": string,
  }

  "RoomJoinMemberPayload": {
    "memberNames": string[],
    "inviterName": string,
  }
}

# 参数说明：

参数	类型	必定存在	备注
type	number	是	类型（详情见SystemMsgType）
subPayload	object	是	详情
RecallFailedPayload.messageId	string	否	消息id
RoomJoinMemberPayload.memberNames	array	否	入群联系人名字
RoomJoinMemberPayload.inviterName	string	否	邀请者姓名

# WechatSystem类型：

{
  "payload": {
    "wechatSystemPayloadType": WechatSystemPayloadType,
    "subPayload": WechatSystemSubPayload,
  }
}

WechatSystemSubPayload

{
  "RoomJoinPayload": {
    "inviter": ContactInRoomSystemMessage,
    "inviteeList": ContactInRoomSystemMessage[],
    "timestamp": number,
  }

  "RoomLeavePayload": {
    "remover": ContactInRoomSystemMessage,
    "leaverList": ContactInRoomSystemMessage[],
    "timestamp": number,
  }

  "RoomTopicPayload": {
    "oldTopic": string,
    "newTopic": string,
    "changer": ContactInRoomSystemMessage,
    "timestamp": number,
  }
}

ContactInRoomSystemMessage

{
  "ContactInRoomSystemMessage": {
    "wxid": string,
    "isSelf": boolean,
    "displayName": string,
  }
}

# 参数说明：

参数	类型	必定存在	备注
wechatSystemPayloadType	number	是	类型（详情见WechatSystemPayloadType）
subPayload	object	是	详情
ContactInRoomSystemMessage.wxid	string	否	wxid
ContactInRoomSystemMessage.isSelf	string	否	是否是bot自己
ContactInRoomSystemMessage.displayName	string	否	展示名称
RoomJoinPayload.inviter	object	是	邀请者信息
RoomJoinPayload.inviteeList	array	是	被邀请者信息
RoomJoinPayload.timestamp	number	是	时间戳
RoomLeavePayload.remover	object	否	踢人者
RoomLeavePayload.leaverList	array	是	被踢者信息
RoomLeavePayload.timestamp	number	是	时间戳
RoomTopicPayload.oldTopic	string	否	旧群名
RoomTopicPayload.newTopic	string	是	新群名
RoomTopicPayload.changer	object	是	修改者信息
RoomTopicPayload.timestamp	number	是	时间戳

# 获取托管企业微信列表

# GET https://ex-api.botorange.com/bot/list

参数：

token, // 必选

参数需要通过url传入，例如：

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

返回数据为json格式，具体格式如下：

{
  "code": 0,
  "data": [
    {
      "id": "60541d4fd28931d5f9f617ff",
      "wxid": "1688853462929494",
      "weixin": "MiRenDeHaiYang",
      "nickName": "迷人的海洋",
      "avatar": "https://wework.qpic.cn/bizmail/wE1wZT8dKWr2jcpjCNC9fDXzjQKcq8CRew9cj4cog4nFDm9z6SibVFw/0",
      "online": true
    }
  ]
}

# 返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码
data	array	是	托管企业微信数据
data.id	string	是	托管企业微信的账号ID
data.wxid	string	是	托管企业微信的wxid，在企业微信内唯一
data.weixin	string	是	托管企业微信的userId，可与企业微信API的userId一一对应
data.nickName	string	是	托管企业微信的昵称
data.avatar	string	是	托管企业微信的头像
data.online	boolean	是	托管企业微信是否在线

# 获取联系人列表

# GET https://ex-api.botorange.com/contact/list

此接口为分页接口，单页最大100条，需要自行翻页获取所有数据

参数：

token, // 必选
current, // 可选，默认为0，即第一页
pageSize, // 可选，默认为10，最大为100
wxid, // 可选，用来搜索某wxid的用户，当传入此参数时，current 和 pageSize 失效

参数需要通过url传入，例如：

GET https://ex-api.botorange.com/contact/list?token={your-token}&current=1&pageSize=4

上面这条请求会查询第5-8条数据，即每页四条，第二页的数据

GET https://ex-api.botorange.com/contact/list?wxid=wxid_xxxxx

上面这条请求会查询 wxid 为 wxid_xxxxx 的用户

返回数据为json格式，具体格式如下：

{
  "code": 0,
  "data": [
    {
      "chatId": "5dbe8287184b7cb41f5265ce",
      "botInfo": {
        "wxid": "wxid_rr9ej1o8xv9h21",
        "weixin": "iguxiaobei",
        "nickName": "小北"
      },
      "wxid": "wxid_rr9ej1o8xv9h20",
      "weixin": "kx930418",
      "nickName": "联系人昵称",
      "alias": "联系人备注",
      "avatarUrl": "http://wx.qlogo.cn/mmhead/ver_1/rIMjtIkM3fRnugJcOj9AA9BiaPpIWRia9SaxNPXMLMSj0zcBKIvboibaReOakDbicUzk3B24o87AXwSX4yibtFXicLiaA/132",
      "city": "Haidian",
      "province": "Beijing",
      "gender": 2,
      "labels": [
        {
          "id": "5eda03260e21f35ca20f9eb4",
          "name": "同事"
        }
      ],
      "contactType": 1,
      "coworker": false,
      "unionId": "xxxxxxx",
      "externalUserId": "xxxxxxxx",
      "deleted": false
    }
  ],
  "page": {
    "current": 1,
    "total": 428
  }
}

# 返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码
data	array	是	联系人数据
data.chatId	string	是	该联系人的对话ID
data.botInfo	object	是	所属微信信息
data.botInfo.wxid	string	是	所属微信的wxid
data.botInfo.weixin	string	是	所属微信的userId，可与企业微信API的userId一一对应
data.botInfo.nickName	string	是	所属微信昵称
data.wxid	string	是	wxid，该id在微信里唯一
data.weixin	number	否	userId
data.nickName	string	是	昵称
data.alias	string	否	备注
data.avatarUrl	string	是	头像
data.city	string	否	的省份信息
data.province	string	否	的城市信息
data.gender	number	是	性别，0 - 未知，1 - 男，2 - 女
data.labels	array	是	秒回标签信息
data.labels.id	array	是	秒回标签id
data.labels.name	array	是	秒回标签名字
data.contactType	number	否	联系人类型，0 - 未知，1 - 微信，2 - 公众号，3 - 企业微信
data.coworker	boolean	否	是否为同事（同一个企业下的员工）
data.unionId	string	否	该联系人对应的unionId，该值只有在关联了企业控制台，此联系人数据在企业控制台和秒回间打通，并且当前企业微信的企业绑定了微信开放平台才可返回
data.deleted	boolean	否	是否已删除
data.externalUserId	string	否	该联系人对应的externalUserId，该值只有在关联了企业控制台，此联系人数据在企业控制台和秒回间打通才可返回

# 获取群列表

# GET https://ex-api.botorange.com/room/list

此接口为分页接口，单页最大100条，需要自行翻页获取所有数据

参数：

token, // 必选
current, // 可选，默认为0，即第一页
pageSize, // 可选，默认为10，最大为100
wxid, // 可选，用来搜索某 wxid 的群，当传入此参数时，current 和 pageSize 失效

参数需要通过url传入，例如：

GET https://ex-api.botorange.com/room/list?token={your-token}&current=2&pageSize=5

上面这条请求会查询第11-15条数据，即每页五条，第三页的数据

GET https://ex-api.botorange.com/room/list?wxid=chatroom@xxx

上面这条请求会查询 wxid 为 chatroom@xxx 的群

返回数据为json格式，具体格式如下：

{
  "code": 0,
  "data": [
    {
      "chatId": "5dbe8287184b7cb41f52674e",
      "botInfo": {
        "wxid": "wxid_rr9ej1o8xv9h21",
        "weixin": "iguxiaobei",
        "nickName": "小北"
      },
      "wxid": "11293954269@chatroom",
      "topic": "大街小巷程序员",
      "avatarUrl": "http://wx.qlogo.cn/mmcrhead/WibBib8GYLV5M0UyNUyX4SA5zf5cCzOjsCG3Z1HWA1hneVfQfTIPygia6ibN31LSWqG1jFe0zXZSujPp4CwhBibXpxeQPnDp3LEYN/0",
      "ownerId": "wxid_rr9ej1o8xv9h21",
      "members": [
        {
          "wxid": "kx23498",
          "nickName": "群成员昵称",
          "avatarUrl": "http://wx.qlogo.cn/mmhead/ver_1/3mtHGNE50ZpxZX3SMwqibluNAz5GgiaAVLyzyc3Ex0TThpfrVUibnKiagiciaP5jeO2f6wYAuiaW5cXjKhsgbAHzCzNs4V4uibzLkxr0z3XaluTRGUc/132",
          "roomAlias": null,
          "isFriend": true,
          "contactType": 1,
          "coworker": false // is coworker or not
        }
      ],
      "labels": [
        {
          "id": "5eda03260e21f35ca20f9eb4",
          "name": "VIP客户群"
        }
      ],
      "wecomChatId": "wrrRhyBgAAGf2Wo90zgjmNspXj4y8pQA", // 如果需要该值, 需要联系售后申请内测升级
    }
  ],
  "page": {
    "current": 1,
    "total": 107
  }
}

# 返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码
data	array	是	群数据
data.chatId	string	是	该群组的对话id
data.botInfo	object	是	所属微信信息
data.botInfo.wxid	string	是	所属微信的wxid
data.botInfo.weixin	string	是	所属微信的userId，可与企业微信API的userId一一对应
data.botInfo.nickName	string	是	所属微信昵称
data.wxid	string	是	wxid，该id在微信里唯一
data.topic	string	是	群名称
data.avatarUrl	string	是	群头像
data.ownerId	string	是	群主wxid
data.members	array	是	群成员
data.members.wxid	string	是	群成员wxid
data.members.nickName	string	是	群成员昵称
data.members.avatarUrl	string	是	群成员头像url
data.members.roomAlias	string	是	群成员在群中的昵称
data.members.isFriend	boolean	是	该成员是否和所属微信是好友
data.members.contactType	number	否	联系人类型，0 - 未知，1 - 微信，2 - 公众号，3 - 企业微信
data.members.coworker	boolean	否	是否为同事（同一个企业下的员工）
data.members.corporation	string	否	该客户所属企业名
data.labels	array	是	秒回标签
data.labels.id	string	是	秒回标签id
data.labels.name	string	是	秒回标签名称
data.wecomChatId	string	否	企业微信群官方id。如果需要该值, 需要联系售后申请内测升级
page	object	是	分页信息
page.current	number	是	当前页数
page.total	number	是	总数

注：该接口于2021-04-13号增加了 contactType 和 coworker 字段，但此数据需要系统重新同步才会存在注2：该接口于2021-11-27号增加了 corporation 字段，但此数据需要系统重新同步才会存在所以对于 2021-04-13 和 2021-11-27 之前存在的账号，如果需要返回此字段，需要手动在秒回后台的【客户管理】页面点击【同步群聊】按钮来同步数据，之后才可以获取到这两个新增字段

# 获取群列表（不包含成员信息）

# GET https://ex-api.botorange.com/room/simpleList

此接口为分页接口，单页最大100条，需要自行翻页获取所有数据

参数：

token, // 必选
current, // 可选，默认为0，即第一页
pageSize, // 可选，默认为10，最大为100
wxid, // 可选，用来搜索某 wxid 的群，当传入此参数时，current 和 pageSize 失效

参数需要通过url传入，例如：

GET https://ex-api.botorange.com/room/list?token={your-token}&current=2&pageSize=5

上面这条请求会查询第11-15条数据，即每页五条，第三页的数据

GET https://ex-api.botorange.com/room/list?wxid=chatroom@xxx

上面这条请求会查询 wxid 为 chatroom@xxx 的群

返回数据为json格式，具体格式如下：

{
  "code": 0,
  "data": [
    {
      "chatId": "5dbe8287184b7cb41f52674e",
      "botInfo": {
        "wxid": "wxid_rr9ej1o8xv9h21",
        "weixin": "iguxiaobei",
        "nickName": "小北"
      },
      "wxid": "11293954269@chatroom",
      "topic": "大街小巷程序员",
      "avatarUrl": "http://wx.qlogo.cn/mmcrhead/WibBib8GYLV5M0UyNUyX4SA5zf5cCzOjsCG3Z1HWA1hneVfQfTIPygia6ibN31LSWqG1jFe0zXZSujPp4CwhBibXpxeQPnDp3LEYN/0",
      "ownerId": "wxid_rr9ej1o8xv9h21",
      "memberCount": 10,
      "labels": [
        {
          "id": "5eda03260e21f35ca20f9eb4",
          "name": "VIP客户群"
        }
      ],
      "wecomChatId": "wrrRhyBgAAGf2Wo90zgjmNspXj4y8pQA" // 如果需要该值, 需要联系售后申请内测升级
    }
  ],
  "page": {
    "current": 1,
    "total": 107
  }
}

# 返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码
data	array	是	群数据
data.chatId	string	是	该群组的对话id
data.botInfo	object	是	所属微信信息
data.botInfo.wxid	string	是	所属微信的wxid
data.botInfo.weixin	string	是	所属微信的userId，可与企业微信API的userId一一对应
data.botInfo.nickName	string	是	所属微信昵称
data.wxid	string	是	wxid，该id在微信里唯一
data.topic	string	是	群名称
data.avatarUrl	string	是	群头像
data.ownerId	string	是	群主wxid
data.memberCount	int	是	群成员数量
data.labels	array	是	秒回标签
data.labels.id	string	是	秒回标签id
data.labels.name	string	是	秒回标签名称
data.wecomChatId	string	否	企业微信群官方id。如果需要该值, 需要联系售后申请内测升级
page	object	是	分页信息
page.current	int	是	当前页数
page.total	int	是	总数

# 获取原图

# 获取原图url为 https://ex-api.botorange.com/message/getArtworkImage

发送POST请求，请求数据为json格式，如下

{
  "chatId": "bcdw2j234ko1",
  "token": "abcd",
  "messageId": "8466788600329921944"
}

返回格式如下

{
  "code": 0,
  "data": {
    "url": "http://img.botorange.com/2340afaksf.png",
    "height": 1148,
    "width": 1194
  }
}

# 创建群发

注意

若使用unionId方式创建群发，需确认秒回端客户已完成union ID打通，可通过回调或者通过接口获取到chatId进行打通确认
创建群发接口需要说明最大传入的wxid或者unionId的总长度为1000，如果需要群发超过1000人，则需要重复调用接口来传入数据。创建群发任务，当人数过多时需要分页。通过hasMore字段传入true, 会将多组成员数据组合在一起。
多次调用接口创建群发时，非第一次调用接口时，需要带着id的参数，否则会创建出多个独立的群发。
多次调用接口创建任务时，后传入的messages字段会覆盖之前传入的值。当接收到hasMore为false或不存在时，为结束标志。
当群发任务全部成功时，会自动归档。当群发任务有失败的对象时，不会自动归档，需调用取消api接口或者在群发界面点击取消按钮。
每一次接收到messages，都会在公司话术的"api群发"组中新建一个素材，便于界面显示以及后续对于群发详细信息进行复核。
分页创建群发时需要在10分钟内完成。

# POST https://ex-api.botorange.com/broadcast/create

发送POST请求，请求数据为json格式，如下

{
    "id": "5c69d33cac3d075a57657ed6",
    "token": "abcd",
    "messages": [{
      "type": 0, // MessageType, check below
      "payload": {
        "text": "你好啊，我是句子互动的商务", // message content
        "mention": ["wxid_rr9ej1o8xv9h21"], // mention list, when send message to room, can set mention list, nullable
      },
      "isAnnouncement": false
    }],
    "scheduledTimestamp": 1597903969925,
    "members": [{
      "botUserId": "5d0c86971150c017984cee66",
      "wxids": ["788748399949943"],
      "unionIds": ["ozynqsulJFCZ2z1aYeS8h-nuasdAAA"],
    }],
    "hasMore": false,
    "type": 5
}

名称	类型	是否必须	备注
id	string	否	群发id，分页后续必传
token	string	是	调用接口凭证
type	string	是	5私聊 6群聊
hasMore	boolean	否	当分页时为true，最后一个是false或者不传
scheduledTimestamp	number	否	（毫秒）当定时任务时必传，否则不传
messages	array	否	当hseMore不传或者为false时，必须存在一组messages,多存在多组时,后面会覆盖前面的messages
messages.type	number	是	参考发送消息的messageType
messages.payload	object	是	参考发送消息的payload
messages.isAnnouncement	boolean	否	表示该条消息是群公告（需保证一次群发只允许有一条群公告消息），只在type是群聊且机器人为群主时生效
members	array	是	发送对象
members.botUserId	string	是	机器人的userId
members.wxids	array	否(和unionIds二选一)	该机器人发送对象的wxid列表,多组时会整合去重. 当wxids存在时, unionId无效
members.unionIds	array	否(和wxids二选一)	该机器人发送对象的unionId列表,多组时会整合去重. 当wxids存在时, unionId无效

返回格式如下

{
    "code": 0,
    "data": {
      "id": "5c69d33cac3d075a57657ed6",
      "memberNumber": 1,
      "scheduledTimestamp": 1597903969925,
      "isCreated": false,
      "messageNumber": 1,
      "failedMembers": [{
        "botUserId": "5d0c86971150c017984cee66",
        "wxids": ["788748399949943"],
        "unionIds": ["ozynqsulJFCZ2z1aYeS8h-nuasdAAA"]
      }],
      "failedMemberCount": 0
    }
}

名称	类型	是否必须	备注
id	string	否	群发id
memberNumber	number	是	群发对象人数
scheduledTimestamp	number	否	（毫秒）定时任务时存在
isCreated	boolean	否	该群发是否创建成功
messageNumber	number	是	发送消息数
failedMembers	array	否	未创建成功的成员,参数参照请求的members字段
failedMemberCount	number	否	未创建成功的成员数量

# 错误码说明：

错误码	说明
-1	群发任务不存在
-2	群发任务已开始
-3	wxid或者unionId长度超过限制
-4	未找到发送的消息
-5	未找到发送的对象
-6	指定群公告的消息数量超过1条
-7	指定群公告的消息消息类型不是文本

# 重发群发

该接口只允许对api创建且发送完成，未归档但是有失败的群发任务进行群发。

# POST https://ex-api.botorange.com/broadcast/resend

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}

名称	类型	是否必须	备注
id	string	是	群发id
token	string	是	调用接口凭证

返回格式如下

{
  "code": 0
}

# 错误码说明：

错误码	说明
-1	群发任务不存在
-2	群发任务的状态不可以重发

# 取消群发

该接口只允许取消发送中的群发，会自动取消群发并归档，如未发送的定时群发，请调用删除群发接口。

# POST https://ex-api.botorange.com/broadcast/cancel

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}

名称	类型	是否必须	备注
id	string	否	群发id
token	string	是	调用接口凭证

返回格式如下

{
  "code": 0
}

# 错误码说明：

错误码	说明
-1	群发任务不存在
-2	群发任务的状态不可以取消

# 删除群发

删除未发送的定时任务。

# POST https://ex-api.botorange.com/broadcast/delete

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}

名称	类型	是否必须	备注
id	string	否	群发id
token	string	是	调用接口凭证

返回格式如下

{
  "code": 0
}

# 错误码说明：

错误码	说明
-1	群发任务不存在
-2	群发任务的不可以删除

# 群发回调

群发结果通知，在群发任务结束时进行回调。会进行重试5次，间隔分别是1s, 5s, 30s, 1min

# POST ***/broadcast/result

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "successTotal": 10,
  "failedTotal": 10,
  "startTimestamp": 1597903969925,
  "endTimestamp": 1597903969925,
  "scheduleTimestamp": 1597903969925
}

名称	类型	是否必须	备注
id	string	是	群发id
successTotal	number	是	群发成功对象数
failedTotal	number	是	群发失败对象数
startTimestamp	number	是	（毫秒）群发开始时间
endTimestamp	number	是	（毫秒）群发结束时间
scheduleTimestamp	number	否	（毫秒）群发定时时间，定时任务存在

返回格式如下

{
  "code": 0
}

# 获取群发任务的失败列表

获取群发失败列表接口，可以获取到群发任务的发送失败的对象信息。

# GET https://ex-api.botorange.com/broadcast/failedList?id=5c69d33cac3d075a57657ed6&current=1&pageSize=10&token=abcd

名称	类型	是否必须	备注
id	string	否	群发id
token	string	是	调用接口凭证
current	string	是	页数从1开始
pageSize	string	是	每页个数，最大不超过500

返回格式如下

{
  "code": 0,
  "data": [
    {
      "botUserId": "5d0c86971150c017984cee66",
      "wxid": "788748399949943",
      "unionId": "ozynqsulJFCZ2z1aYeS8h-nuasdAAA",
      "errorMsg": "",
      "errorCode": 0
    }
  ]
}

名称	类型	是否必须	备注
botUserId	string	否	机器人的userId
wxid	string	是	群发对象的wxid
unionId	string	否	群发对象的unionId
errorCode	number	是	错误码，详情参见
errorMsg	string	是	错误描述，详情参见

# 错误码说明：

错误码	说明
-1	群发任务不存在
-2	每页长度超过限制

# 加入、同步群事件回调

Bot加入群或同步到群组回调

TIP

加入群事件只会在BOT运行过程中被捕捉
同步事件会在BOT启动时以及成员同步群信息时被捕捉

POST ***/chatroom/joined #加入群事件
###
POST ***/chatroom/loaded #同步到群事件

# 回调请求Body

{
  "chatId": "5dbe8287184b7cb41f52674e",
  "botInfo": {
    "wxid": "string",
    "weixin": "string",
    "nickName": "string"
  },
  "wxid": "string",
  "topic": "string",
  "avatarUrl": "string",
  "ownerId": "string",
  "members": [
    {
      "wxid": "string",
      "nickName": "string",
      "avatarUrl": "string",
      "roomAlias": "string | null",
      "isFriend": "boolean",
      "contactType": "number",
      "coworker": "boolean"
    }
  ],
  "group": "string",
  "syncedTime": "number"
}

名称	类型	是否必须	备注
chatId	string	是	群组的对话id
botInfo	Model	是	触发事件的Bot信息
botInfo.wxid	string	是	触发事件的Bot wxid
botInfo.weixin	string	是	触发事件的Bot weixin
botInfo.nickName	string	是	触发事件的Bot 昵称
wxid	string	是	群wxid
topic	string	是	群名称
avatarUrl	string	是	群头像地址
ownerId	string	是	拥有者wxid
members	List	是	群内成员信息
members.wxid	string	是	成员wxid
members.nickName	string	是	成员昵称
members.avatarUrl	string	是	成员头像地址
members.roomAlias	string/null	是	成员备注
members.isFriend	string	是	是否为好友
members.contactType	number	是	联系人类型
members.coworker	boolean	是	是否为同事
group	string	是	群聊所属群组id
syncedTime	string	是	BOT获取到同步信息的时间

# 加入群聊

### POST https://ex-api.botorange.com/room/addMember

# 请求示例：

{
  "token": "abcd",
  "botUserId": "testUserId",
  "contactWxid": "7888888888",
  "roomWxid": "R:888888"
}

# 请求参数：

名称	类型	是否必须	备注
token	string	是	调用接口凭证，秒回token
botUserId	string	是	需要执行添加的托管微信的userId
contactWxid	string	是	需要被添加的群成员的wxid
roomWxid	string	是	需要被添加的群的wxid

注意

1.使用userId进行添加群聊时，无法保证当前微信组下该userId仅在一有一个账号，如果以当前userId查到了不止一个托管账号，则会报错 2.群人数40人之前默认拉入群聊，40人以后发送入群卡片链接，需要客户点击确认 3.建议拉人进群时，每分钟不超过50次

# 返回示例：

{
  "code": 0,
  "message": ""
}

# 返回参数说明：

参数	类型	必定存在	备注
code	number	是	返回码
message	string	是	对返回码的文本描述内容

# 错误码：

错误码	说明
-2	botUserId的bot不存在
-3	botUserId存在多个机器人
-4	不是企业微信
-5	bot不在线
-6	群聊加载失败
-7	拉入群聊失败
-8	和bot不是好友关系
-9	群聊中已经存在此好友
-10	群人数达到上限(500)
-11	bot不在群内
-12	该群是内部群，不执行此操作

# 创建群聊

POST https://ex-api.botorange.com/room/create

# 请求示例：

{
  "token": "5f60998462c907003e1fa2c1",
  "botUserId": "testUserId",
  "userIds": [
    "zhangsan"
  ],
  "unionIds": [
    "ozynqsulJFCZ2z1aYeS8h-nuasdAAA"
  ],
  "name": "create",
  "greeting": "大家好，这个是新的群",
  "wxids": [
    "wmrRhyBgAA6PKOL7IA2Nbikedjxxxxxx",
    "wmrRhyBgAANQ1O34HRXfVQh17exxxxxx"
  ]
}

# 请求参数：

名称	类型	是否必须	备注
token	string	是	秒回调用接口凭证
botUserId	string	是	需要执行建群的托管微信的userId
userIds	string array	是	建群时需要拉入的企业成员的userId
unionIds	string array	否	建群时需要拉取的外部联系人的unionId
name	string	否	建群后新的群的名字
greeting	string	是	建群后的激活语
wxids	string array	否	建群时需要拉取的联系人的wxid

注意

使用userId进行建群时，无法保证当前企业下该userId仅在一个微信组内托管了一次，如果以当前userId查到了不止一个托管账号，则会报错。

创建群聊时 unionIds 和 wxids 联系人组合的总人数应位于2～40之间，两个参数可以共存。

# 返回示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "chatId": "wrG3O4AAAAA8bbFkg5q6q0M0Sdp-QQQQ",
    "roomWxid": "R:888888888"
  }
}

# 返回参数说明：

参数	类型	必定存在	备注
errcode	number	是	返回码
errmsg	string	是	对返回码的文本描述内容
data.chatId	string	是	创建的群聊的chatId
data.roomWxid	string	是	创建的群聊的wxid

# 错误码：

错误码	说明
-1	无效token
-2	botUserId的bot不存在
-3	botUserId存在多个机器人
-4	不是企业微信
-5	bot不在线
-6	同事不存在
-7	contact不存在
-8	contact加载失败
-9	创建群聊失败
-10	创建群人数不足

# 发送秒回通知

POST https://ex-api.botorange.com/mhNotice/send

# 请求示例：

{
  "token": "5f60998462c907003e1fa2c1",
  "content": "通知内容",
  "title": "通知标题",
  "time": 30
}

# 请求参数：

名称	类型	是否必须	备注
token	string	是	秒回调用接口凭证
content	string	是	通知内容
title	string	否	通知标题，可以不存在
time	number	否	通知展示时长（单位秒）, 如果为0或者不传则不会自动关闭

注意

小组成员登录秒回且网页端打开时，才会显示提醒。刷新网页/关闭浏览器会导致通知消息全部关闭。

# 返回示例：

{
  "code": 0
}

← 小组控制台发送消息回调接口小组控制台接口 v1 (Beta) →