概述

当微信客户、接待人员发消息或有行为动作时，企业微信后台会将事件的回调数据包发送到企业指定URL；企业收到请求后，再通过读取消息接口主动读取具体的消息内容。

回调事件

接收并解析事件的方法见：接收事件。
示例

说明

参数	说明
ToUserName	企业微信CorpID
CreateTime	消息创建时间，unix时间戳
MsgType	消息的类型，此时固定为：event
Event	事件的类型，此时固定为：kf_msg_or_event
Token	调用拉取消息接口时，需要传此token，用于校验请求的合法性
OpenKfId	有新消息的客服账号。可通过sync_msg接口指定`open_kfid`获取此客服账号的消息

读取消息

微信客户发送的消息、接待人员在企业微信回复的消息、发送消息接口发送失败事件（如被用户拒收）、客户点击菜单消息的回复消息，可以通过该接口获取最近3天内具体的消息内容和事件。不支持读取通过发送消息接口发送的消息。
支持的消息类型：文本、图片、语音、视频、文件、位置、链接、名片、小程序、菜单、事件。

消息类型

文本消息

返回示例：

参数说明：

参数	类型	说明
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

curl --location -g --request POST 'https://qyapi.weixin.qq.com/cgi-bin/kf/sync_msg?access_token=' \ --header 'Content-Type: application/json' \ --data-raw '{ "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" } ] }

请求参数

Query 参数

access_token

调用接口凭证

必需

示例值:

Body 参数application/json

cursor

string

可选

上一次调用时返回的next_cursor，第一次拉取可以不填。若不填，从3天内最早的消息开始返回。不多于64字节

token

string

可选

回调事件返回的token字段，10分钟内有效；可不填，如果不填接口有严格的频率限制。不多于128字节

limit

integer

可选

期望请求的数据量，默认值和最大值都为1000。注意：可能会出现返回条数少于limit的情况，需结合返回的has_more字段判断是否继续请求。

voice_format

integer

可选

语音消息类型，0-Amr 1-Silk，默认0。可通过该参数控制返回的语音格式，开发者可按需选择自己程序支持的一种格式

open_kfid

string

可选

指定拉取某个客服账号的消息，否则默认返回有权限的客服账号的消息。当客服账号较多，建议按open_kfid来拉取以获取更好的性能。

示例

返回响应

🟢200成功

application/json

Body

errcode

integer <int32>

可选

msg_list

array [object {7}]

消息列表

可选

external_userid

string

可选

客户UserID（msgtype为event，该字段不返回）

send_time

integer <int32>

消息发送时间

可选

origin

integer <int32>

可选

消息来源。3-微信客户发送的消息 4-系统推送的事件消息 5-接待人员在企业微信客户端发送的消息

msgid

string

消息ID

可选

servicer_userid

string

可选

从企业微信给客户发消息的客服人员userid（msgtype为event，该字段不返回）

open_kfid

string

可选

客服帐号ID（msgtype为event，该字段不返回

msgtype

string

可选

对不同的msgtype，有相应的结构描述，下面进一步说明

next_cursor

string

可选

下次调用带上该值，则从当前的位置继续往后拉，以实现增量拉取。强烈建议对改该字段入库保存，每次请求读取带上，请求结束后更新。避免因意外丢，导致必须从头开始拉取，引起消息延迟。

errmsg

string

可选

has_more

integer <int32>

可选

是否还有更多数据。0-否；1-是。不能通过判断msg_list是否空来停止拉取，可能会出现has_more为1，而msg_list为空的情况

接收消息和事件-读取消息

概述#

回调事件#

读取消息#

消息类型#

文本消息#

图片消息#

语音消息#

视频消息#

文件消息#

位置消息#

链接消息#

名片消息#

小程序消息#

菜单消息#

视频号商品消息#

视频号订单消息#

事件消息#

用户进入会话事件#

消息发送失败事件#

接待人员接待状态变更事件#

会话状态变更事件#

用户撤回消息事件#

接待人员撤回消息事件#

请求参数

返回响应

概述

回调事件

读取消息

消息类型

文本消息

图片消息

语音消息

视频消息

文件消息

位置消息

链接消息

名片消息

小程序消息

菜单消息

视频号商品消息

视频号订单消息

事件消息

用户进入会话事件

消息发送失败事件

接待人员接待状态变更事件

会话状态变更事件

用户撤回消息事件

接待人员撤回消息事件