# 句子秒回接口(legacy)

# 关于token

在句子秒回上添加微信号并扫码登录以后,在智能对话 ==> API接入页面即可找到自己的token

# 关于频率限制

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

# 发送消息

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

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

  1. 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, 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}
  1. 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, 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}
  1. 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, 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}
  1. 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, 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}
  1. 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, 会在发送消息回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}
  1. 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, 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错)
}

返回格式如下

{
  "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,需提前获取或一直保存 请求中的messageTypepayload遵循如下格式,messageType需要和payload格式对应,否则会报错

enum MessageType {
  TEXT = 0,
  IMAGE = 1,
  URL_LINK = 2,
  FILE = 3,
  MINI_PROGRAM = 4,
  VIDEO = 5,
}
  1. 文本消息类型payload
{
  "text": "你好啊,我是句子互动的商务", // message content
  "mention": ["wxid_rr9ej1o8xv9h21"] // mention list, when send message to room, can set mention list, nullable
}
  1. 图片类型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
}
  1. 图文链接类型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
}
  1. 文件类型
{
  "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客户群"
        }
      ]
    }
  ],
  "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 秒回标签名称
page object 分页信息
page.current number 当前页数
page.total number 总数

注:该接口于2021-04-13号增加了 contactTypecoworker 字段,但此数据需要系统重新同步才会存在 注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客户群"
        }
      ]
    }
  ],
  "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 秒回标签名称
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字段会覆盖之前传入的值。当接收到hasMorefalse或不存在时,为结束标志。
  • 当群发任务全部成功时,会自动归档。当群发任务有失败的对象时,不会自动归档,需调用取消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查到了不止一个托管账号,则会报错。

创建群聊时 unionIdswxids 联系人组合的总人数应位于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
}
最近更新: 2022/3/18 下午10:22:30