消息接口

发送消息

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

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

请求示例:

{
  "chatId": "5e38ef8054eed1179f904f8e",
  "token": "5df7649ae44570065a78f337",
  "messageType": MessageType,
  "payload": MessagePayload,
  "externalRequestId": "1",
}

请求参数:

名称类型是否必须备注
tokenstring调用接口凭证,通过query传入, 获取方式
chatIdstring客户或者群 与托管账号关系的唯一id, 详见客户chatId群聊chatId
messageTypeMessageType消息类型
payloadMessagePayload消息的payload
externalRequestIdstring会在回调中原样带回的字段,需要保证唯一(当不唯一时报错),幂等

消息类型

enum MessageType {
  TEXT = 0,
  IMAGE = 1,
  URL_LINK = 2,
  FILE = 3,
  MINI_PROGRAM = 4,
  VIDEO = 5,
  CHANNEL = 7,
  VOICE = 8,
  EMOTICON = 9,
  LOCATION = 10,
}

type MessagePayload =
  TextPayload |
  ImagePayload |
  UrlPayload |
  FilePayload |
  MiniProgramPayload |
  VideoPayload |
  ChannelPayload |
  VoicePayload |
  EmoticonPayload |
  LocationPayload;

消息结构

1. text类型消息

interface TextPayload {
  text: string,
  mention?: string[],
}

参数说明:

参数类型必定存在备注
textstring消息内容
mentionarray@人的wxid列表, @all 可以@所有人
wecomMentionarray被@的人的externalUserId (仅在通过企微id接口时,才可以传入该字段)

2. image类型消息

interface ImagePayload {
  url: string,
  size?: number,
}

参数说明:

参数类型必定存在备注
urlstring图片地址
sizenumber图片大小

3. link类型消息

interface UrlPayload {
  sourceUrl: string,
  title: string,
  summary: string,
  imageUrl: string,
}

参数说明:

参数类型必定存在备注
sourceUrlstring跳转地址
titlestring标题
summarystring描述
imageUrlstring封面图地址

4. file类型消息

interface FilePayload {
  name: string,
  url: string,
  size?: number,
}

参数说明:

参数类型必定存在备注
namestring文件名
urlstring文件地址
sizenumber文件大小

5. miniProgram类型消息

interface MiniProgramPayload {
  appid: string,
  description: string,
  pagePath: string,
  thumbUrl: string,
  title: string,
  username: string,
  iconUrl?: string,
}

参数说明:

参数类型必定存在备注
appidstring关联的公众号ID(使用小程序appid发送消息, 接受到的小程序无法正常打开). 企微格式要求
descriptionstring描述
pagePathstring跳转地址
thumbUrlstring封面图地址
titlestring标题
usernamestring小程序ID
iconUrlstringicon地址

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

interface VideoPayload {
  url: string,
}

参数说明:

参数类型必定存在备注
urlstring视频地址

7. channel(视频号)类型消息

TIP

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

interface ChannelPayload {
  avatarUrl: string,
  coverUrl: string,
  description: string,
  feedType: number,
  nickname: string,
  thumbUrl: string,
  url: string,
  extras: string,
}

参数说明:

参数类型必定存在备注
avatarUrlstring头像地址
coverUrlstring封面地址
descriptionstring描述
feedTypenumber未知, 目前固定为4
nicknamestring昵称
thumbUrlstring缩略图地址
urlstring视频号地址
extrasstring未知, 请使用收到的字段信息

8. voice(语音)类型消息

TIP

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

interface VoicePayload {
  voiceUrl: string,
  duration?: number,
}

参数说明:

参数类型必定存在备注
voiceUrlstring语音地址,目前仅支持silk格式的语音文件
durationnumber时长(秒)

9. emoticon(表情)类型消息

TIP

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

interface EmoticonPayload {
  imageUrl: string,
}

参数说明:

参数类型必定存在备注
imageUrlstring图片地址

10. location(位置)类型消息

TIP

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

interface LocationPayload {
  accuracy: number,
  address: string,
  latitude: number,
  longitude: number,
  name: string,
}

参数说明:

参数类型必定存在备注
accuracynumber精确度 默认为15
addressstring地址描述
latitudenumber维度,北纬为正数
longitudenumber经度,东经为正数
namestring地址名

返回格式如下

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

参数说明:

参数类型必定存在备注
codenumber返回错误码
messagestring错误描述
data.requestIdstring本次发送消息的请求id

code具体原因说明

0: 发送成功

-1: 无效的chatId

-2: 机器人未找到(chatId对应的机器人未找到,可能已经删除)

-3: 机器人不在线

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

-6: 只支持mp4格式视频

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

-9: 加入队列失败

通过企微id发送消息

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

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

请求示例:

{
  "wecomUserId": "5e38ef8054eed1179f904f8e",
  "externalUserId": "xxxxxxxx",
  "wecomChatId": "xxxxxxxx",
  "token": "5df7649ae44570065a78f337",
  "messageType": MessageType,
  "payload": MessagePayload,
  "externalRequestId": "1",
}

请求参数:

名称类型是否必须备注
tokenstring调用接口凭证,通过query传入, 获取方式
wecomUserIdstring员工企微userId, 详见wxUserId
externalUserIdstring客户企微id, 详见externalUserId
wecomChatIdstring客户群企微id, 详见wecomChatId
messageTypeMessageType消息类型
payloadMessagePayload消息的payload
externalRequestIdstring会在回调中原样带回的字段,需要保证唯一(当不唯一时报错),幂等

参数说明:

参数类型必定存在备注
codenumber返回错误码
messagestring错误描述
data.requestIdstring本次发送消息的请求id

code具体原因说明

0: 发送成功

-1: 无效的chatId

-2: 机器人未找到(chatId对应的机器人未找到,可能已经删除)

-3: 机器人不在线

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

-6: 只支持mp4格式视频

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

-9: 加入队列失败

接收消息

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

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

消息格式

{
  "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 contact 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
  "botWxid": "1688851085873555",
  "botWeixin": "123",
  "source": 1,
  "sendBy": "",
  "isSelf": true,
  "mentionSelf": false,
  "externalUserId": "wmrRhyBgAAUvbnJ0ZSlOrzN0pwR9XEZw",
  "roomWecomChatId": "wrrRhyBgAAKwcuh20eNTBWx1wwK-I-_w",
}

返回参数说明:

参数类型必定存在备注
messageIdstring消息id
chatIdstring聊天id(表示一个bot和一个客户)
avatarstring客户或者群头像
roomTopicstring群名
roomIdstring群wxid, 详见roomWxid
contactNamestring客户名
contactIdstring客户wxid, 详见contactWxid
payloadobject消息具体内容(详情见下方
typenumber消息类型(详情见下方msgType
timestampnumber消息的时间(ms)
tokenstring秒回token
contactTypenumber客户的类型(详情见下方contactType
coworkerbool是否为内部员工
botIdstringbot的账号id, 详见botId
botWxidstringbot的wxid, 详见imBotId
botWeixinstringbot的企业微信userId, 详见wxUserId
sourceMessageSource消息来源,具体来源信息参考下面的枚举定义
sendBystring消息发送者的秒回id,仅当消息为消息为托管账号发送的,且消息来源为小组级控制台手动发消息时有效
isSelfbool消息是否是托管账号自己发送的消息
mentionSelfboolean此条消息是否 @ 了托管账号
chatExternalUserIdstring当发送消息是托管账号的时候,且是私聊的时候,这个值存在,且这个值是接收消息的联系人的 externalUserId。这个字段是为了解决自己发送的消息,externalUserId 是托管账号自己的场景
externalUserIdstring发送当前这条消息的人的 externalUserId,当这条消息是托管账号自己发出的时候,这个值是托管账号的 wxUserId
roomWecomChatIdstring当消息发生在群里的时候,这个值存在,它是这个群的明文的企微官方 chatId

相应的枚举的格式如下

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,    // 群名称变更
}

enum MessageSource {
  PHONE = 0,          // 手机推送过来的消息
  CONSOLE = 1,        // 小组级控制台手动发送消息
  BROADCAST = 2,      // 群发
  AUTO_REPLY = 3,     // 自动回复
  CREATE_ROOM = 4,    // 创建群聊
  BOT_REPLY = 5,      // 其他机器人回复
  API = 6,            // api发消息
  SOP = 7,            // sop功能
  API_BROADCAST = 8,  // api群发
}

相应的payload的格式如下

Unknown类型:

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

参数说明:

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

Attachment类型:

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

参数说明:

参数类型必定存在备注
namestring文件名
fileUrlstring文件地址
sizenumber文件大小

Audio类型:

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

参数说明:

参数类型必定存在备注
voiceUrlstring语音地址
durationnumber时长

Contact类型:

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

参数说明:

参数类型必定存在备注
avatarstring头像
coworkerbool是否为内部员工
friendbool是否为好友
gendernumber性别(详情请见GenderType
wxidstringwxid, 详见contactWxid
namestring名字
typenumber类型(详情见下方contactType
weixinstring微信号/企业微信(名字全拼)

ChatHistory类型:

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

参数说明:

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

Emoticon类型:

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

参数说明:

参数类型必定存在备注
imageUrlstring表情地址

Image类型:

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

参数说明:

参数类型必定存在备注
imageUrlstring压缩图片地址
sizenumber图片大小
artworkobject原图数据
artwork.urlstring原图地址
artwork.heightnumber原图高
artwork.widthnumber原图宽

Text类型:

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

参数说明:

参数类型必定存在备注
textstring消息内容
mentionarray被@的人的wxid

Location类型:

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

参数说明:

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

MiniProgram类型:

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

参数说明:

参数类型必定存在备注
appidstring关联的公众号ID
descriptionstring小程序描述
pagePathstring跳转路径
thumbKeystring封面图加密数据
thumbUrlstring封面图url
titlestring小程序标题
usernamestring小程序ID
iconUrlstringicon地址

Money类型:

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

参数说明:

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

Recalled类型:

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

参数说明:

参数类型必定存在备注
contentstring消息id

Url类型:

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

参数说明:

参数类型必定存在备注
titlestring标题
descriptionstring描述
thumbnailUrlstring封面图地址
urlstring跳转地址

Video类型:

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

参数说明:

参数类型必定存在备注
videoUrlstring视频地址
durationnumber时长
thumbnailUrlstring封面图地址

RoomInvitation类型:

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

参数说明:

参数类型必定存在备注
roomTopicstring群名
avatarUrlstring群头像
invitaterNamestring邀请者名字
inviteModelIdstring邀请者记录id
inviteStatusnumber邀请状态(详情见RoomInvitationStatus

System类型:

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

SystemSubPayload

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

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

参数说明:

参数类型必定存在备注
typenumber类型(详情见SystemMsgType
subPayloadobject详情
RecallFailedPayload.messageIdstring消息id
RoomJoinMemberPayload.memberNamesarray入群联系人名字
RoomJoinMemberPayload.inviterNamestring邀请者姓名

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,
  }
}

参数说明:

参数类型必定存在备注
wechatSystemPayloadTypenumber类型(详情见WechatSystemPayloadType
subPayloadobject详情
ContactInRoomSystemMessage.wxidstringwxid, 详见roomWxid
ContactInRoomSystemMessage.isSelfstring是否是bot自己
ContactInRoomSystemMessage.displayNamestring展示名称
RoomJoinPayload.inviterobject邀请者信息
RoomJoinPayload.inviteeListarray被邀请者信息
RoomJoinPayload.timestampnumber时间戳
RoomLeavePayload.removerobject踢人者
RoomLeavePayload.leaverListarray被踢者信息
RoomLeavePayload.timestampnumber时间戳
RoomTopicPayload.oldTopicstring旧群名
RoomTopicPayload.newTopicstring新群名
RoomTopicPayload.changerobject修改者信息
RoomTopicPayload.timestampnumber时间戳

发送消息回调

POST ***/sentResult

使用须知

需要在界面开启 "发送消息回调" 开关。

请求示例:

{
  "data" : {
    "requestId": "600e343fca473e00394aaaaa",
    "sentStatus": true,
    "token": "5df7649ae44570065a78f337",
    "errorCode": 101,
    "errorMsg": "系统错误,请重启后稍后重试",
    "chatId": "5df7649ae44570065a78f333",
    "sendTimestamp": 1604048292000,
    "messageType": 0,
    "payload": {
      "text": "123",
    },
    "externalRequestId": "123",
  }
}

请求参数:

名称类型是否必须备注
requestIdstring发送消息的请求id
sentStatusboolean消息是否发送成功
tokenstring小组控制台的小组token, 详见小组级token
errorCodenumber错误码0表示成功
errorMsgstring错误信息说明
chatIdstring发送对象的chatId, 详见chatId
sendTimestampnumber发送消息的时间戳
messageTypenumber消息的类型
payloadany消息的内容 同发消息的payload
externalRequestIdstring会在回调中原样带回的字段,需保证唯一
error code msg 具体原因说明

0: (发送成功) msg 为空

101: 系统错误,请重启后稍后重试
102: 无效的url
103: 托管微信已掉线,请启动后重试
104: 托管微信网络异常,请检查网络或者重启后再试
105: 群聊不存在或者加载失败,请同步已有群聊后重试
106: 联系人不存在或者加载失败,请同步已有联系人后重试
107: 名片发送失败,请检查该名片是否是好友关系
108: 小程序发送失败,请检查小程序参数是否正确

150: 对联系人发送消息过于频繁被限制 151: 对群聊发送消息过于频繁被限制 152: 该托管账号已不在群聊中 153: 对方已不在企业中 154: 该托管账号没有外部联系人权限 155: 发送文件失败 156: 发送群公告失败 157: 对方开启了联系人验证,你还不是他的联系人 158: 对方将您拉黑了 159: 对方已将您删除 160: 该托管账号相关功能被封禁 161: 对方无外部联系人权限 162: 操作频率过快被限制
201: 托管微信未完成数据同步,请稍后再试
202: 托管微信云端客户端出错,请稍后重试
203: 超过账号同时发送消息数量限制,请稍后重试
204: 托管微信发送消息失败,请重试,如多次失败请在秒回中重启后再试
205: 客户端崩溃尚未启动完成,请稍后重试

1001: 消息发送错误,不确定消息是否发送成功,建议确认是否发送成功或重试,如多次超时,请联系客服
1002: 消息发送超时,不确定消息是否发送成功,建议确认是否发送成功或重试,如多次超时,请联系客服
1100: 未知原因

以下3xx错误码现已废弃。废弃时间为2022-07-14

301: 对联系人发送消息过于频繁被限制。 变更为 【150】302: 对群聊发送消息过于频繁被限制。 变更为 【151】303: 该托管账号已不在群聊中。 变更为 【152】304: 对方已不在企业中。 变更为 【153】305: 该托管账号没有外部联系人权限。 变更为 【154】306: 发送文件失败。 变更为 【155】307: 发送群公告失败。 变更为 【156】308: 对方开启了联系人验证,你还不是他的联系人。 变更为 【157】309: 对方将您拉黑了。 变更为 【158】310: 对方已将您删除。 变更为 【159】311: 该托管账号相关功能被封禁。 变更为 【160】312: 对方无外部联系人权限。 变更为 【161】390: 未知原因。 变更为 【1100】391: 未知原因。 变更为 【1100】

获取原图

获取原图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
  }
}

拉取历史聊天记录

请示地址:

GET https://ex-api.botorange.com/message/history?token={your-token}&snapshotDay=2022-08-25&pageSize=10&seq=

参数说明:

参数类型是否必须备注
tokenstring身份验证, 获取方式
snapshotDaystring日期(YYYY-MM-DD)
pageSizestring拉取的聊天历史条数
seqstring游标,用于拉取聊天

返回数据为json格式,具体格式如下:

{
  "code": 0,
  "data": [
    {
      "botId": "5d0c86971150c017984cee66", // botid
      "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
      "contactType": 1,
      "coworker": false, // is coworker or not
      "botWxid": "1688851085873555",
      "botWeixin": "123",
      "source": 1,
      "sendBy": "",
      "isSelf": true,
    }
  ],
  "seq": "1585995128441"
}

返回参数说明:

参数类型必定存在备注
codenumber返回码
dataarray消息列表
seqstring游标,用于拉取聊天
最近更新:
Contributors: windmemory, hamlin.li, SilentQianyi, alexwang, hanyachao, iseei, 高原