消息管理接口
发送消息
POST https://hub.juzibot.com/api/v2/message/send?token=***
请求参数:
名称 | 类型 | 是否必须 | 备注 |
---|
token | string | 是 | 调用接口凭证, 获取方式 |
externalRequestId | string | 否 | 会在回调中原样带回的字段,需要保证唯一(当不唯一时报错),两月内幂等 |
imBotId | string | 是 | 托管账号的wxid(v1版本的botWxid), 详见imBotId |
imContactId | string | 否 | 客户的id(v1版本的contactWxid), 详见contactWxid |
imRoomId | string | 否 | 群聊的id(v1版本的roomWxid), 详见roomWxid |
messageType | SendMessageType | 是 | 消息类型 |
payload | SendMessagePayload | 是 | 消息的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,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
name | string | 是 | 文件名 |
url | string | 是 | 文件地址 |
size | number | 否 | 文件大小 |
voice(语音)类型消息
interface SendVoicePayload {
voiceUrl: string,
duration?: number,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
voiceUrl | string | 是 | 语音地址, 目前仅支持silk格式的语音文件 |
duration | number | 否 | 时长(秒) |
emoticon(表情)类型消息
interface SendEmoticonPayload {
imageUrl: string,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
imageUrl | string | 是 | 图片地址 |
image类型消息
interface SendImagePayload {
url: string,
size?: number,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
url | string | 是 | 图片地址 |
size | number | 否 | 图片大小 |
text类型消息
interface SendTextPayload {
text: string,
mention?: string[],
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
text | string | 是 | 消息内容 |
mention | array | 否 | @人的wxid列表, @all 可以@所有人 |
location(位置)类型消息
interface SendLocationPayload {
accuracy: number,
address: string,
latitude: number,
longitude: number,
name: string,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
accuracy | number | 是 | 精确度 默认为15 |
address | string | 是 | 地址描述 |
latitude | number | 是 | 维度,北纬为正数 |
longitude | number | 是 | 经度,东经为正数 |
name | string | 是 | 地址名 |
miniProgram类型消息
interface SendMiniProgramPayload {
appId: string,
description: string,
pagePath: string,
thumbUrl: string,
title: string,
username: string,
iconUrl?: string,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
appId | string | 是 | 关联的公众号ID |
description | string | 是 | 描述 |
pagePath | string | 是 | 跳转地址 |
thumbUrl | string | 是 | 封面图地址 |
title | string | 是 | 标题 |
username | string | 是 | 小程序ID |
iconUrl | string | 否 | icon地址 |
url类型消息
interface SendUrlPayload {
sourceUrl: string,
title: string,
summary: string,
imageUrl: string,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
sourceUrl | string | 是 | 跳转地址 |
title | string | 是 | 标题 |
summary | string | 是 | 描述 |
imageUrl | string | 是 | 封面图地址 |
video类型消息(只支持mp4格式)
interface SendVideoPayload {
url: string,
}
参数说明:
channel(视频号)类型消息
interface SendChannelPayload {
avatarUrl: string,
coverUrl: string,
description: string,
feedType: number,
nickname: string,
thumbUrl: string,
url: string,
extras: string,
}
参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
avatarUrl | string | 是 | 头像地址 |
coverUrl | string | 是 | 封面地址 |
description | string | 是 | 描述 |
feedType | number | 是 | 未知, 目前固定为4 |
nickname | string | 是 | 昵称 |
thumbUrl | string | 是 | 缩略图地址 |
url | string | 是 | 视频号地址 |
extras | string | 是 | 未知, 请使用收到的字段信息 |
返回示例:
{
errcode: 0,
errmsg: 'ok',
requestId: 'requestId',
}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
errcode | number | 是 | 返回码 |
errmsg | string | 是 | 对返回码的文本描述内容 |
requestId | string | 是 | 消息的请求id,可与回调结合使用获取本次发消息情况 |
错误码:
错误码 | 说明 |
---|
-1 | 系统错误 |
-2 | 没找到托管账号 |
-3 | 找到多个托管账号 |
-4 | 未找到客户 |
-5 | 未找到群聊 |
-6 | 消息类型错误 |
发送消息回调 POST
回调地址在 企业级 api接入配置 发消息结果回调地址
请求参数:
名称 | 类型 | 是否必须 | 备注 |
---|
type | string | 是 | 固定为send_message_result |
requestId | string | 是 | 发送消息的请求id |
externalRequestId | string | 否 | 发送消息的自定义请求id |
timestamp | number | 是 | 回调时间戳 (毫秒) |
imBotId | string | 是 | 托管账号的botId(v1版本的botWxid), 详见botId |
imContactId | string | 否 | 客户的id(v1版本的contactWxid), 详见contactWxid |
imRoomId | string | 否 | 群聊的id(v1版本的roomWxid), 详见roomWxid |
messageType | SendMessageType | 是 | 消息类型 |
messagePayload | SendMessagePayload | 是 | 消息的payload |
sendCode | number | 是 | 错误码 |
sendMessage | string | 否 | 错误描述 |
sendTimestamp | number | 是 | 发送时间戳(毫秒) |
返回示例:
{
errcode: 0,
errmsg: 'ok',
}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
errcode | number | 是 | 返回码 |
errmsg | string | 是 | 对返回码的文本描述内容 |
接收消息回调 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,
}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
orgId | string | 是 | 企业id |
token | string | 是 | 企业级token |
botId | string | 是 | bot的账号id |
imBotId | string | 是 | bot的wxid |
botUserId | string | 是 | bot的企业微信userId |
chatId | string | 是 | 聊天id(表示一个bot和一个客户) |
avatar | string | 是 | 客户或者群头像 |
coworker | bool | 是 | 是否为内部员工 |
imContactId | string | 是 | 客户wxid |
externalUserId | string | 是 | 客户企微externalUserId |
contactName | string | 是 | 客户名 |
contactType | number | 是 | 客户的类型(详情见下方contactType) |
imRoomId | string | 否 | 群wxid, 详见roomWxid |
roomWecomChatId | string | 否 | 群的企微chatId, 详见wecomChatId |
roomTopic | string | 否 | 群名 |
messageId | string | 否 | 消息id |
isSelf | bool | 是 | 消息是否是托管账号自己发送的消息 |
sendBy | string | 否 | 消息发送者的秒回id,仅当消息为消息为托管账号发送的,且消息来源为小组级控制台手动发消息时有效 |
source | MessageSource | 否 | 消息来源,具体来源信息参考下面的枚举定义 |
timestamp | number | 是 | 消息的时间(ms) |
messageType | number | 是 | 消息类型(详情见下方msgType) |
payload | object | 是 | 消息具体内容(详情见下方) |
相应的枚举的格式如下
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,
SOP = 7,
}
相应的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 | 是 | 时长 |
{
"payload": {
"avatar": "https://xxx";
"coworker": false;
"friend": false;
"gender": 1;
"wxid": "1688849967837777";
"name": "我";
"type": 3;
"weixin": "wonMj_CgAA2QjLWcRIn3vuFN9b7mj222";
}
}
参数说明:
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, 详见roomWxid |
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://hub.juzibot.com/api/v2/message/history?token={your-token}&imBotId={imBotId}&snapshotDay=2022-08-25&pageSize=10&seq=0
请求参数:
参数 | 类型 | 是否必须 | 备注 |
---|
token | string | 是 | 身份验证, 获取方式 |
imBotId | string | 是 | 托管账号wxid, 获取方式 |
snapshotDay | string | 是 | 日期(YYYY-MM-DD) |
pageSize | string | 是 | 拉取的聊天历史条数 |
seq | string | 否 | 游标,用于拉取聊天 |
返回数据为json格式,具体格式如下:
{
"errcode": 0,
"errmsg": "",
"data": {
"botId": "5d0c86971150c017984cee66",
"imBotId": "1688851085873555",
"botWeixin": "123",
"messages":[
{
"botId": "5d0c86971150c017984cee66",
"messageId": "2422188041612737714",
"chatId": "5e469a2b8d429806b0fef189",
"avatar": "http://wx.qlogo.cn/mmhead/ver_1/JiceV4HzlY2MAg0ZEfcytbic6GcibRj2FLK6oDFsR4FafVFnPBQ6Kc1Wqur2KmN8ult3Zf4cxqp2L64daRN5V7oWfIk5k4BTDMTqZQVo0Fpsj8/132",
"roomTopic": "我的亲友团",
"imRoomId": "7215325536@chatroom",
"contactName": "小北",
"imContactId": "wxid_rr9ej1o8xv9h21",
"payload": MessagePayload,
"type": MsgType,
"timestamp": 1585995128441,
"contactType": 1,
"coworker": false,
"source": 1,
"sendBy": "",
"isSelf": true,
}
]
},
"seq": "1585995128441"
}
返回参数说明:
参数 | 类型 | 必定存在 | 备注 |
---|
code | number | 是 | 返回码 |
data | array | 是 | 消息列表 |
seq | string | 是 | 游标,用于拉取聊天 |