消息管理接口

发送消息

POST https://hub.juzibot.com/api/v2/message/send?token=***

请求参数:

名称类型是否必须备注
tokenstring调用接口凭证, 获取方式
externalRequestIdstring会在回调中原样带回的字段,需要保证唯一(当不唯一时报错),两月内幂等
imBotIdstring托管账号的wxid(v1版本的botWxid), 详见imBotId
imContactIdstring客户的id(v1版本的contactWxid), 详见contactWxid
imRoomIdstring群聊的id(v1版本的roomWxid), 详见roomWxid
messageTypeSendMessageType消息类型
payloadSendMessagePayload消息的payload

TIP

imBotId 是v1版本api接口中bot的wxid, 详见imBotId
imContactId 是v1版本api接口中contact的wxid, 详见contactWxid
imRoomId 是v1版本api接口中room的wxid, 详见roomWxid
imContactId 和 imRoomId 必须存在一个,当同时存在时,优先imContactId

enum SendMessageType {
  File = 1,        // 文件
  Voice = 2,       // 语音
  Emoticon = 5,    // 表情
  Image = 6,       // 图片
  Text = 7,        // 文字
  Location = 8,    // 位置
  MiniProgram = 9, // 小程序
  Url = 12,        // 图文消息
  Video = 13,      // 视频
  Channel = 14;    // 视频号
}

type SendMessagePayload =
  SendFilePayload |
  SendVoicePayload |
  SendEmoticonPayload |
  SendImagePayload |
  SendTextPayload |
  SendLocationPayload |
  SendMiniProgramPayload |
  SendUrlPayload |
  SendVideoPayload |
  SendChannelPayload;

file类型消息

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

参数说明:

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

voice(语音)类型消息

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

参数说明:

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

emoticon(表情)类型消息

TIP

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

interface SendEmoticonPayload {
  imageUrl: string,
}

参数说明:

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

image类型消息

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

参数说明:

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

text类型消息

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

参数说明:

参数类型必定存在备注
textstring消息内容
mentionarray@人的wxid列表, @all 可以@所有人

location(位置)类型消息

TIP

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

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

参数说明:

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

miniProgram类型消息

interface SendMiniProgramPayload {
  appId: string,
  description: string,
  pagePath: string,
  thumbUrl: string,
  title: string,
  username: string,
  iconUrl?: string,
}

参数说明:

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

url类型消息

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

参数说明:

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

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

interface SendVideoPayload {
  url: string,
}

参数说明:

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

channel(视频号)类型消息

TIP

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

interface SendChannelPayload {
  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未知, 请使用收到的字段信息

返回示例:

{
  errcode: 0,
  errmsg: 'ok',
  requestId: 'requestId',
}

返回参数说明:

参数类型必定存在备注
errcodenumber返回码
errmsgstring对返回码的文本描述内容
requestIdstring消息的请求id,可与回调结合使用获取本次发消息情况

错误码:

错误码说明
-1系统错误
-2没找到托管账号
-3找到多个托管账号
-4未找到客户
-5未找到群聊
-6消息类型错误

发送消息回调 POST

回调地址在 企业级 api接入配置 发消息结果回调地址

请求参数:

名称类型是否必须备注
typestring固定为send_message_result
requestIdstring发送消息的请求id
externalRequestIdstring发送消息的自定义请求id
timestampnumber回调时间戳 (毫秒)
imBotIdstring托管账号的botId(v1版本的botWxid), 详见botId
imContactIdstring客户的id(v1版本的contactWxid), 详见contactWxid
imRoomIdstring群聊的id(v1版本的roomWxid), 详见roomWxid
messageTypeSendMessageType消息类型
messagePayloadSendMessagePayload消息的payload
sendCodenumber错误码
sendMessagestring错误描述
sendTimestampnumber发送时间戳(毫秒)

返回示例:

{
  errcode: 0,
  errmsg: 'ok',
}

返回参数说明:

参数类型必定存在备注
errcodenumber返回码
errmsgstring对返回码的文本描述内容

接收消息回调 POST

回调地址在 企业级 api接入配置 收消息回调地址

消息格式

{
  "orgId": "orgId",
  "token": "5dbe8221fc191f13bc072908",
  "botId": "5d0c86971150c017984cee66",
  "imBotId": "1688851085873555",
  "botUserId": "123",
  "chatId": "5e469a2b8d429806b0fef189",
  "avatar": "http://wx.qlogo.cn/mmhead/ver_1/JiceV4HzlY2MAg0ZEfcytbic6GcibRj2FLK6oDFsR4FafVFnPBQ6Kc1Wqur2KmN8ult3Zf4cxqp2L64daRN5V7oWfIk5k4BTDMTqZQVo0Fpsj8/132",
  "coworker": false,
  "imContactId": "wxid_rr9ej1o8xv9h21",
  "externalUserId": "ExternalUserId",
  "contactName": "小北",
  "contactType": 1,
  "imRoomId": "7215325536@chatroom",
  "roomWecomChatId": "RoomWecomChatId",
  "roomTopic": "我的亲友团",
  "messageId": "2422188041612737714",
  "isSelf": true,
  "sendBy": "",
  "source": 1,
  "timestamp": 1585995128441,
  "messageType": MsgType,
  "payload": MessagePayload,
}

返回参数说明:

参数类型必定存在备注
orgIdstring企业id
tokenstring企业级token
botIdstringbot的账号id
imBotIdstringbot的wxid
botUserIdstringbot的企业微信userId
chatIdstring聊天id(表示一个bot和一个客户)
avatarstring客户或者群头像
coworkerbool是否为内部员工
imContactIdstring客户wxid
externalUserIdstring客户企微externalUserId
contactNamestring客户名
contactTypenumber客户的类型(详情见下方contactType
imRoomIdstring群wxid, 详见roomWxid
roomWecomChatIdstring群的企微chatId, 详见wecomChatId
roomTopicstring群名
messageIdstring消息id
isSelfbool消息是否是托管账号自己发送的消息
sendBystring消息发送者的秒回id,仅当消息为消息为托管账号发送的,且消息来源为小组级控制台手动发消息时有效
sourceMessageSource消息来源,具体来源信息参考下面的枚举定义
timestampnumber消息的时间(ms)
messageTypenumber消息类型(详情见下方msgType
payloadobject消息具体内容(详情见下方

相应的枚举的格式如下

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功能
}

相应的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时间戳

获取指定托管账号的聊天历史

请求地址:

GET https://hub.juzibot.com/api/v2/message/history?token={your-token}&imBotId={imBotId}&snapshotDay=2022-08-25&pageSize=10&seq=0

请求参数:

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

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

{
  "errcode": 0,
  "errmsg": "",
  "data": {
    "botId": "5d0c86971150c017984cee66",
    "imBotId": "1688851085873555",
    "botWeixin": "123",
    "messages":[
      {
        "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
        "imRoomId": "7215325536@chatroom", // room wxid nullable
        "contactName": "小北", // message conact name
        "imContactId": "wxid_rr9ej1o8xv9h21",
        "payload": MessagePayload,
        "type": MsgType,
        "timestamp": 1585995128441, // message timestamp
        "contactType": 1,
        "coworker": false, // is coworker or not
        "source": 1,
        "sendBy": "",
        "isSelf": true,
      }
    ]
  },
  "seq": "1585995128441"
}

返回参数说明:

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