云开发 /sendSms
# cloudbase.sendSms
> 本接口应在服务器端调用，详细说明参见[服务端API](https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/backend-api.html)。
> 本接口支持[云调用](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html)。需开发者工具版本 >= `1.02.1904090`（最新[稳定版下载](https://developers.weixin.qq.com/miniprogram/dev/devtools/stable.html)），`wx-server-sdk` >= `0.4.0`
发送支持打开云开发静态网站的短信，该 H5 可以打开小程序。详情可[参考静态网站 H5 跳小程序](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/staticstorage/jump-miniprogram.html)
**短信内容**
短信由签名和正文内容组成：
短信签名是位于短信正文前【】中的署名，小程序发送短信时，签名为小程序名称。
- 正文内容是由短信模板和变量构成，例：{1}，跳转小程序 {2} 回 T 退订，模板参数中 {1}，{2} 是变量：
- {1} ：用户可自定义传入的内容，当前最长为30个字。
- {2} ：用户传入的静态托管的地址，例如 /action/index.html?action=double12。 示例：【云开发】能力上新，跳转小程序 https://tcbe.cn/VcdrUJK0 回 T 退订
**短信资源包**
前往“开发者工具 - 云开发 - 设置 - 环境设置 - 资源包”中购买。
**第三方代开发**
小程序需要将【短信服务】或【云开发】权限集授权给第三方，第三方才可代小程序调用此接口。第三方在调用接口时，可选择使用第三方的环境或小程序的环境，默认使用小程序的环境。在resource_appid填入第三方的appid，在 env 填入第三方账号下的环境，即可使用第三方的环境。
调用方式：
- [HTTPS 调用](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/cloudbase/cloudbase.sendSms.html#method-http)
- [云调用](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/cloudbase/cloudbase.sendSms.html#method-cloud)
## HTTPS 调用
### 请求地址
```text
POST https://api.weixin.qq.com/tcb/sendsms?access_token=TOKEN
```
### 请求参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
| :------------------------------------ | :------------- | :-------- | :--- | :----------------------------------------------------------- |
| access_token / cloudbase_access_token | string | | 是 | [接口调用凭证](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/access-token/auth.getAccessToken.html) |
| env | string | | 是 | [环境 ID](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/quickstart.html#_2-开通云开发、创建环境) |
| phone_number_list | Array.<string> | | 是 | 手机号列表，单次请求最多支持 1000 个境内手机号，**手机号必须以`+86`开头** |
| sms_type | string | Marketing | 是 | 短信类型，营销类短信：Marketing；通知类短信：Notification |
| content | string | | 是 | sms_type="Marketing" 时必填，自定义短信内容，一条短信最多为70个字。可自定义内容最多为 30 个字符，详情参考[短信规则](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/staticstorage/msg-miniprogram.html) |
| path | string | | 是 | sms_type="Marketing" 时必填，云开发静态网站 path，**不需要指定域名**，例如`/index.html` |
| template_id | string | | 是 | sms_type="Notification" 时必填，模版 ID |
| template_param_list | Array.<string> | | 是 | sms_type="Notification" 时必填，短信模版变量数组 |
| use_short_name | bool | false | 否 | 是否使用小程序简称 |
| resource_appid | string | | 否 | 资源方appid，第三方代开发时可填第三方 appid 或小程序appid，应为所填环境所属的账号APPID |
### 返回值
### Object
返回的 JSON 数据包
| 属性 | 类型 | 说明 |
| :--------------- | :------------- | :----------- |
| errcode | number | 错误码 |
| errmsg | string | 错误信息 |
| send_status_list | Array.<Object> | 开放数据列表 |
**errcode 的合法值**
| 值 | 说明 | 最低版本 |
| :------ | :----------------------------- | :------- |
| 0 | 请求成功 | |
| -1 | 系统繁忙，此时请开发者稍候再试 | |
| -501007 | 参数有误，具体原因参考 errmsg | |
| -601027 | 无效的环境 | |
| -601032 | 小程序昵称不能为空 | |
| -601033 | 仅支持非个人主体小程序 | |
| -607004 | 无效的 URL Link | |
**send_status_list 的结构**
| 属性 | 类型 | 说明 |
| :----------- | :----- | :----------------- |
| serial_no | string | 发送流水号 |
| phone_number | string | 手机号码 |
| code | string | 短信请求错误码 |
| message | string | 短信请求错误码描述 |
| iso_code | string | 国家码或地区码 |
### 营销类短信请求数据示例
```json
{
"env":"online-12345678910",
"phone_number_list":[
"+8612345678910"
],
"sms_type": "Marketing",
"content":"发布了新的能力",
"path":"/index.html",
"use_short_name": true
}
```
### 通知类短信请求数据示例
```json
{
"env":"online-12345678910",
"phone_number_list":[
"+8612345678910"
],
"sms_type": "Notification",
"template_id": "923584",
"template_param_list": ["商品", "/index.html"]
}
```
### 返回数据示例
```json
{
"errcode":0,
"send_status_list":[
{
"serial_no":"8:gFIqWUHzllUyOFRHgeu20201231",
"phone_number":"+8612345678910",
"code":"Ok",
"message":"send success",
"iso_code":""
}
]
}
```
## 云调用
> [云调用](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html)是微信云开发提供的在云函数中调用微信开放接口的能力，需要在云函数中通过 `wx-server-sdk` 使用。
### 接口方法
```js
openapi.cloudbase.sendSms
```
> 需在 `config.json` 中配置 `cloudbase.sendSms` API 的权限，[详情](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html#usage-3)
### 请求参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
| :---------------- | :------------- | :-------- | :--- | :----------------------------------------------------------- |
| env | string | | 是 | [环境 ID](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/quickstart.html#_2-开通云开发、创建环境) |
| phoneNumberList | Array.<string> | | 是 | 手机号列表，单次请求最多支持 1000 个境内手机号，**手机号必须以`+86`开头** |
| smsType | string | Marketing | 是 | 短信类型，营销类短信：Marketing；通知类短信：Notification |
| content | string | | 是 | sms_type="Marketing" 时必填，自定义短信内容，一条短信最多为70个字。可自定义内容最多为 30 个字符，详情参考[短信规则](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/staticstorage/msg-miniprogram.html) |
| path | string | | 是 | sms_type="Marketing" 时必填，云开发静态网站 path，**不需要指定域名**，例如`/index.html` |
| templateId | string | | 是 | sms_type="Notification" 时必填，模版 ID |
| templateParamList | Array.<string> | | 是 | sms_type="Notification" 时必填，短信模版变量数组 |
| useShortName | bool | false | 否 | 是否使用小程序简称 |
| resourceAppid | string | | 否 | 资源方appid，第三方代开发时可填第三方 appid 或小程序appid，应为所填环境所属的账号APPID |
### 返回值
### Object
返回的 JSON 数据包
| 属性 | 类型 | 说明 |
| :------------- | :------------- | :----------- |
| errCode | number | 错误码 |
| errMsg | string | 错误信息 |
| sendStatusList | Array.<Object> | 开放数据列表 |
**errCode 的合法值**
| 值 | 说明 | 最低版本 |
| :--- | :--- | :------- |
| 0 | 成功 | |
**sendStatusList 的结构**
| 属性 | 类型 | 说明 |
| :---------- | :----- | :----------------- |
| serialNo | string | 发送流水号 |
| phoneNumber | string | 手机号码 |
| code | string | 短信请求错误码 |
| message | string | 短信请求错误码描述 |
| isoCode | string | 国家码或地区码 |
### 异常
### Object
抛出的异常
| 属性 | 类型 | 说明 |
| :------ | :----- | :------- |
| errCode | number | 错误码 |
| errMsg | string | 错误信息 |
**errCode 的合法值**
| 值 | 说明 | 最低版本 |
| :------ | :----------------------------- | :------- |
| -1 | 系统繁忙，此时请开发者稍候再试 | |
| -501007 | 参数有误，具体原因参考 errmsg | |
| -601027 | 无效的环境 | |
| -601032 | 小程序昵称不能为空 | |
| -601033 | 仅支持非个人主体小程序 | |
| -607004 | 无效的 URL Link | |
### 营销类短信请求数据示例
```js
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.cloudbase.sendSms({
"env": 'online-12345678910',
"content": '发布了新的能力',
"path": '/index.html',
"phoneNumberList": [
"+8612345678910"
],
"smsType": 'Marketing',
"useShortName": true
})
return result
} catch (err) {
return err
}
}
```
### 通知类短信请求数据示例
```js
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.cloudbase.sendSms({
"env": 'online-12345678910',
"phoneNumberList": [
"+8612345678910"
],
"smsType": 'Notification',
"templateId": '923584',
"templateParamList": [
"商品",
"/index.html"
]
})
return result
} catch (err) {
return err
}
}
```
### 返回数据示例
```json
{
"errCode": 0,
"sendStatusList": [
{
"code": "Ok",
"message": "send success",
"serialNo": "8:gFIqWUHzllUyOFRHgeu20201231",
"phoneNumber": "+8612345678910",
"isoCode": ""
}
],
"errMsg": "openapi.cloudbase.sendSms:ok"
}
```