# 发送模板消息 [调试诊断](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_tools) > 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。 接口英文名：sendTemplateMessage 本接口用于向用户发送模板消息 ## 1. 调用方式 ### HTTPS 调用 ```bash POST https://api.weixin.qq.com/cgi-bin/message/template/send?access_token=ACCESS_TOKEN ``` ### 云调用 - 调用方法：officialAccount.messageTemplate.send - 出入参和 HTTPS 调用相同，调用方式可查看 [云调用](/doc/oplatform/developers/dev/cloudCall.md) 说明文档。 ### 第三方调用 - 本接口支持第三方平台代商家调用。 - 该接口所属的权限集 id 为：7、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" }, { "参数名": "template_id", "类型": "string", "必填": "是", "说明": "所需下发的订阅模板id" }, { "参数名": "url", "类型": "string", "必填": "否", "说明": "模板跳转链接（海外账号没有跳转能力,url 和 miniprogram 同时不填，无跳转，url 和 miniprogram 同时填写，优先跳转小程序）" }, { "参数名": "miniprogram", "类型": "object", "必填": "否", "说明": "跳转小程序时填写（url 和 miniprogram 同时不填，无跳转，page 和 miniprogram 同时填写，优先跳转小程序）" }, { "参数名": "data", "类型": "object", "必填": "是", "说明": "模板内容，需根据模板给定的格式给出（参考注意事项），格式形如 { \"key1\": { \"value\": any }, \"key2\": { \"value\": any } }" }, { "参数名": "client_msg_id", "类型": "string", "必填": "否", "说明": "防重入id。对于同一个openid + client_msg_id, 只发送一条消息,10分钟有效,超过10分钟不保证效果。若无防重入需求，可不填" } ] ``` ### Body.miniprogram `Object Payload` 跳转小程序时填写（url 和 miniprogram 同时不填，无跳转，page 和 miniprogram 同时填写，优先跳转小程序） ```json [ { "参数名": "appid", "类型": "string", "必填": "否", "说明": "小程序appid" }, { "参数名": "pagepath", "类型": "string", "必填": "否", "说明": "小程序跳转路径" } ] ``` ### Body.data `Object Payload` 模板内容，需根据模板给定的格式给出（参考注意事项），格式形如 { "key1": { "value": any }, "key2": { "value": any } } ```json [ { "参数名": "thing.DATA", "类型": "string", "必填": "否", "说明": "事物，可汉字、数字、字母或符号组合，1-20个字符。（即，thing1.value的值最多 20 个字符，thing2.value的值最多 20 个字符，如此类推）\n符号包含了所有可见的正常符号，特殊不可见的符号则不可以。\n\n适用范围：供姓名关键词、地址关键词、机构/组织名关键词选择（如：单位名、银行名、医院名、科室、班级）、品名关键词选择（如：药品名、股票名、课程名、科目名、岗位名）" }, { "参数名": "character_string.DATA", "类型": "string", "必填": "否", "说明": "字符串，可数字、字母或符号组合，32位以内数字、字母或符号\n\n适用范围：供数字/编码/编号/单号/卡号/航班号关键词选择（如：证券编码、设备编号、快递单号、银行卡号、网址）" }, { "参数名": "time.DATA", "类型": "string", "必填": "否", "说明": "时间，24小时制时间格式（支持+年月日），支持HH:MM:SS或者HH:MM，支持填时间段，两个时间点之间用“~”符号连接，例如：「15:01」或「2019年10月1日 15:01」\n\n适用范围：供时间类关键词选择" }, { "参数名": "amount.DATA", "类型": "string", "必填": "否", "说明": "金额，1个币种符号+10位以内纯数字，可带小数，结尾可带“元”\n\n适用范围：供金额类关键词选择" }, { "参数名": "phone_number.DATA", "类型": "string", "必填": "否", "说明": "电话号码，17位以内，数字、符号，例：+86-0766-66888866\n\n适用范围：供电话号码类关键词选择" }, { "参数名": "car_number.DATA", "类型": "string", "必填": "否", "说明": "车牌号码，8位以内，第一位与最后一位可为汉字，其余为字母或数字，如：粤A8Z888挂\n\n适用范围：供车牌号码类关键词选择" }, { "参数名": "const.DATA", "类型": "string", "必填": "否", "说明": "常量，20位以内字符，超过无法下发；另外需要枚举（需将内容提交平台审核，审核通过可下发）只能下发审核通过的字符串和空串\n\n适用范围：供状态/方式/类型/提醒/说明/详情关键词选择（如：支付状态、排队状态、天气状态、物流状态、用药提醒、还款提醒）" } ] ``` ## 3. 返回参数 ### 返回体 `Response Payload` ```json [ { "参数名": "msgid", "类型": "number", "说明": "消息id" }, { "参数名": "errcode", "类型": "number", "说明": "错误码" }, { "参数名": "errmsg", "类型": "string", "说明": "错误描述" } ] ``` ## 4. 注意事项 url和miniprogram都是非必填字段，若都不传则模板无跳转；若都传，会优先跳转至小程序。开发者可根据实际需要选择其中一种跳转方式即可。当用户的微信客户端版本不支持跳小程序时，将会跳转至url。 各 DATA 注意事项： - 符号：表示除中文、英文、数字外的常见符号，不能带有换行等控制字符。 - 时间：格式支持HH:MM:SS或者HH:MM。 - 日期：包含年月日，为y年m月d日，y年m月、m月d日格式，或者用‘-’、‘/’、‘.’符号连接，如2018-01-01，2018/01/01，2018.01.01，2018-01，01-01。 每个模板参数都会以类型为前缀，例如第一个数字模板参数为number01.DATA，第二个为number02.DATA，发送模版通知时，通知内容应于模板参数一致，每个模板参数都会以类型为前缀，例如第一个数字模板参数为number01.DATA，第二个为number02.DATA 例如，模板的内容为 ``` 姓名: {{name01.DATA}} 金额: {{amount01.DATA}} 行程: {{thing01.DATA}} 日期: {{date01.DATA}} ``` 则对应的json为 ```json { "touser": "OPENID", "template_id": "TEMPLATE_ID", "page": "index", "data": { "name01": { "value": "某某" }, "amount01": { "value": "￥100" }, "thing01": { "value": "广州至北京" }, "date01": { "value": "2018-01-01" } } } ``` 如果参数不符合要求，会收到如下提示,并指明不符合要求的字段： ```text { "errcode":47003, "errmsg":"thing01.DATA is invalid" } ``` ## 5. 代码示例 请求示例 ``` json { "touser": "OPENID", "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY", "url": "http://weixin.qq.com/download", "miniprogram": { "appid": "wx9183c0f44097c93", "pagepath": "index?foo=bar" }, "client_msg_id": "MSG_000001", "data": { "time4": { "value": "2025-11-29 10:00:00~12:00:00" }, "thing7": { "value": "TIT园地"// 最多 20 个字符 }, "thing9": { "value": "麦多多-英文,melody"// 最多 20 个字符 }, "thing5": { "value": "可可"// 最多 20 个字符 }, "thing1": { "value": "Group T-melody|Tu"// 最多 20 个字符 } } } ``` 返回示例 ``` json { "errcode":0, "errmsg":"ok", "msgid":200228332 } ``` ## 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 的正确性，或查看是否正在为恰当的公众号调用接口" }, { "错误码": "40003", "错误描述": "invalid openid", "解决方案": "不合法的 OpenID ，请开发者确认 OpenID （该用户）是否已关注公众号，或是否是其他公众号的 OpenID" }, { "错误码": "40008", "错误描述": "invalid message type", "解决方案": "不合法的消息类型" }, { "错误码": "40013", "错误描述": "invalid appid", "解决方案": "不合法的 AppID ，请开发者检查 AppID 的正确性，避免异常字符，注意大小写" }, { "错误码": "40036", "错误描述": "invalid template_id size", "解决方案": "不合法的 template_id 长度" }, { "错误码": "40037", "错误描述": "invalid template_id", "解决方案": "不合法的 template_id" }, { "错误码": "40039", "错误描述": "invalid url size", "解决方案": "不合法的 URL 长度" }, { "错误码": "40249", "错误描述": "", "解决方案": "禁止发送营销内容" }, { "错误码": "43116", "错误描述": "", "解决方案": "模板被限制下发" }, { "错误码": "47003", "错误描述": "", "解决方案": "参数格式错误" } ] ``` ## 7. 适用范围 本接口支持「服务号（仅认证）」账号类型调用。其他账号类型如无特殊说明，均不可调用。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)接口变更日志（1条） 2025 年 11 月 26 日更新 `thing.DATA` 字段描述，文档请求示例以及文档描述优化