[TOC] ## 概述 当用户在主动发送消息给微信客服时，企业可在48小时内调用该接口发送消息给用户，最多可发送5条消息给客户；若用户继续发送消息，企业可再次下发消息。 支持发送消息类型：文本、图片、语音、视频、文件、图文、小程序、菜单消息、地理位置。 目前该接口允许下发消息条数和下发时限如下： | 用户动作 | 允许下发条数限制 | 下发时限 | | --- | --- | --- | | 用户发送消息 | 5条 | 48 小时 | ## 接口定义 **请求方式**: POST(**HTTPS**) **请求地址**: https://qyapi.weixin.qq.com/cgi-bin/kf/send\_msg?access\_token=ACCESS\_TOKEN **参数说明：** | 参数 | 是否必须 | 说明 | | --- | --- | --- | | access\_token | 是 | 调用接口凭证 | **权限说明**: 仅允许微信客服的Secret所获取的access\_token调用。 **返回结果**: ~~~ { "errcode": 0, "errmsg": "ok", "msgid": "MSG_ID"} ~~~ **参数说明**: | 参数 | 类型 | 说明 | | --- | --- | --- | | errcode | int32 | 返回码 | | errmsg | string | 错误码描述 | | msgid | string | 消息ID。如果请求参数指定了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" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：text | | text | 是 | obj | 文本消息 | | text.content | 是 | string | 消息内容，最长不超过2048个字节 | ### 图片消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "image", "image" : { "media_id" : "MEDIA_ID" }} ~~~ **请求参数：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：image | | image | 是 | obj | 图片消息 | | image.media\_id | 是 | string | 图片文件id，可以调用上传临时素材接口获取 | ### 语音消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgtype" : "voice", "voice" : { "media_id" : "MEDIA_ID" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：voice | | voice | 是 | obj | 语音消息 | | voice.media\_id | 是 | string | 语音文件id，可以调用[上传临时素材](https://www.kancloud.cn/dabashan/qiwei/2376081#_7)接口获取 | ### 视频消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "video", "video" : { "media_id" : "MEDIA_ID" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：video | | video | 是 | obj | 视频消息 | | video.media\_id | 是 | string | 视频媒体文件id，可以调用[上传临时素材](https://www.kancloud.cn/dabashan/qiwei/2376081#_7)接口获取 | **视频消息展现：**  ### 文件消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "file", "file" : { "media_id" : "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：file | | file | 是 | obj | 文件消息 | | file.media\_id | 是 | string | 文件id，可以调用上传临时素材接口获取 | **文件消息展现：**  ### 图文链接消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "link", "link" : { "title" : "企业如何增长？企业微信给出3个答案", "desc" : "今年中秋节公司有豪礼相送", "url" : "URL", "thumb_media_id": "MEDIA_ID" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：link | | link | 是 | obj | 链接消息 | | link.title | 是 | string | 标题，不超过128个字节，超过会自动截断 | | link.desc | 否 | string | 描述，不超过512个字节，超过会自动截断 | | link.url | 是 | string | 点击后跳转的链接。 最长2048字节，请确保包含了协议头(http/https) | | link.thumb\_media\_id | 是 | string | 缩略图的media\_id, 可以通过[素材管理](https://www.kancloud.cn/dabashan/qiwei/2376081)接口获得。此处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" }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：miniprogram | | miniprogram | 是 | obj | 小程序消息 | | miniprogram.appid | 是 | string | 小程序appid，必须是关联到企业的小程序应用 | | miniprogram.title | 否 | string | 小程序消息标题，最多64个字节，超过会自动截断 | | miniprogram.thumb\_media\_id | 是 | string | 小程序消息封面的mediaid，封面图建议尺寸为520\*416 | | miniprogram.pagepath | 是 | string | 点击消息卡片后进入的小程序页面路径。注意路径要以.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": "欢迎再次光临" }} ~~~ **参数说明：** | 参数 | 必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：msgmenu | | msgmenu | 是 | obj | 菜单消息 | | msgmenu.head\_content | 否 | string | 起始文本 不多于1024字节 | | msgmenu.list | 否 | obj\[\] | 菜单项配置 | | msgmenu.list.type | 是 | string | 菜单类型。 `click`\-回复菜单`view`\-超链接菜单`miniprogram`\-小程序菜单 | | msgmenu.list.click | 否 | obj | type为`click`的菜单项 | | msgmenu.list.click.id | 否 | string | 菜单ID。 不少于1字节 不多于64字节 | | msgmenu.list.click.content | 是 | string | 菜单显示内容 不少于1字节 不多于128字节 | | msgmenu.list.view | 否 | obj | type为`view`的菜单项 | | msgmenu.list.view.url | 是 | string | 点击后跳转的链接。 不少于1字节 不多于2048字节 | | msgmenu.list.view.content | 是 | string | 菜单显示内容。 不少于1字节 不多于1024字节 | | msgmenu.list.miniprogram | 否 | obj | type为`miniprogram`的菜单项 | | msgmenu.list.miniprogram.appid | 是 | string | 小程序appid。 不少于1字节 不多于32字节 | | msgmenu.list.miniprogram.pagepath | 是 | string | 点击后进入的小程序页面。 不少于1字节 不多于1024字节 | | msgmenu.list.miniprogram.content | 是 | string | 菜单显示内容。 不多于1024字节 | | msgmenu.tail\_content | 否 | string | 结束文本 不多于1024字节 | 其中，“满意”和“不满意”两个菜单当用户点击后，用户会自动回复一条文本消息，同时附带对应的菜单ID。 **菜单消息展现：**  ### 地理位置消息 **请求示例：** ~~~ { "touser" : "EXTERNAL_USERID", "open_kfid": "OPEN_KFID", "msgid": "MSGID", "msgtype" : "location", "location": { "name": "测试小区", "address": "实例小区，不真实存在，经纬度无意义", "latitude": 0, "longitude": 0 }} ~~~ **参数说明：** | 参数 | 是否必须 | 类型 | 说明 | | --- | --- | --- | --- | | touser | 是 | string | 指定接收消息的客户UserID | | open\_kfid | 是 | string | 指定发送消息的客服帐号ID | | msgid | 否 | string | 指定消息ID | | msgtype | 是 | string | 消息类型，此时固定为：location | | location | 是 | obj | 地理位置消息 | | location.name | 否 | string | 位置名 | | location.address | 否 | string | 地址详情说明 | | location.latitude | 是 | float | 纬度，浮点数，范围为90 ~ -90 | | location.longitude | 是 | float | 经度，浮点数，范围为180 ~ -180 |