# 发送客服消息

[调试诊断](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_tools)

> 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。

接口英文名：sendCustomMessage

本接口用于发送多种类型的客服消息，主要应用在有人工消息处理环节的场景。

当用户和应用产生特定动作的交互时，微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前为48小时）调用客服接口，通过POST一个JSON数据包来发送消息给普通用户。

目前允许的动作列表如下（公众平台会根据运营情况更新该列表，不同动作触发后，允许的客服接口

1. 用户发送信息
2. 点击自定义菜单（仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的）
3. 关注公众号
4. 扫描二维码

各场景的客服消息下发规则：
|场景 |下发额度 |额度有效期|
|---|---|---|
|用户发送消息| 5条 |48小时|
|点击自定义菜单| 3条| 1分钟|
|关注公众号|3条| 1分钟|
|扫描二维码| 3条| 1分钟|

## 1. 调用方式

### HTTPS 调用

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

> **支持加密请求：** 本接口支持服务通信二次加密和签名，可有效防止数据篡改与泄露。[查看详情](/miniprogram/dev/server/getting_started/api_signature.md)

### 云调用

- 调用方法：customerServiceMessage.send

- 出入参和 HTTPS 调用相同，调用方式可查看 [云调用](/doc/oplatform/developers/dev/cloudCall.md) 说明文档。

### 第三方调用

- 本接口支持第三方平台代商家调用。

- 该接口所属的权限集 id 为：1、6、19、100-101

- 服务商获得其中之一权限集授权后，可通过使用 [authorizer_access_token](/doc/oplatform/developers/dev/AuthorizerAccessToken.md) 代商家进行调用，具体可查看 [第三方调用](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/call_interface.md) 说明文档。

## 2. 请求参数

### 查询参数 `Query String Parameters`

```json
[
  {
    "参数名": "access_token",
    "类型": "string",
    "必填": "是",
    "示例": "ACCESS_TOKEN",
    "说明": "接口调用凭证，可使用 [access_token](/doc/service/api/base/api_getaccesstoken)、[authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken.md)"
  }
]
```

### 请求体 `Request Payload`

```json
[
  {
    "参数名": "touser",
    "类型": "string",
    "必填": "是",
    "说明": "用户的 OpenID"
  },
  {
    "参数名": "msgtype",
    "类型": "string",
    "必填": "是",
    "说明": "消息类型。text表示文本消息；image表示图片消息；link表示图文链接；miniprogrampage表示小程序卡片。"
  },
  {
    "参数名": "text",
    "类型": "object",
    "必填": "否",
    "说明": "文本消息，msgtype=\"text\" 时必填"
  },
  {
    "参数名": "image",
    "类型": "object",
    "必填": "否",
    "说明": "图片消息，msgtype=\"image\" 时必填"
  },
  {
    "参数名": "voice",
    "类型": "object",
    "必填": "否",
    "说明": "语音消息，msgtype=\"voice\" 时必填"
  },
  {
    "参数名": "video",
    "类型": "object",
    "必填": "否",
    "说明": "视频消息，msgtype=\"video\" 时必填"
  },
  {
    "参数名": "music",
    "类型": "object",
    "必填": "否",
    "说明": "音乐消息，msgtype=\"music\" 时必填"
  },
  {
    "参数名": "news",
    "类型": "object",
    "必填": "否",
    "说明": "图文消息（点击跳转到外链），msgtype=\"news\" 时必填"
  },
  {
    "参数名": "mpnews",
    "类型": "object",
    "必填": "否",
    "说明": "图文消息（点击跳转到图文消息页面），msgtype=\"mpnews\" 时必填，图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。（草稿灰度完成后，此类型不再支持）"
  },
  {
    "参数名": "mpnewsarticle",
    "类型": "object",
    "必填": "否",
    "说明": "图文消息（点击跳转到图文消息页面），msgtype=\"mpnewsarticle\" 时必填，使用通过 “发布” 系列接口得到的 article_id"
  },
  {
    "参数名": "msgmenu",
    "类型": "object",
    "必填": "否",
    "说明": "菜单消息，msgtype=\"msgmenu\" 时必填"
  },
  {
    "参数名": "wxcard",
    "类型": "object",
    "必填": "否",
    "说明": "卡券信息，msgtype=\"wxcard\"时必填"
  },
  {
    "参数名": "miniprogrampage",
    "类型": "object",
    "必填": "否",
    "说明": "小程序消息，msgtype=\"miniprogrampage\"时必填"
  },
  {
    "参数名": "customservice",
    "类型": "object",
    "必填": "否",
    "说明": "以某个客服账号来发消息"
  },
  {
    "参数名": "aimsgcontext",
    "类型": "object",
    "必填": "否",
    "说明": "ai 消息上下文"
  },
  {
    "参数名": "businessid",
    "类型": "string",
    "必填": "否",
    "说明": "子商户ID，普通账号无需传"
  }
]
```

### Body.text `Object Payload`

文本消息，msgtype="text" 时必填

```json
[
  {
    "参数名": "content",
    "类型": "string",
    "必填": "是",
    "说明": "文本内容，支持插入跳小程序的文字链，\n\n例如「文本内容[点击跳小程序](http://www.qq.com)」\n\n说明： 1.data-miniprogram-appid 项，填写小程序appid，则表示该链接跳小程序； 2.data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数； 3.对于不支持data-miniprogram-appid 项的客户端版本，如果有herf项，则仍然保持跳href中的网页链接； 4.data-miniprogram-appid对应的小程序必须与公众号有绑定关系。"
  }
]
```

### Body.image `Object Payload`

图片消息，msgtype="image" 时必填

```json
[
  {
    "参数名": "media_id",
    "类型": "string",
    "必填": "是",
    "说明": "媒体ID，通过素材上传接口获得。"
  }
]
```

### Body.voice `Object Payload`

语音消息，msgtype="voice" 时必填

```json
[
  {
    "参数名": "media_id",
    "类型": "string",
    "必填": "是",
    "说明": "媒体ID，通过素材上传接口获得。"
  }
]
```

### Body.video `Object Payload`

视频消息，msgtype="video" 时必填

```json
[
  {
    "参数名": "media_id",
    "类型": "string",
    "必填": "是",
    "说明": "媒体ID，通过素材上传接口获得。"
  },
  {
    "参数名": "thumb_media_id",
    "类型": "string",
    "必填": "是",
    "说明": "缩略图媒体ID，通过素材上传接口获得。"
  },
  {
    "参数名": "title",
    "类型": "string",
    "必填": "否",
    "说明": "视频标题"
  },
  {
    "参数名": "description",
    "类型": "string",
    "必填": "否",
    "说明": "视频描述"
  }
]
```

### Body.music `Object Payload`

音乐消息，msgtype="music" 时必填

```json
[
  {
    "参数名": "title",
    "类型": "string",
    "必填": "是",
    "说明": "音乐标题"
  },
  {
    "参数名": "description",
    "类型": "string",
    "必填": "是",
    "说明": "音乐描述"
  },
  {
    "参数名": "musicurl",
    "类型": "string",
    "必填": "是",
    "说明": "音乐链接"
  },
  {
    "参数名": "hqmusicurl",
    "类型": "string",
    "必填": "否",
    "说明": "高质量音乐链接"
  },
  {
    "参数名": "thumb_media_id",
    "类型": "string",
    "必填": "是",
    "说明": "缩略图媒体ID"
  }
]
```

### Body.news `Object Payload`

图文消息（点击跳转到外链），msgtype="news" 时必填

```json
[
  {
    "参数名": "articles",
    "类型": "objarray",
    "必填": "是",
    "说明": "图文消息条数限制在1条以内"
  }
]
```

### Body.mpnews `Object Payload`

图文消息（点击跳转到图文消息页面），msgtype="mpnews" 时必填，图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。（草稿灰度完成后，此类型不再支持）

```json
[
  {
    "参数名": "media_id",
    "类型": "string",
    "必填": "是",
    "说明": "素材ID，通过素材上传接口获得。"
  }
]
```

### Body.mpnewsarticle `Object Payload`

图文消息（点击跳转到图文消息页面），msgtype="mpnewsarticle" 时必填，使用通过 “发布” 系列接口得到的 article_id

```json
[
  {
    "参数名": "article_id",
    "类型": "string",
    "必填": "是",
    "说明": "发布文章ID"
  }
]
```

### Body.msgmenu `Object Payload`

菜单消息，msgtype="msgmenu" 时必填

```json
[
  {
    "参数名": "head_content",
    "类型": "string",
    "必填": "否",
    "说明": "菜单描述"
  },
  {
    "参数名": "list",
    "类型": "objarray",
    "必填": "是",
    "说明": "菜单内容"
  },
  {
    "参数名": "tail_content",
    "类型": "string",
    "必填": "否",
    "说明": "菜单结尾"
  }
]
```

### Body.wxcard `Object Payload`

卡券信息，msgtype="wxcard"时必填

```json
[
  {
    "参数名": "card_id",
    "类型": "string",
    "必填": "是",
    "说明": "卡券ID"
  }
]
```

### Body.miniprogrampage `Object Payload`

小程序消息，msgtype="miniprogrampage"时必填

```json
[
  {
    "参数名": "title",
    "类型": "string",
    "必填": "是",
    "说明": "小程序卡片标题"
  },
  {
    "参数名": "appid",
    "类型": "string",
    "必填": "是",
    "说明": "小程序APPID"
  },
  {
    "参数名": "pagepath",
    "类型": "string",
    "必填": "是",
    "说明": "小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar"
  },
  {
    "参数名": "thumb_media_id",
    "类型": "string",
    "必填": "是",
    "说明": "小程序消息卡片的封面， image 类型的 media_id，通过素材上传图片文件获得，建议大小为 520*416"
  }
]
```

### Body.customservice `Object Payload`

以某个客服账号来发消息

```json
[
  {
    "参数名": "kf_account",
    "类型": "string",
    "必填": "是",
    "说明": "客服账号"
  }
]
```

### Body.aimsgcontext `Object Payload`

ai 消息上下文

```json
[
  {
    "参数名": "is_ai_msg",
    "类型": "number",
    "必填": "否",
    "说明": "消息下方增加灰色 wording “内容由第三方AI生成” 0 不增加 1 增加"
  }
]
```

">

### Body.news.articles(Array) `Object Payload`

图文消息条数限制在1条以内

```json
[
  {
    "参数名": "title",
    "类型": "string",
    "必填": "是",
    "说明": "消息标题"
  },
  {
    "参数名": "description",
    "类型": "string",
    "必填": "是",
    "说明": "消息描述"
  },
  {
    "参数名": "picurl",
    "类型": "string",
    "必填": "是",
    "说明": "封面图片url"
  },
  {
    "参数名": "url",
    "类型": "string",
    "必填": "是",
    "说明": "跳转url"
  }
]
```

">

### Body.msgmenu.list(Array) `Object Payload`

菜单内容

```json
[
  {
    "参数名": "id",
    "类型": "string",
    "必填": "是",
    "说明": "菜单值"
  },
  {
    "参数名": "content",
    "类型": "string",
    "必填": "是",
    "说明": "菜单项"
  }
]
```

## 3. 返回参数

### 返回体 `Response Payload`

```json
[
  {
    "参数名": "errcode",
    "类型": "number",
    "说明": "错误码"
  },
  {
    "参数名": "errmsg",
    "类型": "string",
    "说明": "错误描述"
  }
]
```

## 4. 注意事项

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

## 5. 代码示例

### 5.1 发送文本消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":`文本内容<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>`
    },
    "customservice":{
         "kf_account": "test1@kftest"
    }
}
```

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.2 发送图片消息

请求示例

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

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.3 发送语音消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"voice",
    "voice":
    {
      "media_id":"MEDIA_ID"
    }
}
````

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.4 发送视频消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"video",
    "video":
    {
      "media_id":"MEDIA_ID",
      "thumb_media_id":"MEDIA_ID",
      "title":"TITLE",
      "description":"DESCRIPTION"
    }
}
````

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.5 发送音乐消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"music",
    "music":
    {
      "title":"MUSIC_TITLE",
      "description":"MUSIC_DESCRIPTION",
      "musicurl":"MUSIC_URL",
      "hqmusicurl":"HQ_MUSIC_URL",
      "thumb_media_id":"THUMB_MEDIA_ID" 
    }
}
````

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.6 发送外链图文消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"news",
    "news":{
        "articles": [
         {
             "title":"Happy Day",
             "description":"Is Really A Happy Day",
             "url":"URL",
             "picurl":"PIC_URL"
         }
         ]
    }
}
````

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.7 发送公众号图文消息（废弃）

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"mpnews",
    "mpnews":
    {
         "media_id":"MEDIA_ID"
    }
}
```

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.8 发送公众号图文消息

请求示例

``` json
{
    "touser":"OPENID",
    "msgtype":"mpnewsarticle",
    "mpnewsarticle": {
         "article_id":"ARTICLE_ID"
    }
}
```

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.9 发送菜单消息

请求示例

``` json
{
  "touser": "OPENID",
  "msgtype": "msgmenu",
  "msgmenu": {
    "head_content": "您对本次服务是否满意呢? ",
    "list": [
      {
        "id": "101",
        "content": "满意"
      },
      {
        "id": "102",
        "content": "不满意"
      }
    ],
    "tail_content": "欢迎再次光临"
  }
}
```

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.10 发送卡券消息

请求示例

``` json
{
  "touser":"OPENID", 
  "msgtype":"wxcard",
  "wxcard":
  {              
   "card_id":"123dsdajkasd231jhksad"        
   }
}
```

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

### 5.11 发送小程序消息

请求示例

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

返回示例

``` json
{
  "errcode": 0,
  "errmsg": "ok"
}
```

## 6. 错误码

以下是本接口的错误码列表，其他错误码可参考 [通用错误码](/doc/oplatform/developers/errCode/README.md)；调用接口遇到报错，可使用官方提供的 [API 诊断工具](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_errcode) 辅助定位和分析问题。

```json
[
  {
    "错误码": "-1",
    "错误描述": "system error",
    "解决方案": "系统繁忙，此时请开发者稍候再试"
  },
  {
    "错误码": "40001",
    "错误描述": "invalid credential  access_token isinvalid or not latest",
    "解决方案": "获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口"
  },
  {
    "错误码": "40013",
    "错误描述": "invalid appid",
    "解决方案": "不合法的 AppID ，请开发者检查 AppID 的正确性，避免异常字符，注意大小写"
  },
  {
    "错误码": "70000",
    "错误描述": "为保护未成年人权益，该条消息发送失败",
    "解决方案": ""
  }
]
```

## 7. 适用范围

本接口在不同账号类型下的可调用情况：

```json
[
  {
    "小程序": "✔",
    "公众号": "仅认证",
    "服务号": "仅认证",
    "小游戏": "✔"
  }
]
```

- ✔：该账号可调用此接口。
- 仅认证：表示仅允许企业主体已认证账号调用，未认证或不支持认证的账号无法调用。
- 其他未明确声明的账号类型，如无特殊说明，均不可调用此接口。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)接口变更日志（2条）
2025 年 11 月 26 日修改 AI 标记的描述
2025 年 11 月 24 日支持“内容由第三方 ai 标识”的灰色 wording