## 短信API服务 ![](https://img.kancloud.cn/3f/1f/3f1f30dde33bba9a259a7e418a1f10df_160x133.png) > 支持三网合一短信通道,仅可用于验证码短信 · 短信通知 >[danger] 禁止用于金融类、区块链、房产、医疗、中奖以及其它非法内容发送。 为了规范短信业务,地产、留学、招聘、交友、游戏等行业仅支持发送验证码短信。 ## 功能介绍 1. 支持国内快速发送验证码、短信通知,服务范围覆盖全国。 2. 支持三网合一专属通道,与工信部携号转网平台实时互联。 3. 电信级运营保障,到达率高达99%,支持大容量高并发。 4. 超低资费,多种阶梯套餐任意选择 ### 内置安全策略 1. 限制每天单个号码的发送次数,默认为10条,可根据业务自行调整。 2. 限制单个号码一分钟内不超过1条,一小时内不超过5条,可以根据业务自行调整。 ### 短信防轰炸建议 1. 有效的图片验证(图形、滑动拼图验证码、减少被轰炸机识别的可能性)及不低于60S倒计时。 2. 设置IP白名单。(可绑定多个IP地址) 3. 设置短信预警提醒功能。 4. APP端建议采用秘钥签名校验请求合法性。 5. 由于短信轰炸机可以模拟IP且取用随机号码,所以在进行整改时不要只限制IP和单号码发送次数,因为这样无法限制大量号码异常下发。 ## 签名及模板审核要求(支持接口申请) 短信发送审核要求大致包括: > 1、短信模板需明确表述短信发送的实际内容。 > 2、所有模板均禁止发送金融相关的所有内容。 > 3、不支持发送未经许可的发送行为,主要指邀请注册、邀请成为会员的商业性信息 。 > 4、禁止发送涉及:色情、赌博、毒品、党政、法律维权、众筹、慈善募捐、宗教、迷信、股票、留学移民、面试招聘、博彩、贷款、催款还款、信用卡提额、投资理财、中奖、抽奖、一元夺宝、一元秒杀、一元云购、二类电商、A货、整形、烟酒、交友、暴力、恐吓、皮草、返现返利、代开发票、运营商禁止发送的信息、代理注册、代办证件、加群、加QQ或者加微信、贩卖个人信息、运营商策反、流量营销、违反广告法用语、殡葬、刷单、空包网、邀请好评、转店类业务等信息的短信。地产、留学、招聘、交友、游戏等行业仅支持发送验证码短信。 > 5、禁止在关键字或关键信息中出现错别字、变体字、异体字、各类干扰符号等;禁止出现各类非正常混合字以及非常用的表达法。 > 6、不支持内容中含有直接或间接访问应用内测分发平台的行为。 > 7、通知短信中不得包含联系客服或添加微信的行为。 ## 接口费用( [点击购买](https://market.topthink.com/product/395)) > 最低 0.035元/次 ### 计费规则 >[danger] 短信最终是否成功的确认是运营商异步确认的,所以需要在我的服务->短信服务->发信记录里面确认,最终的计费也是以发信记录里面的成功次数来计费,如果短信内容长度超过70个字符可能会造成多次计费,请悉知。 短信字数=短信模版内容字数 + 签名字数 短信字数≤70个字数,按照70个字数一条短信计算 短信字数>70个字数,即为长短信,按照67个字数记为一条短信计算。客户感知还是一条短信。 >[danger] 在统计短信字数时,小数点、字母、汉字以及其他符号、空格均按照一个字符位进行统计。最终按照实际发送成功的短信条数计费。 ## 接口调用([调用须知](https://docs.topthink.com/think-api/1835086)) ### 调用步骤:申请签名-> 申请模板(如果使用系统自带模板可跳过)->调用接口 短信发送之前,首先要完成模板和签名的申请,登录市场后点击右上角用户头像选择“我的服务->短信服务”,在签名管理和模板管理里面申请即可,审核通过后才可以进行短信发送调用。一旦检查发现有任何违规内容发送的话,我们将会对签名和模板进行冻结,已购买的套餐资费不退,并且保留追究相关责任的权利。开发对接测试的时候,也不要使用带有测试字样的内容(如果产品尚未上线,可以先申请一个公司简称用于测试对接,后续再申请产品相关签名)。 ### 签名提交注意事项 >[danger] 签名的规范建议使用公司名(通常是简写)、品牌名(或商标)、网站名称、产品名、公众号名称等,尽量避免使用生僻字,会比较容易通过审核。签名中不要包含任何特殊字符,包括【】、[],不要使用带有测试字样的签名或过于宽泛的名称,申请签名的时候务必注明你的使用场景并提供网址,便于快速完成审核。为了企业安全考虑,签名使用公司名或简称的话,请先完成企业认证。 ### 模板提交注意事项 >[danger] 模板内容里面如果需要使用变量,变量定义格式为 `${变量名}`,其中变量名规范为英文大小写字母及下划线(请避免包含数字和特殊符号,并且不能使用系统内置变量,包括`id`、`email`、`mobile`、`nick`、`site`)。并且模板内容里面不要包含【】符号,否则会误判为签名,导致发送较慢或者拦截,如非必要,避免在模板中使用特殊字符,单个模板中不得超过8个变量,并且单个变量不能超过50个字符(如果你要在变量中传URL地址 尽可能使用短网址)。 ## 接口1:发送短信 ``` GET https://api.topthink.com/sms/send ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | | signId | Number | 是 | 签名id,在我的服务->短信服务->签名管理里面查看 | | templateId | Number | 是 | 模板id,在我的服务->短信服务->模板管理里面查看 | | phone| String | 是 | 要发送的国内手机号码 | | params| Json | 否 | 模板变量 使用Json对象格式 | ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |id|String|短信发送任务id| ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsSend() ->withSignId('78') ->withTemplateId('234') ->withPhone('15687902345') ->withParams('{"code": "7865"}') ->request(); dump($result); ``` >[danger] 注意:如果你的模板没有变量,请不要传任何变量参数,否则会提示变量错误。 返回结果示例: ``` { "code": 0, "message": "发送成功", "data":{ "id": "6055df2f45e10" } } ``` ## 接口2:查询短信发送状态 短信最终是否成功的确认是运营商异步确认的,你可以在**我的服务->短信服务->发信设置**里面设置数据推送的回调地址,用于支持短信发送回执的推送。 回调请求类型为`POST`, 请求的头部包含 ~~~ X-ThinkPHP-Event: sms ~~~ 请求的数据为`json`格式的 ~~~ { 'action' : 'report', 'sms': { 'id':'6055075678d9' // 短信任务ID 'phone' : '13509898765', // 发送手机号码 'content' : '短信内容', // 短信内容 'sendDate' : '2021-04-20 04:19:33', // 发送时间 'receiveDate': '2021-04-20 04:21:30', // 接收时间 'status': 1,// 1 成功 -1 失败 0 发送中 'message':'', // 错误提示 } } ~~~ 数据推送只会推送一次,如果没有收到的话,也可以通过以下接口主动查询短信的发送状态 ``` GET https://api.topthink.com/sms/query_status ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | |id|String|是|短信发送任务id| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |id|String|短信发送任务id| | phone| Number | 发送手机号码 | | content| string| 短信内容 | | sendDate| String | 发送时间 | | reveiveDate| String| 接收时间 | | status| int | 发送状态 0 发送中 1 成功 -1 失败 | | message| String| 错误信息 | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsQueryStatus() ->withId('6055075678d9') ->request(); dump($result); ``` ## 接口3:申请签名 申请短信签名 ### 签名提交注意事项 >[danger] 签名的规范建议使用公司名(通常是简写)、品牌名(或商标)、网站名称、产品名、公众号名称等,尽量避免使用生僻字,会比较容易通过审核。签名中不要包含任何特殊字符,包括【】、\[\],不要使用带有测试字样的签名,申请签名的时候务必注明你的使用场景,便于快速完成审核。为了企业安全考虑,签名使用公司名或简称的话,请先完成企业认证。 ### 接口地址 ``` GET https://api.topthink.com/sms/add_sign ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | |name|String|是|短信签名| |remark|String|是|签名描述| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |name|String|短信签名| | remark|string| 签名描述 | | user_id| int| 用户id | | create_time| String | 创建时间 | | update_time| String| 更新时间 | | id | int | 签名ID | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsAddSign() ->withName('顶想云') ->withRemark('用于topthink.com顶想云短信通知和验证码发送') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "添加成功", "data":{ "name": "顶想云", "remark": "用于topthink.com顶想云服务短信通知和验证码", "user_id": 1, "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:28:04", "id": "471" } } ``` ## 接口4:查询签名审核状态 短信签名审核是异步确认的,你可以在**我的服务->短信服务->发信设置**里面设置数据推送的回调地址,用于支持短信签名审核回执的推送。 回调请求类型为`POST`, 请求的头部包含 ~~~ X-ThinkPHP-Event: sms ~~~ 请求的数据为`json`格式的 ~~~ { 'action' : 'sign', 'sign': { "id": "471", "user_id": "1", "name": "顶想云", "remark": "用于顶想云服务短信通知和验证码", "status": 2, // 签名状态 0 审核中 1 通过 2 驳回 "error": "请提供网址或公众号", // 驳回原因 "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:28:04", } } ~~~ 数据推送只会推送一次(无论是通过审核还是驳回),如果没有收到的话,也可以通过以下接口主动查询短信签名的审核状态 ``` GET https://api.topthink.com/sms/query_sign ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | |id|String|是|短信签名ID| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| | id | int | 签名ID | | user_id| int| 用户id | |name|String|短信签名| | remark|string| 签名描述 | |status|int|签名状态 0 审核中 1 通过审核 2 驳回| | error|string| 签名驳回原因 | | create_time| String | 创建时间 | | update_time| String| 更新时间 | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsQuerySign() ->withId('471') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "查询成功", "data":{ "id": "471", "user_id": "1", "name": "顶想云", "remark": "用于顶想云服务短信通知和验证码", "status": 2, "error": "请提供网址或公众号", "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:28:04", } } ``` ## 接口5:修改签名 如果签名被驳回了 可以通过该接口修改后重新提交申请。(已经通过审核的签名不允许修改 只能删除然后重新申请新的签名) ``` GET https://api.topthink.com/sms/modify_sign ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | | id | int | 是|签名ID | |name|String|是|短信签名| |remark|String|是|签名描述| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |name|String|短信签名| | remark|string| 签名描述 | | user_id| int| 用户id | | create_time| String | 创建时间 | | update_time| String| 更新时间 | | id | int | 签名ID | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsModifySign() ->withId('471') ->withName('顶想云') ->withRemark('用于topthink.com顶想云短信通知和验证码发送') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "修改成功", "data":{ "name": "顶想云", "remark": "用于topthink.com顶想云服务短信通知和验证码", "user_id": 1, "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:38:04", "id": "471" } } ``` 修改签名接口提交后,依然可以通过回调或查询签名状态的接口来查询审核结果。 ## 接口6:删除签名 可以通过该接口删除已经申请的签名(包括驳回和通过审核的) ``` GET https://api.topthink.com/sms/delete_sign ``` ### 请求参数 | 参数名称 | 类型 | 必须|描述 | | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | | id | int | 是|签名ID | ### 返回`data`参数 无 ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsDeleteSign() ->withId('471') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "删除成功", } ``` ## 接口7:申请模板 申请短信通知模板 ### 模板提交注意事项 >[danger] 模板内容里面如果需要使用变量,变量定义格式为`${变量名}`,其中变量名规范为英文大小写字母及下划线(请避免包含数字和特殊符号,并且不能使用系统内置变量,包括`id`、`email`、`mobile`、`nick`、`site`)。并且模板内容里面不要包含【】符号,否则会误判为签名,导致发送较慢或者拦截,如非必要,避免在模板中使用特殊字符,单个模板中不得超过8个变量,并且单个变量不能超过50个字符(如果你要在变量中传URL地址 尽可能使用短网址)。 ### 接口地址 ``` GET https://api.topthink.com/sms/add_template ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | |name|String|是|短信模板名称| |content|String|是|短信模板内容| |remark|String|是|模板描述| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |name|String|短信模板名称| |name|String|模板内容| | remark|string| 模板描述 | | user_id| int| 用户id | | create_time| String | 创建时间 | | update_time| String| 更新时间 | | id | int | 模板ID | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsAddTemplate() ->withName('订单通知') ->withContent('你有一个新的${name}订单,请及时处理!') ->withRemark('用于顶想云订单通知') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "添加成功", "data":{ "name": "订单通知", "content": "你有一个新的${name}订单,请及时处理!", "remark": "用于顶想云订单通知", "user_id": 1, "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:28:04", "id": "278" } } ``` ## 接口8:查询模板审核状态 短信模板审核是异步确认的,你可以在**我的服务->短信服务->发信设置**里面设置数据推送的回调地址,用于支持短信模板申请回执的推送。 回调请求类型为`POST`, 请求的头部包含 ~~~ X-ThinkPHP-Event: sms ~~~ 请求的数据为`json`格式的 ~~~ { 'action' : 'template', 'sign': { "id": "278", "user_id": "1", "name": "订单通知", "content": "你有一个新的${name}订单,请及时处理!", "remark": "用于顶想云订单通知", "status": 1, // 审核状态 0 审核中 1 通过 2 驳回 "error": null, // 驳回原因 "create_time": "2022-02-13 22:32:04", "update_time": "2022-02-13 22:32:04", } } ~~~ 数据推送只会推送一次(无论是通过审核还是驳回),如果没有收到的话,也可以通过以下接口主动查询短信模板的审核状态 ``` GET https://api.topthink.com/sms/query_template ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | |id|String|是|短信模板ID| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| | id | int | 模板ID | | user_id| int| 用户id | |name|String|模板名称| |content|String|模板内容| | remark|string| 模板描述 | |status|int|审核状态 0 审核中 1 通过审核 2 驳回| | error|string| 驳回原因 | | create_time| String | 创建时间 | | update_time| String| 更新时间 | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsQueryTemplate() ->withId('278') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "查询成功", "data":{ "id": "278", "user_id": "1", "name": "订单通知", "content": "你有一个新的${name}订单,请及时处理!", "remark": "用于顶想云订单通知", "status": 1, "error": null, "create_time": "2022-02-13 22:48:04", "update_time": "2022-02-13 22:48:04", } } ``` ## 接口9:修改模板 如果模板被驳回了 可以通过该接口修改后重新提交申请。(已经通过审核的模板不允许修改 只能删除然后重新申请新的模板) ``` GET https://api.topthink.com/sms/modify_template ``` ### 请求参数 | 参数名称 | 类型 | 必须 | 描述 | | --- | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | | id | int | 是|模板ID | |name|String|是|短信模板名| |remark|String|是|模板描述| ### 返回`data`参数 | 名称 | 类型 | 说明 | |---|---|---| |name|String|短信模板名| | content|string| 模板内容 | | remark|string| 模板描述 | | user_id| int| 用户id | | create_time| String | 创建时间 | | update_time| String| 更新时间 | | id | int | 签名ID | ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsModifyTemplate() ->withId('278') ->withName('订单通知1') ->withContent('你有一个新的${name}订单,请及时处理!') ->withRemark('用于顶想云订单通知') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "修改成功", "data":{ "name": "订单通知1", "content": "你有一个新的${name}订单,请及时处理!", "remark": "用于顶想云订单通知", "user_id": 1, "create_time": "2022-02-13 22:28:04", "update_time": "2022-02-13 22:38:04", "id": "278" } } ``` 修改模板接口提交后,依然可以通过回调或查询模板审核状态的接口来查询审核结果。 ## 接口10:删除模板 可以通过该接口删除已经申请的模板(包括驳回和通过审核的) ``` GET https://api.topthink.com/sms/delete_template ``` ### 请求参数 | 参数名称 | 类型 | 必须| 描述 | | --- | --- | --- | --- | | appCode| string| 是 | 用户授权码,参考[API调用](https://docs.topthink.com/think-api/1835086) | | id | int | 是|签名ID | ### 返回`data`参数 无 ## SDK调用 ``` $client = new Client("YourAppCode"); $result = $client->smsDeleteTemplate() ->withId('278') ->request(); dump($result); ``` 返回结果示例: ``` { "code": 0, "message": "删除成功", } ```