接收消息和事件-读取消息
POST
/cgi-bin/kf/sync_msg
概述
回调事件
示例
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| CreateTime | 消息创建时间，unix时间戳 |
| MsgType | 消息的类型，此时固定为：event |
| Event | 事件的类型，此时固定为：kf_msg_or_event |
| Token | 调用拉取消息接口时，需要传此token，用于校验请求的合法性 |
| OpenKfId | 有新消息的客服账号。可通过sync_msg接口指定open_kfid获取此客服账号的消息 |
读取消息
支持的消息类型：文本、图片、语音、视频、文件、位置、链接、名片、小程序、菜单、事件。
消息类型
文本消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：text |
| text | obj | 文本消息 |
| text.content | string | 文本内容 |
| text.menu_id | string | 客户点击菜单消息，触发的回复消息中附带的菜单ID |
图片消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：image |
| image | obj | 图片消息 |
| image.media_id | string | 图片文件id |
语音消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：voice |
| voice | obj | 语音消息 |
| voice.media_id | string | 语音文件ID |
视频消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：video |
| video | obj | 视频消息 |
| video.media_id | string | 文件id |
文件消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：file |
| file | obj | 文件消息 |
| file.media_id | string | 文件id |
位置消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：location |
| location | obj | 地理位置消息 |
| location.latitude | float | 纬度 |
| location.longitude | float | 经度 |
| location.name | string | 位置名 |
| location.address | string | 地址详情说明 |
链接消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：link |
| link | obj | 链接消息 |
| link.title | string | 标题 |
| link.desc | string | 描述 |
| link.url | string | 点击后跳转的链接 |
| link.pic_url | string | 缩略图链接 |
名片消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：business_card |
| business_card | obj | 名片消息 |
| business_card.userid | string | 名片userid |
小程序消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：miniprogram |
| miniprogram | obj | 小程序消息 |
| miniprogram.title | string | 标题 |
| miniprogram.appid | string | 小程序appid |
| miniprogram.pagepath | string | 点击消息卡片后进入的小程序页面路径 |
| miniprogram.thumb_media_id | string | 小程序消息封面的mediaid |
菜单消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：msgmenu |
| msgmenu | obj | 菜单消息 |
| msgmenu.head_content | string | 起始文本 |
| msgmenu.list | obj[] | 菜单项配置 |
| msgmenu.list.type | string | 菜单类型。 click-回复菜单 view-超链接菜单 miniprogram-小程 序菜单 |
| msgmenu.list.click | obj | type为click的菜单项 |
| msgmenu.list.click.id | string | 菜单ID |
| msgmenu.list.click.content | string | 菜单显示内容 |
| msgmenu.list.view | obj | type为view的菜单项 |
| msgmenu.list.view.url | string | 点击后跳转的链接 |
| msgmenu.list.view.content | string | 菜单显示内容 |
| msgmenu.list.miniprogram | obj | type为miniprogram的菜单项 |
| msgmenu.list.miniprogram.appid | string | 小程序appid |
| msgmenu.list.miniprogram.pagepath | string | 点击后进入的小程序页面 |
| msgmenu.list.miniprogram.content | string | 菜单显示内容 |
| msgmenu.tail_content | string | 结束文本 |
视频号商品消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：channels_shop_product |
| channels_shop_product | obj | 视频号商品消息 |
| channels_shop_product.product_id | string | 商品ID |
| channels_shop_product.head_img | string | 商品图片 |
| channels_shop_product.title | string | 商品标题 |
| channels_shop_product.sales_price | string | 商品价格，以分为单位 |
| channels_shop_product.shop_nickname | string | 店铺名称 |
| channels_shop_product.shop_head_img | string | 店铺头像 |
视频号订单消息
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：channels_shop_order |
| channels_shop_order | obj | 视频号订单消息 |
| channels_shop_order.order_id | string | 订单号 |
| channels_shop_order.product_titles | string | 商品标题 |
| channels_shop_order.price_wording | string | 订单价格描述 |
| channels_shop_order.state | string | 订单状态 |
| channels_shop_order.image_url | string | 订单缩略图 |
| channels_shop_order.shop_nickname | string | 店铺名称 |
事件消息
用户进入会话事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：enter_session |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.scene | string | 进入会话的场景值，获取客服帐号链接开发者自定义的场景值 |
| event.scene_param | string | 进入会话的自定义参数，获取客服帐号链接返回的url，开发者按规范拼接的scene_param参数 |
| event.welcome_code | string | 如果满足发送欢迎语条件（条件为：用户在过去48小时里未收过欢迎语，且未向客服发过消息），会返回该字段。 可用该welcome_code调用发送事件响应消息接口给客户发送欢迎语。 |
| event.wechat_channels | obj | 进入会话的视频号信息，从视频号进入会话才有值 |
| event.wechat_channels.nickname | string | 视频号名称，视频号场景值为1、2、3时返回此项 |
| event.wechat_channels.shop_nickname | string | 视频号小店名称，视频号场景值为4、5时返回此项 |
| event.wechat_channels.scene | uint32 | 视频号场景值。1：视频号主页，2：视频号直播间商品列表页，3：视频号商品橱窗页，4：视频号小店商品详情页，5：视频号小店订单页 |
消息发送失败事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：msg_send_fail |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.fail_msgid | string | 发送失败的消息msgid |
| event.fail_type | uint32 | 失败类型。0-未知原因 1-客服账号已删除 2-应用已关闭 4-会话已过期，超过48小时 5-会话已关闭 6-超过5条限制 7-未绑定视频号 8-主体未验证 9-未绑定视频号且主体未验证 10-用户拒收 |
接待人员接待状态变更事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：servicer_status_change |
| event.servicer_userid | string | 接待人员userid |
| event.status | uint32 | 状态类型。1-接待中 2-停止接待 |
| event.open_kfid | string | 客服帐号ID |
会话状态变更事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：session_status_change |
| event.open_kfid | string | 客服帐号ID |
| event.external_userid | string | 客户UserID |
| event.change_type | uint32 | 变更类型，均为接待人员在企业微信客户端操作触发。1-从接待池接入会话 2-转接会话 3-结束会话 4-重新接入已结束/已转接会话 |
| event.old_servicer_userid | string | 老的 接待人员userid。仅change_type为2、3和4有值 |
| event.new_servicer_userid | string | 新的接待人员userid。仅change_type为1、2和4有值 |
| event.msg_code | string | 用于发送事件响应消息的code，仅change_type为1和3时，会返回该字段。 可用该msg_code调用发送事件响应消息接口给客户发送回复语或结束语。 |
用户撤回消息事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：user_recall_msg |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.recall_msgid | string | 撤回的消息msgid |
接待人员撤回消息事件
| 参数 | 类型 | 说明 |
|---|---|---|
| msgtype | string | 消息类型，此时固定为：event |
| event | obj | 事件消息 |
| event.event_type | string | 事件类型。此处固定为：servicer_recall_msg |
| event.open_kfid | string | 客服账号ID |
| event.external_userid | string | 客户UserID |
| event.recall_msgid | string | 撤回的消息msgid |
| event.servicer_userid | string | 接待人员userid |
请求参数
Query 参数
Body 参数application/json
返回响应
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --globoff 'https://qyapi.weixin.qq.com/cgi-bin/kf/sync_msg?access_token=' \
--header 'Content-Type: application/json' \
--data '{
"cursor": "4gw7MepFLfgF2VC5npN",
"token": "ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR",
"limit": 1000,
"voice_format": 0,
"open_kfid": "wkxxxxxx"
}'响应示例响应示例
{
"errcode": 0,
"errmsg": "ok",
"next_cursor": "4gw7MepFLfgF2VC5npN",
"has_more": 1,
"msg_list": [
{
"msgid": "from_msgid_4622416642169452483",
"open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
"external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
"send_time": 1615478585,
"origin": 3,
"servicer_userid": "Zhangsan",
"msgtype": "MSG_TYPE"
}
]
}
扫码加入交流群修改于 2022-12-01 09:34:26