send-sms.md 9.5 KB
Newer Older
雪洛's avatar
雪洛 已提交
1
## 发送短信
雪洛's avatar
雪洛 已提交
2 3 4 5 6

<!--
/// meta
keyword: 短信,sms
-->
Q
qiang 已提交
7

雪洛's avatar
雪洛 已提交
8
> 自`HBuilderX 3.3.0`起,本接口支持传入phoneList参数批量发送短信,其他参数均于发送单条短信相同
雪洛's avatar
雪洛 已提交
9

雪洛's avatar
雪洛 已提交
10 11
> 自`HBuilderX 3.4.0`起云函数需启用uni-cloud-sms之后才可以调用sendSms接口,详细说明见:[云函数使用短信扩展库](#extension)

雪洛's avatar
雪洛 已提交
12
自HBuilderX 2.8.1起,uniCloud内置了短信发送API。给开发者提供更方便、更便宜的短信发送能力。
Q
qiang 已提交
13 14 15

该服务类似小程序的模板消息,在一个固定模板格式的文字里自定义某些字段,而不是所有文字都可以随便写。

D
DCloud_LXH 已提交
16
使用本功能需要在[DCloud开发者中心](https://dev.dcloud.net.cn/#/pages/sms/base)开通并充值,教程参考[短信服务开通指南](https://ask.dcloud.net.cn/article/37534)
Q
qiang 已提交
17 18 19 20 21 22 23 24 25

因涉及费用,为保障安全,本能力应该在云函数中调用,而不是在前端调用。

云函数API名称:`uniCloud.sendSms`

**参数说明**

参数结构体为json格式。

雪洛's avatar
雪洛 已提交
26 27 28 29 30 31
|参数名			|类型		|必填							|说明																																											|
|:-:				|:-:		|:-:							|:-:																																											|
|appid			|String	|是								|DCloud appid,可以在项目manifest.json内看到																							|
|smsKey			|String	|是								|调用短信接口的密钥key,从 dev.dcloud.net.cn/uniSms 后台获取															|
|smsSecret	|String	|是								|调用短信接口的密钥secret,从 dev.dcloud.net.cn/uniSms 后台获取														|
|phone			|String	|和phoneList二选一|发送目标手机号,暂仅支持中国大陆手机号																										|
雪洛's avatar
雪洛 已提交
32
|phoneList	|Array	|和phone二选一		|发送目标手机号,暂仅支持中国大陆手机号,最多50个手机号码,`HBuilderX 3.3.0`起支持				|
雪洛's avatar
雪洛 已提交
33 34
|templateId	|String	|是								|模版Id,短信内容为固定模板,详见下方说明(应用开发阶段,可以使用 DCloud 提供的测试模板)	|
|data				|Object	|是								|模版里的各个变量字段,json格式																														|
Q
qiang 已提交
35 36 37 38


**注意**

39
- 如果使用uni-id发送短信,无需自行开发,请参考[uni-id-pages](uni-id-pages.md)
Q
qiang 已提交
40

雪洛's avatar
雪洛 已提交
41 42 43 44
#### 云函数使用短信扩展库@extension

自HBuilderX 3.4.0起,短信相关功能移至扩展库`uni-cloud-sms`内。在一段时间内无论开发者是否使用扩展库云函数都可以正常使用`uniCloud.sendSms`。预计于2022年3月初发布的HBuilderX内强制使用扩展库,即使用在此时间点后发布的HBuilderX上传云函数时如果没有指定使用`uni-cloud-sms`扩展库的云函数将无法调用uniCloud.sendSms接口。

45
关于扩展库的说明见:[云函数扩展库](cf-functions.md#extension)
雪洛's avatar
雪洛 已提交
46 47 48 49 50 51 52

在云函数的package.json内添加`uni-cloud-sms`的引用即可为云函数启用此扩展,无需做其他调整,完整的package.json示例如下:

```js
{
	"name": "uni-sms",
	"extensions": {
雪洛's avatar
雪洛 已提交
53
		"uni-cloud-sms": {} // 启用uni-cloud-sms扩展,值为空对象即可
雪洛's avatar
雪洛 已提交
54 55 56 57
	}
}
```

Q
qiang 已提交
58 59 60 61 62 63 64 65
#### 参数templateId说明@smstemplate

按照国家法律和运营商要求,每个要发送短信的应用,需要备案其短信模板,并且经过运营商的审核。通过审核的模板,会得到一个templateId。

短信内容规范:
1. 不能包含涉政、黄赌毒、暴力、房产、移民、贷款、代开发票等违法内容
2. 不能包含运营商禁止发送的内容
3. 不能包含侵犯第三方权益的内容(如侵犯他人商标或冒名行为)
66
4. 营销类短信不能违反广告法
Q
qiang 已提交
67 68 69 70
5. 不能利用短信骚扰或诈骗用户

报备模板的方式:

D
DCloud_LXH 已提交
71 72
1. 如果尚未添加签名,请在在开发者中心-[签名配置](https://dev.dcloud.net.cn/#/pages/sms/sign)内添加签名
2. 在开发者中心-[模板配置](https://dev.dcloud.net.cn/#/pages/sms/template)内申请自定义模板
Q
qiang 已提交
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89

- 短信签名:
即短信内容开头的【xxx】,可选内容为App或小程序名称、网站名称、企业名称(可使用简称,但需具备辨识度)、商标名称。如`【DCloud】`,即是DCloud官方发送短信的签名。签名的作用是明确告知用户该短信由什么样的主体发送。签名内容只允许包含中文、英文、数字,签名的长度限制为2-8位。

- 模板内容:
短信模板必然以短信签名作为开头,其内容中允许有一定的变量,以满足灵活性需求。变量用${}包裹。

例如:【hello uni-app】验证码:${code},${expMinute}分钟内有效,请勿泄露并尽快验证。

在实际发送短信时,在短信API中传入该模板ID,然后传入合适的变量,最终发送的短信将变为:
`【hello uni-app】验证码:123465,用于注册,15分钟内有效,请勿泄露并尽快验证。`

- 短信类别:
分为3类,即验证码类短信、通知类短信、营销类短信。验证码类短信,其模板审核简单快速,只能单次发送。

**短信测试模板说明**

雪洛's avatar
雪洛 已提交
90
运营商目前审核比较严格,处于开发阶段的应用可能无法通过运营商的审核。为方便开发者测试短信功能,DCloud 提供了一个测试模板,该模板的templateId为:uni_sms_test,内容为:`【统一应用软件】尊敬的用户,您的验证码是:${code}。5分钟内有效,请尽快验证。请勿泄漏您的验证码。` 
Q
qiang 已提交
91 92 93 94 95 96 97 98 99 100 101

使用该模板的限制:

1. 每日最多给10个手机号发送不超过100条短信;
2. 使用该模板也会正常收取费用,请保证账户有充足余额。


**返回值**

接口调用失败时会直接抛出错误,调用成功时才会有返回值。

D
DCloud_LXH 已提交
102
注意接口调用成功不代表短信发送成功,比如目标手机关机会导致短信发送失败。真实的短信发送成功与否请在[https://dev.dcloud.net.cn/#/pages/sms/base](https://dev.dcloud.net.cn/#/pages/sms/base)后台查看报表。
Q
qiang 已提交
103 104 105 106 107 108 109 110 111 112

|参数名	|类型	|说明			|
|:-:	|:-:	|:-:			|
|errCode|Number|成功返回0,调用失败错误码见下表	|
|errMsg|String|错误描述,调用失败时返回	|

**错误码说明**

|错误码	|错误																	|
|:-:		|:-:																	|
雪洛's avatar
雪洛 已提交
113 114 115 116 117 118 119
|1001		|参数校验未通过,errMsg内会给出详细信息|
|4000		|参数错误															|
|4001		|apiKey 不存在 或 templateId 不正确		|
|4002		|请检查smsKey、smsSecret是否有误			|
|4003		|服务空间或IP地址不在白名单中					|
|5000		|服务错误,请联系DCloud进行排查				|
|5001		|服务器异常,请重试!									|
Q
qiang 已提交
120 121 122 123

**调用示例**

```js
雪洛's avatar
雪洛 已提交
124
// 发送单条短信示例
Q
qiang 已提交
125 126 127 128 129 130 131 132
'use strict';
exports.main = async (event, context) => {
  try {
    const res = await uniCloud.sendSms({
      appid: '__UNI__xxxxxxx',
      smsKey: '****************',
      smsSecret: '****************',
      phone: '188********',
雪洛's avatar
雪洛 已提交
133
      templateId: '100**', // 请替换为自己申请的模板id
Q
qiang 已提交
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
      data: {
        name: 'DCloud',
        code: '123456',
        action: '注册',
        expMinute: '3',
      }
    })
    // 调用成功,请注意这时不代表发送成功
    return res
  } catch(err) {
    // 调用失败
    console.log(err.errCode)
    console.log(err.errMsg)
    return {
      code: err.errCode,
      msg: err.errMsg
    }
  }
};

雪洛's avatar
雪洛 已提交
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
// 批量发送短信示例
'use strict';
exports.main = async (event, context) => {
  try {
    const res = await uniCloud.sendSms({
      appid: '__UNI__xxxxxxx',
      smsKey: '****************',
      smsSecret: '****************',
      phoneList: ['188********', '138********'],
      templateId: '100**', // 请替换为自己申请的模板id
      data: {
        name: 'DCloud',
        code: '123456',
        action: '注册',
        expMinute: '3',
      }
    })
    // 调用成功,请注意这时不代表发送成功
    return res
  } catch(err) {
    // 调用失败
    console.log(err.errCode)
    console.log(err.errMsg)
    return {
      code: err.errCode,
      msg: err.errMsg
    }
  }
};
Q
qiang 已提交
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
```

本示例使用的模板为:
```
【uniID】“${name}”验证码:${code},${expMinute}分钟内有效,请勿泄露并尽快验证。
```

本示例发送的短信,在手机上将显示为:
```
【uniID】“DCloud”验证码:123456,3分钟内有效,请勿泄露并尽快验证。
```

**注意事项**

- data内如果有`测试``test`等字样,系统可能会被判定为测试用途,不会真正把短信下发到对应手机(此行为由运营商控制,可能真实发送,也可能不发送)
D
DCloud_LXH 已提交
198
-[DCloud开发者中心](https://dev.dcloud.net.cn/#/pages/sms/base)绑定`uniCloud`服务空间后,将会只允许绑定的服务空间调用此接口,绑定列表为空时表示不限制服务空间
Q
qiang 已提交
199
- 短信内容不可包含★、 ※、 →、 ●等特殊符号,可能会导致短信乱码
200 201
- 如果是用于用户注册的短信验证码,那么强烈推荐使用uni-id,这是一套云端一体的、完善的用户管理方案,已经内置封装好的短信验证码功能,详见:[uni-id-pages](uni-id-pages.md)
- 发送短信如果需要图形验证码来防止机刷,可以使用[uni-captcha图形验证码](https://ext.dcloud.net.cn/plugin?id=4048)。在[uni-id-pages](uni-id-pages.md)模板中已经集成了uni-id、uni-captcha
Q
qiang 已提交
202 203 204
- Android手机在App端获取短信验证码,参考:[https://ask.dcloud.net.cn/article/676](https://ask.dcloud.net.cn/article/676)
- 短信内容超过70个字符时为长短信,需分条发送,每67个字按一条短信计算
- 如果本地运行提示`不支持的模板ID`,请更新到`2.9.9+`版本的HBuilderX 
雪洛's avatar
雪洛 已提交
205
- 单个手机号码使用同一短信模板发送短信时,1分钟内只能发送1次,超过1次会被运营商判定为短信重发而被拦截导致短信发送失败