第三方应用开发 服务端API 微信客服 会话分配与消息收发 接收消息和事件
接收消息和事件

目录

  • 概述
  • 回调事件
  • 读取消息
  •       接口定义
  •       消息类型
  •             文本消息
  •             图片消息
  •             语音消息
  •             视频消息
  •             文件消息
  •             位置消息
  •             链接消息
  •             名片消息
  •             小程序消息
  •             菜单消息
  •             事件消息
  •                   用户进入会话事件
  •                   消息发送失败事件
  •                   接待人员接待状态变更事件
  •                   会话状态变更事件
  • 概述

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

    回调事件

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

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

    说明

    参数说明
    ToUserName企业微信CorpID
    CreateTime消息创建时间,unix时间戳
    MsgType消息的类型,此时固定为:event
    Event事件的类型,此时固定为:kf_msg_or_event
    Token调用拉取消息接口时,需要传此token,用于校验请求的合法性

     

    读取消息

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

    接口定义

    请求方式: 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
    }

    参数说明:

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

    权限说明:

    • 企业需要使用“微信客服”secret所获取的accesstoken来调用(accesstoken如何获取?),同时开启“会话消息管理”开关
    • 第三方应用需具有“微信客服->管理帐号、分配会话和收发消息”权限
    • 代开发自建应用需具有“微信客服->管理帐号、分配会话和收发消息”权限

     

    返回结果:

    {
        "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" : "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": "进入会话的视频号名称"
    		}
       }
    }

    参数说明:

    参数类型说明
    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视频号名称

     

    消息发送失败事件

    返回示例:

    {
       "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条限制 7-未绑定视频号 8-主体未验证 9-未绑定视频号且主体未验证 10-用户拒收
    接待人员接待状态变更事件

    返回示例:

    {
       "msgtype" : "event",
       "event" : {
            "event_type": "servicer_status_change",
    		"servicer_userid": "SERVICER_USERID",
    		"status": 1,
    		"open_kfid": "OPEN_KFID"
       }
    }

    参数说明:

    参数类型说明
    msgtypestring消息类型,此时固定为:event
    eventobj事件消息
    event.event_typestring事件类型。此处固定为:servicer_status_change
    event.servicer_useridstring接待人员userid
    event.statusuint32状态类型。1-接待中 2-停止接待
    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调用发送事件响应消息接口给客户发送回复语或结束语。
    上一篇
    分配客服会话
    下一篇
    发送消息