POST https://qw-openapi-tx.dustess.com/ai/v1/agent/msg/directSendMsg?accessToken=
Content-Type: application/json| 请求参数名 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| scrmAccountID | string | SCRM账号ID,如:W00000000516 | true |
| qwUserId | string | 企微员工ID(需要先对该员工进行授权),如:wonBvEDAAA9lHv80telxLj_YHPC6gDXA | true |
| targetType | string | 目标类型。"single"=单聊,"group"=群聊 | true |
| targetIds | []string | 目标外部ID列表(好友ExternalUserId或群groupId),最多100个 | true |
| messages | []object | 消息列表 | true |
| messages.msgType | int32 | 消息类型。0=文本,1=图片,2=语音,3=文件,4=视频,6=地理位置,9=链接消息,10=小程序消息 | true |
| messages.content | string | 消息内容(文本消息使用) | false |
| messages.fileURL | string | 资源地址(图片、语音、文件、视频等类型消息必填) | false |
| messages.contents | []string | 特殊消息内容(位置、链接、小程序消息使用) | false |
| messages.replyMsgID | []int64 | 被回复的消息ID数组 | false |
{
"msgType": 0,
"content": "你好,这是一条主动发送的消息"
}
{
"msgType": 0,
"content": "@#客服# 你好,这是一条主动发送的消息" // 需要@群成员时,使用 @#xx# 包住@对象的名字,可以是全名或前缀,会自动根据群成员名称进行匹配@
}
{
"msgType": 1,
"fileURL": "https://example.com/image.png"
}{
"msgType": 2,
"fileURL": "https://example.com/voice.amr"
}{
"msgType": 3,
"fileURL": "https://example.com/file.pdf"
}{
"msgType": 4,
"fileURL": "https://example.com/video.mp4"
}特殊消息格式需要将序列化的JSON字符串放在contents中,只取第一个值
{
"msgType": 6,
"contents": [
"{\"address\":\"福建省厦门市集美区侨英街道龙荷二里万科云城15-38号\",\"latitude\":24.604396,\"longitude\":118.078909,\"name\":\"微风乐集·听风的歌(万科云城店)\",\"precision\":0.0}"
]
}{
"msgType": 9,
"contents": [
"{\"desc\":\"百度\",\"thumbUrl\":\"https://picx.zhimg.com/v2-d6f44389971daab7e688e5b37046e4e4_720w.jpg?source=172ae18b\",\"title\":\"百度首页\",\"url\":\"https://www.baidu.com\"}"
]
}| 参数名 | 类型 | 说明 | 是否必填 |
|---|---|---|---|
| appName | string | 小程序名称 | true |
| appid | string | 小程序ID | true |
| pagePath | string | 页面地址 | true |
| thumbUrl | string | 封面图 | true |
| thumbWidth | int | 封面图宽度 | false |
| title | string | 标题 | true |
| type | int | 类型标识,固定为2 | true |
| username | string | 小程序原始ID,必须带有@app后缀 | true |
| weappIconUrl | string | 小程序logo | true |
| schema | string | schema地址,rpa通道必填 | 视通道而定 |
| desc | string | 描述信息 | false |
{
"msgType": 10,
"contents": [
"{\"appName\":\"成都地铁乘车码\",\"appid\":\"wx1b5e2763b9c1e06e\",\"desc\":\"成都地铁乘车码\",\"pagePath\":\"pages/index/index.html\",\"thumbUrl\":\"https://xxx.jpg\",\"thumbWidth\":720,\"title\":\"成都地铁乘车码\",\"type\":2,\"username\":\"gh_27bdf69a27bb@app\",\"weappIconUrl\":\"http://mmbiz.qpic.cn/mmbiz_png/vOGI97uF6r4Oz6aeWdPLgP7D34XiaNaHz7iadb8dc4YE69BqmUsmUIovF8vdAibMnhvpg7Yk1S4yqRzhzYAsjuwiaA/640?wx_fmt=png\\u0026wxfrom=200\",\"schema\":\"weixin://dl/business/?t=xxxxx\"}"
]
}{
"scrmAccountID": "W00000000516",
"qwUserId": "wonBvEDAAA9lHv80telxLj_YHPC6gDXA",
"targetType": "single",
"targetIds": [
"wmnBvEDAAATUrpUTt5f0RXe-8Iemwqpg",
"wmnBvEDAAATUrpUTt5f0RXe-8Iemwqph",
"wmnBvEDAAATUrpUTt5f0RXe-8Iemwqpi"
],
"messages": [
{
"msgType": 0,
"content": "群发消息内容"
}
]
}| 响应参数名 | 类型 | 说明 |
|---|---|---|
| status | int32 | 整体发送状态。0=全部成功,1=部分成功,2=全部失败 |
| totalCount | int32 | 总目标数 |
| successCount | int32 | 成功发送的目标数 |
| failCount | int32 | 失败的目标数 |
| results | []object | 每个目标的详细发送结果 |
| results.targetId | string | 原始传入的目标外部ID |
| results.success | bool | 该目标是否发送成功 |
| results.errorCode | string | 错误码(失败时返回,用于判断失败原因类型) |
| results.msgIds | []int64 | 成功发送的消息ID列表(成功时返回,失败时为空数组) |
{
"status": 0,
"totalCount": 1,
"successCount": 1,
"failCount": 0,
"results": [
{
"targetId": "wmnBvEDAAATUrpUTt5f0RXe-8Iemwqpg",
"success": true,
"errorCode": "",
"msgIds": [123456789, 123456790]
}
]
}{
"status": 1,
"totalCount": 3,
"successCount": 2,
"failCount": 1,
"results": [
{
"targetId": "target_id_1",
"success": true,
"errorCode": "",
"msgIds": [123456791, 123456792]
},
{
"targetId": "target_id_2",
"success": false,
"errorCode": "TARGET_NOT_FOUND",
"msgIds": []
},
{
"targetId": "target_id_3",
"success": true,
"errorCode": "",
"msgIds": [123456793]
}
]
}| 错误码 | 说明 | 处理建议 |
|---|---|---|
| USER_NOT_FOUND | 未找到对应的员工 | 检查qwUserId是否正确 |
| TARGET_NOT_FOUND | 未找到对应的目标好友/群 | 检查targetId是否正确,确认好友关系是否存在 |
| CHAT_NOT_FOUND | 未找到对应的会话 | 确认会话是否存在 |
| SEND_FAILED | 消息发送失败 | 查看服务端日志排查具体原因 |
| INVALID_MESSAGE | 消息格式非法 | 检查消息内容格式是否符合要求 |
| CHANNEL_NOT_SUPPORT | 不支持的渠道类型 | 当前仅支持企微会话存档和ecom渠道 |
| INVALID_TARGET_TYPE | 目标类型非法 | targetType仅支持"single"或"group" |
| EMPTY_TARGETS | 目标列表不能为空 | targetIds至少传入一个 |
| EMPTY_MESSAGES | 消息列表不能为空 | messages至少传入一条消息 |
| INVALID_ACCOUNT_ID | scrmAccountID不能为空 | 必须传入有效的账号ID |
| INVALID_QW_USER_ID | qwUserId不能为空 | 必须传入有效的企微员工ID |
| TOO_MANY_TARGETS | 目标数量超过限制 | 单次请求最多支持100个目标 |