第三方应用开发 服务端API 微信客服 会话分配与消息收发 接收消息和事件
接收消息和事件
最后更新:2024/01/31
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
接收消息和事件
最后更新:2024/01/31

目录

  • 概述
  • 回调事件
  • 读取消息
  •       接口定义
  •       消息类型
  •             文本消息
  •             图片消息
  •             语音消息
  •             视频消息
  •             文件消息
  •             位置消息
  •             链接消息
  •             名片消息
  •             小程序消息
  •             菜单消息
  •             视频号商品消息
  •             视频号订单消息
  •             聊天记录消息
  •             视频号消息
  •             会议消息
  •             日程消息
  •             事件消息
  •                   用户进入会话事件
  •                   消息发送失败事件
  •                   接待人员接待状态变更事件
  •                   会话状态变更事件
  •                   用户撤回消息事件
  •                   接待人员撤回消息事件
  •                   拒收客户消息变更事件
  • 概述

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

    回调事件

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

    <xml>
       <ToUserName><![CDATA[ww12345678910]]></ToUserName>
       <CreateTime>1348831860</CreateTime>
       <MsgType><![CDATA[event]]></MsgType>
       <Event><![CDATA[kf_msg_or_event]]></Event>
       <Token><![CDATA[ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR]]></Token>
       <OpenKfId><![CDATA[wkxxxxxxx]]></OpenKfId>
    </xml>

    说明

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

    读取消息

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

    图片、语音、视频、文件消息的媒体文件有如下大小限制,超出会获取到文本提示消息:

    • 图片:2MB
    • 语音:2MB
    • 视频:10MB
    • 文件:20MB

    接口定义

    请求方式: POST(HTTPS)

    请求地址: https://qyapi.weixin.qq.com/cgi-bin/kf/sync_msg?access_token=ACCESS_TOKEN

    请求示例

    {
        "cursor": "4gw7MepFLfgF2VC5npN",
        "token": "ENCApHxnGDNAVNY4AaSJKj4Tb5mwsEMzxhFmHVGcra996NR",
        "limit": 1000,
        "voice_format": 0,
        "open_kfid": "wkxxxxxx"
    }

    参数说明:

    参数必须类型说明
    access_tokenstring调用接口凭证
    cursorstring上一次调用时返回的next_cursor,第一次拉取可以不填。若不填,从3天内最早的消息开始返回。
    不多于64字节
    tokenstring回调事件返回的token字段,10分钟内有效;可不填,如果不填接口有严格的频率限制。
    不多于128字节
    limituint32期望请求的数据量,默认值和最大值都为1000。
    注意:可能会出现返回条数少于limit的情况,需结合返回的has_more字段判断是否继续请求。
    voice_formatuint32语音消息类型,0-Amr 1-Silk,默认0。可通过该参数控制返回的语音格式,开发者可按需选择自己程序支持的一种格式
    open_kfidstring指定拉取某个客服账号的消息

     

    权限说明:
    调用的应用需要满足如下的权限

    应用类型权限要求
    自建应用配置到「 微信客服- 可调用接口的应用」中
    第三方应用具有“微信客服->管理账号、分配会话和收发消息”权限
    代开发自建应用具有“微信客服->管理账号、分配会话和收发消息”权限

    注: 从2023年12月1日0点起,不再支持通过系统应用secret调用接口,存量企业暂不受影响 查看详情

    • 只能通过API管理企业指定的客服账号。企业可在管理后台“微信客服-通过API管理微信客服账号”处设置对应的客服账号通过API来管理。
    • 操作的客服账号对应的接待人员应在应用的可见范围内

     

    返回结果:

    {
        "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"
            }
        ]
    }

    参数说明:

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    next_cursorstring下次调用带上该值,则从当前的位置继续往后拉,以实现增量拉取。
    强烈建议对该字段入库保存,每次请求读取带上,请求结束后更新。避免因意外丢,导致必须从头开始拉取,引起消息延迟。
    has_moreuint32是否还有更多数据。0-否;1-是。
    不能通过判断msg_list是否空来停止拉取,可能会出现has_more为1,而msg_list为空的情况
    msg_listobj[]消息列表
    msg_list.msgidstring消息ID
    msg_list.open_kfidstring客服账号ID(msgtype为event,该字段不返回)
    msg_list.external_useridstring客户UserID(msgtype为event,该字段不返回)
    msg_list.send_timeuint64消息发送时间
    msg_list.originuint32消息来源。3-微信客户发送的消息 4-系统推送的事件消息 5-接待人员在企业微信客户端发送的消息
    msg_list.servicer_useridstring从企业微信给客户发消息的接待人员userid(即仅origin为5才返回;msgtype为event,该字段不返回)
    msg_list.msgtypestring对不同的msgtype,有相应的结构描述,下面进一步说明

     

    消息类型

    文本消息

    返回示例:

    {
       "msgtype" : "text",
       "text" : {
            "content" : "hello world",
    		"menu_id" : "101"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:text
    textobj文本消息
    text.contentstring文本内容
    text.menu_idstring客户点击菜单消息,触发的回复消息中附带的菜单ID

    图片消息

    返回示例:

    {
       "msgtype" : "image",
       "image" : {
            "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:image
    imageobj图片消息
    image.media_idstring图片文件id

    语音消息

    返回示例:

    {
       "msgtype" : "voice",
       "voice" : {
            "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:voice
    voiceobj语音消息
    voice.media_idstring语音文件ID

    视频消息

    返回示例:

    {
       "msgtype" : "video",
       "video" : {
            "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:video
    videoobj视频消息
    video.media_idstring文件id

    文件消息

    返回示例:

    {
       "msgtype" : "file",
       "file" : {
            "media_id" : "2iSLeVyqzk4eX0IB5kTi9Ljfa2rt9dwfq5WKRQ4Nvvgw"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:file
    fileobj文件消息
    file.media_idstring文件id

    位置消息

    返回示例:

    {
       "msgtype" : "location",
       "location" : {
    		"latitude": 23.106021881103501,
    		"longitude": 113.320503234863,
    		"name": "广州国际媒体港(广州市海珠区)",
    		"address": "广东省广州市海珠区滨江东路"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:location
    locationobj地理位置消息
    location.latitudefloat纬度
    location.longitudefloat经度
    location.namestring位置名
    location.addressstring地址详情说明

    链接消息

    返回示例:

    {
       "msgtype" : "link",
       "link" : {
    		"title": "TITLE",
    		"desc": "DESC",
    		"url": "URL",
    		"pic_url": "PIC_URL"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:link
    linkobj链接消息
    link.titlestring标题
    link.descstring描述
    link.urlstring点击后跳转的链接
    link.pic_urlstring缩略图链接

    名片消息

    返回示例:

    {
       "msgtype" : "business_card",
       "business_card" : {
    		"userid": "USERID"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:business_card
    business_cardobj名片消息
    business_card.useridstring名片userid

     

    小程序消息

    返回示例:

    {
       "msgtype" : "miniprogram",
       "miniprogram" : {
    		"title": "TITLE",
    		"appid": "APPID",
    		"pagepath": "PAGE_PATH",
    		"thumb_media_id": "THUMB_MEDIA_ID"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:miniprogram
    miniprogramobj小程序消息
    miniprogram.titlestring标题
    miniprogram.appidstring小程序appid
    miniprogram.pagepathstring点击消息卡片后进入的小程序页面路径
    miniprogram.thumb_media_idstring小程序消息封面的mediaid

    菜单消息

    返回示例:

    {
       "msgtype" : "msgmenu",
       "msgmenu": {
        "head_content": "您对本次服务是否满意呢? ",
        "list": [
          {
    	    "type": "click",
    		"click":
    		{
            	"id": "101",
            	"content": "满意"
    		}
          },
          {
    	    "type": "click",
    		"click":
    		{
            	"id": "102",
            	"content": "不满意"
    		}
          },
    	  {
    	    "type": "view",
    		"view":
    		{
            	"url": "https://work.weixin.qq.com",
            	"content": "点击跳转到自助查询页面"
    		}
          },
    	  {
    	    "type": "miniprogram",
    		"miniprogram":
    		{
            	"appid": "wx123123123123123",
    			"pagepath": "pages/index?userid=zhangsan&orderid=123123123",
            	"content": "点击打开小程序查询更多"
    		}
          }
        ],
        "tail_content": "欢迎再次光临"
      }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:msgmenu
    msgmenuobj菜单消息
    msgmenu.head_contentstring起始文本
    msgmenu.listobj[]菜单项配置
    msgmenu.list.typestring菜单类型。
    click-回复菜单 view-超链接菜单 miniprogram-小程序菜单
    msgmenu.list.clickobjtype为click的菜单项
    msgmenu.list.click.idstring菜单ID
    msgmenu.list.click.contentstring菜单显示内容
    msgmenu.list.viewobjtype为view的菜单项
    msgmenu.list.view.urlstring点击后跳转的链接
    msgmenu.list.view.contentstring菜单显示内容
    msgmenu.list.miniprogramobjtype为miniprogram的菜单项
    msgmenu.list.miniprogram.appidstring小程序appid
    msgmenu.list.miniprogram.pagepathstring点击后进入的小程序页面
    msgmenu.list.miniprogram.contentstring菜单显示内容
    msgmenu.tail_contentstring结束文本

    视频号商品消息

    返回示例:

    {
       "msgtype" : "channels_shop_product",
       "channels_shop_product" : {
    		"product_id": "PRODUCT_ID",
    		"head_image": "PRODUCT_IMAGE_URL",
    		"title": "TITLE",
    		"sales_price": "SALES_PRICE",
    		"shop_nickname": "SHOP_NICKNAME",
    		"shop_head_image": "SHOP_HEAD_IMAGE"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:channels_shop_product
    channels_shop_productobj视频号商品消息
    channels_shop_product.product_idstring商品ID
    channels_shop_product.head_imagestring商品图片
    channels_shop_product.titlestring商品标题
    channels_shop_product.sales_pricestring商品价格,以分为单位
    channels_shop_product.shop_nicknamestring店铺名称
    channels_shop_product.shop_head_imagestring店铺头像

    视频号订单消息

    返回示例:

    {
       "msgtype" : "channels_shop_order",
       "channels_shop_order" : {
    		"order_id": "ORDER_ID",
    		"product_titles":"PRODUCT_TITLES",
    		"price_wording":"PRICE_WORDING",
    		"state":"STATE",
    		"image_url":"IMAGE_URL",
    		"shop_nickname":"SHOP_NICKNAME"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:channels_shop_order
    channels_shop_orderobj视频号订单消息
    channels_shop_order.order_idstring订单号
    channels_shop_order.product_titlesstring商品标题
    channels_shop_order.price_wordingstring订单价格描述
    channels_shop_order.statestring订单状态
    channels_shop_order.image_urlstring订单缩略图
    channels_shop_order.shop_nicknamestring店铺名称

     

    聊天记录消息

    返回示例:

    {
       "msgtype" : "merged_msg".
       "merged_msg": {
        "title": "群聊的聊天记录",
                    "item": [
                        {
                            "send_time": 1665649618,
                            "msgtype": "text",
                            "sender_name": "发送者",
                            "msg_content": "{\"msgtype\":\"text\",\"text\":{\"content\":\"消息内容\"}}"
                        },
                    ]
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:merged_msg
    merged_msgobj聊天记录消息
    merged_msg.titlestring聊天记录标题
    merged_msg.itemobj[]消息记录内的消息内容
    merged_msg.item.send_timeuint32发送时间
    merged_msg.item.msgtypeuint32消息类型
    merged_msg.item.sender_nameuint32发送者名称
    merged_msg.item.msg_contentstring消息内容,Json字符串,结构可参考本文档消息类型说明

    视频号消息

    返回示例:

    {
       "msgtype" : "channels"
       "channels" : {
          "sub_type": 1,
    	  		"nickname": "视频号名称",
    			"title": "动态标题"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:channels
    目前仅部分返回详细消息内容。
    channelsobj视频号消息
    channels. sub_typeuint32视频号消息类型,1视频号动态、2视频号直播、3视频号名片
    channels. nicknamestring视频号名称
    channels. titlestring视频号动态标题,视频号消息类型为“1视频号动态”时,返回动态标题

     

    会议消息

    返回示例:

    {
       "msgtype" : "meeting"
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:meeting
    目前暂不返回详细消息内容。

    日程消息

    返回示例:

    {
       "msgtype" : "schedule"
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:schedule
    目前暂不返回详细消息内容。

    事件消息

    用户进入会话事件

    通过客服链接进入会话,才会触发该事件。需要注意的是,从客服会话列表的已有会话点击进入,不会触发。
    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "enter_session",
    		"open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
    		"scene": "123",
    		"scene_param": "abc",
    		"welcome_code": "aaaaaa",
    		"wechat_channels": {
    			"nickname": "进入会话的视频号名称",
    			"scene":1
    		}
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:enter_session
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.scenestring进入会话的场景值,获取客服账号链接开发者自定义的场景值
    event.scene_paramstring进入会话的自定义参数,获取客服账号链接返回的url,开发者按规范拼接的scene_param参数
    event.welcome_codestring如果满足发送欢迎语条件(条件为:用户在过去48小时里未收过欢迎语,且未向客服发过消息),会返回该字段。
    可用该welcome_code调用发送事件响应消息接口给客户发送欢迎语。
    event.wechat_channelsobj进入会话的视频号信息,从视频号进入会话才有值
    event.wechat_channels.nicknamestring视频号名称,视频号场景值为1、2、3时返回此项
    event.wechat_channels.shop_nicknamestring视频号小店名称,视频号场景值为4、5时返回此项
    event.wechat_channels.sceneuint32视频号场景值。1:视频号主页,2:视频号直播间商品列表页,3:视频号商品橱窗页,4:视频号小店商品详情页,5:视频号小店订单页

     

    消息发送失败事件

    返回示例:

    {
        "msgtype": "event",
        "event": {
            "event_type": "msg_send_fail",
            "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
            "fail_msgid": "FAIL_MSGID",
            "fail_type": 4
        }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:msg_send_fail
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.fail_msgidstring发送失败的消息msgid
    event.fail_typeuint32失败类型。0-未知原因 1-客服账号已删除 2-应用已关闭 4-会话已过期,超过48小时 5-会话已关闭 6-超过5条限制 8-主体未验证 10-用户拒收 11-企业未有成员登录企业微信App(排查方法:企业至少一个成员通过手机号验证/微信授权登录企业微信App即可)12-发送的消息为客服组件禁发的消息类型

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

    返回示例:

    {
        "msgtype": "event",
        "event": {
            "event_type": "servicer_status_change",
            "servicer_userid": "SERVICER_USERID",
            "status": 2,
            "stop_type": 0,
            "open_kfid": "OPEN_KFID"
        }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:servicer_status_change
    event.servicer_useridstring接待人员userid
    event.statusuint32状态类型。1-接待中 2-停止接待
    event.stop_typeuint32接待人员的状态为「停止接待」的子类型。0:停止接待,1:暂时挂起
    event.open_kfidstring客服账号ID

    会话状态变更事件

    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "session_status_change",
    		"open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
    		"change_type": 1,
    		"old_servicer_userid": "OLD_SERVICER_USERID",
    		"new_servicer_userid": "NEW_SERVICER_USERID",
    		"msg_code": "MSG_CODE"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:session_status_change
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.change_typeuint32变更类型,均为接待人员在企业微信客户端操作触发。1-从接待池接入会话 2-转接会话 3-结束会话 4-重新接入已结束/已转接会话
    event.old_servicer_useridstring老的接待人员userid。仅change_type为2、3和4有值
    event.new_servicer_useridstring新的接待人员userid。仅change_type为1、2和4有值
    event.msg_codestring用于发送事件响应消息的code,仅change_type为1和3时,会返回该字段。
    可用该msg_code调用发送事件响应消息接口给客户发送回复语或结束语。

     

    用户撤回消息事件

    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "user_recall_msg",
            "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
            "recall_msgid": "RECALL_MSGID"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:user_recall_msg
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.recall_msgidstring撤回的消息msgid

    接待人员撤回消息事件

    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "servicer_recall_msg",
            "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
            "recall_msgid": "RECALL_MSGID",
            "servicer_userid": "SERVICER_USERID"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:servicer_recall_msg
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.recall_msgidstring撤回的消息msgid
    event.servicer_useridstring接待人员userid

     

    拒收客户消息变更事件

    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "reject_customer_msg_switch_change",
            "servicer_userid": "Zhangsan",
            "open_kfid": "wkAJ2GCAAASSm4_FhToWMFea0xAFfd3Q",
            "external_userid": "wmAJ2GCAAAme1XQRC-NI-q0_ZM9ukoAw",
            "reject_switch": 1
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:reject_customer_msg_switch_change
    event.servicer_useridstring操作的接待人员userid
    event.open_kfidstring客服账号ID
    event.external_useridstring客户UserID
    event.reject_switchuint32拒收客户消息,1表示接待人员拒收了客户消息,0表示接待人员取消拒收客户消息
    上一篇
    分配客服会话
    下一篇
    发送消息