微信小程序开发文档微信小程序 send

2024-02-25 开发教程微信小程序开发文档匿名 3℃

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>

说明：

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

说明：

data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序；
data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；
对于不支持 data-miniprogram-appid 项的客户端版本（6.5.16 以下），如果有 herf 项，则仍然保持跳 href 中的链接；
小程序发带小程序文字链的文本消息，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
  }
}

上一节：微信小程序 getTempMedia

下一节：微信小程序 setTyping

"微信小程序开发文档"的目录

微信小程序开发文档 微信小程序 send

customerServiceMessage.send

HTTPS 调用

请求地址

请求参数

返回值

Object

下发消息示例

发送文本消息

说明：

发送图片消息

发送图文链接

发送小程序卡片

云调用

接口方法

请求参数

返回值

Object

异常

Object

下发消息示例

发送文本消息

说明：

发送图片消息

发送图文链接

发送小程序卡片

微信小程序开发文档微信小程序 send