通过API发送短信

您可以根据业务需要和自身情况选择合适的方式调用短信服务API：

• 阿里云OpenAPI 开发者门户

  适用于习惯交互式操作界面的场景，或者初次使用阿里云产品的开发者用户。您可以在OpenAPI开发者门户中调试和获取SDK请求示例。

• 短信服务SDK

  支持多种编程语言，包括Java、Go、C#、PHP、Node.js/TypeScript、Python。使用SDK集成短信服务，可提升您使用短信服务的开发效率。

• 自定义封装API调用（不推荐）

  阿里云SDK已经封装了签名、超时、重试等机制，我们建议您使用SDK进行集成，降低开发成本。如果您需要自行封装请求来进行API调用，请参见SendSms和签名示例。

本文将以SDK的方式引导您使用短信服务。您可以先通过OpenAPI 开发者门户，查看、体验短信服务API后，根据本文指引开始集成短信服务API。整体流程：

准备工作

环境配置

本文以Java语言为例，进行后续操作。更多语言及其SDK安装方式，请参见安装与使用教程。

1. 检查Java环境：您的Java版本需高于Java 8。Java环境配置的方法，请参见在Windows搭建Java开发环境。

2. 安装SDK：请通过配置Maven依赖，完成短信服务SDK的安装。

   请在您的Maven项目的pom.xml文件中，在<dependencies>标签内添加以下信息并将 the-latest-version 替换为最新版本号。保存后请重新加载Maven依赖。

   <dependency>
     <groupId>com.aliyun</groupId>
     <artifactId>dysmsapi20170525</artifactId>
     <!-- 请将 'the-latest-version' 替换为最新版本号：https://mvnrepository.com/artifact/com.aliyun/dysmsapi20170525 -->
     <version>the-latest-version</version>
   </dependency>

3. 配置环境变量：为避免在代码中显式地编码访问密钥（AccessKey）而造成泄露，建议您把AccessKey配置到环境变量，通过环境变量进行读取。配置后请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

4. 配置代理（可选）：如果您需要通过代理服务器访问，可通过SDK进行配置，请参见代理配置。

API基本信息

短信服务所提供的API基本信息参见如下：

建议您在调用API接口前，阅读接口参数规范与使用说明。在线调试 | API文档

API调用流程

1. 申请短信资质：使用SubmitSmsQualification接口，资质信息需遵守资质材料说明。资质审核通过后才可以申请短信签名。

   • 受短信签名实名制报备要求影响，当前资质审核工单量增长快速，审核时间可能会延长，请耐心等待，预计2个工作日内完成。

   • 您可以选择使用API接口查看审核状态：使用QuerySmsQualificationRecord接口查询资质列表，并使用出参WorkOrderId调用QuerySingleSmsQualification接口查询指定资质的审核状态。

2. 申请短信签名：使用CreateSmsSign接口，签名信息需遵守短信签名规范。签名审核通过后才可以申请模板。

   • 如果您需要申请的签名用途为他用，则需在申请签名时上传委托授权书，建议您在申请短信签名前根据授权书填写规范调用CreateSmsAuthorizationLetter接口创建授权委托书。

   • 审核预计2个小时内完成（审核工作时间：周一至周日9:00~21:00，法定节假日顺延）。

   • 您可以选择使用接口或回执消息查看审核状态：

     API接口	使用GetSmsSign接口查询签名状态，或使用QuerySmsSignList接口查询签名列表，根据出参AuditStatus判断。
     回执消息	通过配置回执并开发对接，具体操作请参见配置回执消息，仅支持HTTP批量推送模式。 SignSmsReport（签名审核状态）

   • 签名实名制报备：新增签名将在审核通过后自动提交报备，存量签名请在签名管理页面检查后手动提交报备。未报备的签名会被运营商拦截发送。操作说明

     重要

     在未完全完成报备之前，您的短信可能会发送失败，返回错误码如下：

     • PORT_NOT_REGISTERED：当前使用端口号尚未完成企业实名制报备流程。

     运营商实名报备流程平均需要5-7个工作日，基于近期观测，部分运营商实名报备流程需要7-10个工作日，但运营商未对此时效进行承诺，实际可能需要更长时间。请您合理规划业务计划，并在正式使用前提前申请相关资质和签名，预留时间进行发送测试，以确保在正式使用前有充足的时间完成实名报备。

     若报备失败请按照控制台报备结果详情指引进行操作，详情请参见签名实名制报备。

3. 申请短信模板：使用CreateSmsTemplate接口，模板内容需遵守短信模板规范。模板审核通过后才可以发送短信。

   • 申请短信模板时关联的签名仅供审核使用，与实际发送短信时使用的签名无关。

   • 国内短信模板与国际/港澳台短信模板不通用。

   • 审核预计2个小时内完成（审核工作时间：周一至周日9:00~21:00，法定节假日顺延）。

   • 您可以选择使用接口或回执消息查看审核状态：

     API接口	使用GetSmsTemplate接口查询模板状态，或使用QuerySmsTemplateList接口查询模板列表，根据出参AuditStatus判断。
     回执消息	通过配置回执并开发对接，具体操作请参见配置回执消息，仅支持HTTP批量推送模式。 TemplateSmsReport（模板审核状态）

4. 发送短信：使用SendSms接口，或使用SendBatchSms接口批量发送短信。

   • 建议您等待签名报备状态变更为“已报备待验证”后再批量发送，您可使用三大运营商的手机号、少量多次使用该签名发送验证码、通知短信进行测试。在系统探测期内，建议根据自身情况尽可能多测试发送，若实际测试发送的短信成功率符合预期，则报备状态将变更为“报备成功”。若报备状态不为“报备成功”，请根据报备验证环节内相关指引进行操作。

   • 发送短信前确保您账户余额充足。更多详情，请参见计费概述。

5. 查看短信发送详情：您可使用接口或回执消息查看短信发送详情。

   API接口	使用QuerySendDetails接口查询短信发送状态。
   回执消息	通过配置回执并开发对接，具体操作请参见配置回执消息。支持以下两种方式： SmsReport（状态报告接收）：轻量消息队列消费模式 | HTTP批量推送模式

6. 获取用户回复内容：您发送短信后，用户回复的短信内容即为上行短信，需配置回执消息获取。

   回执消息	通过配置回执并开发对接，具体操作请参见配置回执消息。支持以下两种方式： SmsUp（上行消息接收）：轻量消息队列消费模式 | HTTP批量推送模式

更多接口信息，请参见API概览。

代码示例

使用SDK发送短信（调用SendSms接口）的代码示例如下，请根据注释完成参数填写。

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
import static com.aliyun.teautil.Common.toJSONString;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 配置 AccessKey ID，请确保代码运行环境设置了环境变量。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 配置 AccessKey Secret，请确保代码运行环境设置了环境变量。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                // System.getenv()方法表示获取系统环境变量，请配置环境变量后，在此填入环境变量名称，不要直接填入AccessKey信息。
        
        // 配置 Endpoint
        config.endpoint = "dysmsapi.aliyuncs.com";

        return new Client(config);
    }

    public static void main(String[] args) throws Exception {
        // 初始化请求客户端
        Client client = Sample.createClient();

        // 构造请求对象，请填入请求参数值
        SendSmsRequest sendSmsRequest = new SendSmsRequest()
                .setPhoneNumbers("1390000****")
                .setSignName("阿里云")
                .setTemplateCode("SMS_15305****")
                .setTemplateParam("{\"name\":\"张三\",\"number\":\"1390000****\"}");

        // 获取响应对象
        SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);

        // 响应包含服务端响应的 body 和 headers
        System.out.println(toJSONString(sendSmsResponse));
    }
}

您可以访问 OpenAPI 门户，查看各语言 SDK 请求完整示例。如果您需要自行封装请求来进行API调用，请参见SendSms和签名示例。

常见问题

• API&SDK常见问题

• 短信发送常见问题

视频教程