微信小程序 send

customerServiceMessage.send

本接口应在服务器端调用，详细说明参见服务端API。

本接口支持云调用。需开发者工具版本 >= 1.02.1904090（最新稳定版下载）
wx-server-sdk >= 0.4.0

发送客服消息给用户。详细规则见 发送客服消息

调用方式：

• HTTPS 调用
• 云调用

HTTPS 调用

请求地址

POST https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

请求参数

属性	类型	默认值	必填	说明
access_token	string		是	接口调用凭证
touser	string		是	用户的 OpenID
msgtype	string		是	消息类型
text	Object		是	文本消息，msgtype="text" 时必填
image	Object		是	图片消息，msgtype="image" 时必填
link	Object		是	图文链接，msgtype="link" 时必填
miniprogrampage	Object		是	小程序卡片，msgtype="miniprogrampage" 时必填

msgtype 的合法值

值	说明	最低版本
text	文本消息
image	图片消息
link	图文链接
miniprogrampage	小程序卡片

text 的结构

属性	类型	默认值	必填	说明
content	string		是	文本消息内容

image 的结构

属性	类型	默认值	必填	说明
media_id	string		是	发送的图片的媒体ID，通过 新增素材接口 上传图片文件获得。

link 的结构

属性	类型	默认值	必填	说明
title	string		是	消息标题
description	string		是	图文链接消息
url	string		是	图文链接消息被点击后跳转的链接
thumb_url	string		是	图文链接消息的图片链接，支持 JPG、PNG 格式，较好的效果为大图 640 X 320，小图 80 X 80

miniprogrampage 的结构

属性	类型	默认值	必填	说明
title	string		是	消息标题
pagepath	string		是	小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar
thumb_media_id	string		是	小程序消息卡片的封面， image 类型的 media_id，通过 新增素材接口 上传图片文件获得，建议大小为 520*416

返回值

Object

返回的 JSON 数据包

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息

errcode 的合法值

值	说明	最低版本
0	请求成功
-1	系统繁忙，此时请开发者稍候再试
40001	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的小程序调用接口
40002	不合法的凭证类型
40003	不合法的 OpenID，请开发者确认 OpenID 是否是其他小程序的 OpenID
45015	回复时间超过限制
45047	客服接口下行条数超过上限
48001	API 功能未授权，请确认小程序已获得该接口

下发消息示例

发送文本消息

{
  "touser":"OPENID",
  "msgtype":"text",
  "text":
  {
    "content":"Hello World"
  }
}

发送文本消息时，支持添加可跳转小程序的文字连接

文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>

说明：

1. data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序；
2. data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；
3. 对于不支持 data-miniprogram-appid 项的客户端版本（6.5.16 以下），如果有 herf 项，则仍然保持跳 href 中的链接；
4. 小程序发带小程序文字链的文本消息，data-miniprogram-appid必须是该小程序的appid。

发送图片消息

{
  "touser":"OPENID",
  "msgtype":"image",
  "image": {
    "media_id":"MEDIA_ID"
  }
}

发送图文链接

每次可以发送一个图文链接

{
  "touser": "OPENID",
  "msgtype": "link",
  "link": {
    "title": "Happy Day",
    "description": "Is Really A Happy Day",
    "url": "URL",
    "thumb_url": "THUMB_URL"
  }
}

发送小程序卡片

{
 "touser":"OPENID",
 "msgtype":"miniprogrampage",
 "miniprogrampage": {
   "title":"title",
   "pagepath":"pagepath",
   "thumb_media_id":"thumb_media_id"
 }
}

云调用

云调用是小程序·云开发提供的在云函数中调用微信开放接口的能力，需要在云函数中通过 wx-server-sdk 使用。

接口方法

openapi.customerServiceMessage.send

需在 config.json 中配置 customerServiceMessage.send API 的权限，详情

请求参数

属性	类型	默认值	必填	说明
touser	string		是	用户的 OpenID
msgtype	string		是	消息类型
text	Object		是	文本消息，msgtype="text" 时必填
image	Object		是	图片消息，msgtype="image" 时必填
link	Object		是	图文链接，msgtype="link" 时必填
miniprogrampage	Object		是	小程序卡片，msgtype="miniprogrampage" 时必填

msgtype 的合法值

值	说明	最低版本
text	文本消息
image	图片消息
link	图文链接
miniprogrampage	小程序卡片

text 的结构

属性	类型	默认值	必填	说明
content	string		是	文本消息内容

image 的结构

属性	类型	默认值	必填	说明
mediaId	string		是	发送的图片的媒体ID，通过 新增素材接口 上传图片文件获得。

link 的结构

属性	类型	默认值	必填	说明
title	string		是	消息标题
description	string		是	图文链接消息
url	string		是	图文链接消息被点击后跳转的链接
thumbUrl	string		是	图文链接消息的图片链接，支持 JPG、PNG 格式，较好的效果为大图 640 X 320，小图 80 X 80

miniprogrampage 的结构

属性	类型	默认值	必填	说明
title	string		是	消息标题
pagepath	string		是	小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar
thumbMediaId	string		是	小程序消息卡片的封面， image 类型的 media_id，通过 新增素材接口 上传图片文件获得，建议大小为 520*416

返回值

Object

返回的 JSON 数据包

属性	类型	说明
errCode	number	错误码
errMsg	string	错误信息

errCode 的合法值

值	说明	最低版本
0	成功

异常

Object

抛出的异常

属性	类型	说明
errCode	number	错误码
errMsg	string	错误信息

errCode 的合法值

值	说明	最低版本
-1	系统繁忙，此时请开发者稍候再试
40001	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的小程序调用接口
40002	不合法的凭证类型
40003	不合法的 OpenID，请开发者确认 OpenID 是否是其他小程序的 OpenID
45015	回复时间超过限制
45047	客服接口下行条数超过上限
48001	API 功能未授权，请确认小程序已获得该接口

下发消息示例

发送文本消息

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.customerServiceMessage.send({
        touser: 'OPENID',
        msgtype: 'text',
        text: {
          content: 'Hello World'
        }
      })
    return result
  } catch (err) {
    return err
  }
}

发送文本消息时，支持添加可跳转小程序的文字连接

文本内容...<a href="http://www.qq.com" rel="external nofollow" target="_blank"  rel="external nofollow" target="_blank"  data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>

说明：

1. data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序；
2. data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；
3. 对于不支持 data-miniprogram-appid 项的客户端版本（6.5.16 以下），如果有 herf 项，则仍然保持跳 href 中的链接；
4. 小程序发带小程序文字链的文本消息，data-miniprogram-appid必须是该小程序的appid。

发送图片消息

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.customerServiceMessage.send({
        touser: 'OPENID',
        msgtype: 'image',
        image: {
          mediaId: 'MEDIA_ID'
        }
      })
    return result
  } catch (err) {
    return err
  }
}

发送图文链接

每次可以发送一个图文链接

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.customerServiceMessage.send({
        touser: 'OPENID',
        msgtype: 'link',
        link: {
          title: 'Happy Day',
          description: 'Is Really A Happy Day',
          url: 'URL',
          thumbUrl: 'THUMB_URL'
        }
      })
    return result
  } catch (err) {
    return err
  }
}

发送小程序卡片

const cloud = require('wx-server-sdk')
cloud.init()
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.customerServiceMessage.send({
        touser: 'OPENID',
        msgtype: 'miniprogrampage',
        miniprogrampage: {
          title: 'title',
          pagepath: 'pagepath',
          thumbMediaId: 'thumb_media_id'
        }
      })
    return result
  } catch (err) {
    return err
  }
}