-

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
  }
}