企业内部开发 服务端API 微信客服 会话分配与消息收发 发送消息
发送消息

目录

  • 概述
  • 接口定义
  • 消息类型
  •       文本消息
  •       图片消息
  •       语音消息
  •       视频消息
  •       文件消息
  •       图文链接消息
  •       小程序消息
  •       菜单消息
  •       地理位置消息
  • 概述

    当微信客户处于“新接入待处理”或“由智能助手接待”状态下,可调用该接口给用户发送消息。
    注意仅当微信客户在主动发送消息给客服后的48小时内,企业可发送消息给客户,最多可发送5条消息;若用户继续发送消息,企业可再次下发消息。
    支持发送消息类型:文本、图片、语音、视频、文件、图文、小程序、菜单消息、地理位置。
    目前该接口允许下发消息条数和下发时限如下:

    用户动作允许下发条数限制下发时限
    用户发送消息5条48 小时

    接口定义

    请求方式: POST(HTTPS)

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

    参数说明:

    参数是否必须说明
    access_token调用接口凭证


    权限说明:

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

     

    返回结果:

    {
        "errcode": 0,
        "errmsg": "ok",
        "msgid": "MSG_ID"
    }

    参数说明:

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    msgidstring消息ID。如果请求参数指定了msgid,则原样返回,否则系统自动生成并返回。若指定msgid,开发者需确保客服账号内唯一,否则接口返回错误。
    不多于32字节
    字符串取值范围(正则表达式):[0-9a-zA-Z_-]*

    消息类型

    文本消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "text",
       "text" : {
           "content" : "你购买的物品已发货,可点击链接查看物流状态http://work.weixin.qq.com/xxxxxx"
       }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:text
    textobj文本消息
    text.contentstring消息内容,最长不超过2048个字节

     

    图片消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "image",
       "image" : {
            "media_id" : "MEDIA_ID"
       }
    }

    请求参数:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:image
    imageobj图片消息
    image.media_idstring图片文件id,可以调用上传临时素材接口获取

    语音消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgtype" : "voice",
       "voice" : {
            "media_id" : "MEDIA_ID"
       }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:voice
    voiceobj语音消息
    voice.media_idstring语音文件id,可以调用上传临时素材接口获取

    视频消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "video",
       "video" : {
            "media_id" : "MEDIA_ID"
       }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:video
    videoobj视频消息
    video.media_idstring视频媒体文件id,可以调用上传临时素材接口获取


    视频消息展现:

    文件消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "file",
       "file" : {
            "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o"
       }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:file
    fileobj文件消息
    file.media_idstring文件id,可以调用上传临时素材接口获取

    文件消息展现:

    图文链接消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "link",
       "link" :
       {
               "title" : "企业如何增长?企业微信给出3个答案",
               "desc" : "今年中秋节公司有豪礼相送",
               "url" : "URL",
    		   "thumb_media_id": "MEDIA_ID"
       }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:link
    linkobj链接消息
    link.titlestring标题,不超过128个字节,超过会自动截断
    link.descstring描述,不超过512个字节,超过会自动截断
    link.urlstring点击后跳转的链接。 最长2048字节,请确保包含了协议头(http/https)
    link.thumb_media_idstring缩略图的media_id, 可以通过素材管理接口获得。此处thumb_media_id即上传接口返回的media_id

    图文链接消息展现:

     

    小程序消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "miniprogram"
       "miniprogram" : {
           "appid": "APPID",
           "title": "欢迎报名夏令营",
           "thumb_media_id": "MEDIA_ID",
           "pagepath": "PAGE_PATH"
       }
    }

     

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:miniprogram
    miniprogramobj小程序消息
    miniprogram.appidstring小程序appid
    miniprogram.titlestring小程序消息标题,最多64个字节,超过会自动截断
    miniprogram.thumb_media_idstring小程序消息封面的mediaid,封面图建议尺寸为520*416
    miniprogram.pagepathstring点击消息卡片后进入的小程序页面路径。注意路径要以.html为后缀,否则在微信中打开会提示找不到页面

     

    菜单消息

    请求示例:

    {
      "touser": "EXTERNAL_USERID",
      "open_kfid": "OPEN_KFID",
      "msgid": "MSGID",
      "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": "欢迎再次光临"
      }
    }

     

    参数说明:

    参数必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:msgmenu
    msgmenuobj菜单消息
    msgmenu.head_contentstring起始文本
    不多于1024字节
    msgmenu.listobj[]菜单项配置
    msgmenu.list.typestring菜单类型。
    click-回复菜单 view-超链接菜单 miniprogram-小程序菜单
    msgmenu.list.clickobjtype为click的菜单项
    msgmenu.list.click.idstring菜单ID。
    不少于1字节
    不多于128字节
    msgmenu.list.click.contentstring菜单显示内容
    不少于1字节
    不多于128字节
    msgmenu.list.viewobjtype为view的菜单项
    msgmenu.list.view.urlstring点击后跳转的链接。
    不少于1字节
    不多于2048字节
    msgmenu.list.view.contentstring菜单显示内容。
    不少于1字节
    不多于1024字节
    msgmenu.list.miniprogramobjtype为miniprogram的菜单项
    msgmenu.list.miniprogram.appidstring小程序appid。
    不少于1字节
    不多于32字节
    msgmenu.list.miniprogram.pagepathstring点击后进入的小程序页面。
    不少于1字节
    不多于1024字节
    msgmenu.list.miniprogram.contentstring菜单显示内容。
    不多于1024字节
    msgmenu.tail_contentstring结束文本
    不多于1024字节

    其中,“满意”和“不满意”两个菜单当用户点击后,用户会自动回复一条文本消息,同时附带对应的菜单ID。

    菜单消息展现:

     

    地理位置消息

    请求示例:

    {
       "touser" : "EXTERNAL_USERID",
       "open_kfid": "OPEN_KFID",
       "msgid": "MSGID",
       "msgtype" : "location",
       "location": {
                "name": "测试小区",
                "address": "实例小区,不真实存在,经纬度无意义",
                "latitude": 0,
                "longitude": 0
        }
    }

    参数说明:

    参数是否必须类型说明
    touserstring指定接收消息的客户UserID
    open_kfidstring指定发送消息的客服帐号ID
    msgidstring指定消息ID
    msgtypestring消息类型,此时固定为:location
    locationobj地理位置消息
    location.namestring位置名
    location.addressstring地址详情说明
    location.latitudefloat纬度,浮点数,范围为90 ~ -90
    location.longitudefloat经度,浮点数,范围为180 ~ -180
    上一篇
    接收消息和事件
    下一篇
    发送欢迎语等事件响应消息