qcloud sms java sdk

this Repository is responsible for qlcoud sms sdk

License

License

GroupId

GroupId

com.github.qcloudsms
ArtifactId

ArtifactId

sms
Last Version

Last Version

0.9.2
Release Date

Release Date

Type

Type

jar
Description

Description

qcloud sms java sdk
this Repository is responsible for qlcoud sms sdk
Project URL

Project URL

https://github.com/qcloudsms/qcloudsms_java/
Source Code Management

Source Code Management

https://github.com/qcloudsms/qcloudsms_java/blob/master/LICENSE

Download sms

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.qcloudsms/sms/ -->
<dependency>
    <groupId>com.github.qcloudsms</groupId>
    <artifactId>sms</artifactId>
    <version>0.9.2</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.qcloudsms/sms/
implementation 'com.github.qcloudsms:sms:0.9.2'
// https://jarcasting.com/artifacts/com.github.qcloudsms/sms/
implementation ("com.github.qcloudsms:sms:0.9.2")
'com.github.qcloudsms:sms:jar:0.9.2'
<dependency org="com.github.qcloudsms" name="sms" rev="0.9.2">
  <artifact name="sms" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.qcloudsms', module='sms', version='0.9.2')
)
libraryDependencies += "com.github.qcloudsms" % "sms" % "0.9.2"
[com.github.qcloudsms/sms "0.9.2"]

Dependencies

compile (4)

Group / Artifact Type Version
org.json : json jar 20170516
org.apache.httpcomponents : httpclient jar 4.5.3
org.apache.httpcomponents : httpcore jar 4.4.7
org.apache.httpcomponents : httpmime jar 4.5.3

test (1)

Group / Artifact Type Version
junit : junit jar 3.8.1

Project Modules

There are no modules declared in this project.

腾讯云短信 Java SDK

腾讯短信服务

目前腾讯云短信为客户提供国内短信国内语音海外短信三大服务,腾讯云短信SDK支持以下操作:

国内短信

国内短信支持操作:

  • 指定模板单发短信
  • 指定模板群发短信
  • 拉取短信回执和短信回复状态

Note 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限,量大客户可以使用此功能批量拉取,其他客户不建议使用。

海外短信

海外短信支持操作:

  • 指定模板单发短信
  • 指定模板群发短信
  • 拉取短信回执和短信回复状态

Note 海外短信和国内短信使用同一接口,只需替换相应的国家码与手机号码,每次请求群发接口手机号码需全部为国内或者海外手机号码。

语音通知

语音通知支持操作:

  • 发送语音验证码
  • 发送语音通知
  • 上传语音文件
  • 按语音文件fid发送语音通知
  • 指定模板发送语音通知类

开发

准备

在开始开发云短信应用之前,需要准备如下信息:

  • 获取SDK AppID和AppKey

云短信应用SDK AppIDAppKey可在短信控制台的应用信息里获取,如您尚未添加应用,请到短信控制台中添加应用。

  • 申请签名

一个完整的短信由短信签名和短信正文内容两部分组成,短信签名须申请和审核,签名可在短信控制台的相应服务模块内容配置中进行申请。

  • 申请模板

同样短信或语音正文内容模板须申请和审核,模板可在短信控制台的相应服务模块内容配置中进行申请。

安装

qcloudsms_java可以采用多种方式进行安装,我们提供以下三种方法供用户使用:

maven

要使用qcloudsms_java功能,需要在pom.xml中添加如下依赖:

<dependency>
  <groupId>com.github.qcloudsms</groupId>
  <artifactId>qcloudsms</artifactId>
  <version>1.0.6</version>
</dependency>

sbt

libraryDependencies += "com.github.qcloudsms" % "sms" % "1.0.6"

其他

  • 方法1

源代码直接引入到项目工程中。

Note 由于qcloudsms_java依赖四个依赖项目library: org.json , httpclient, httpcorehttpmine 采用方法1需要将以上四个jar包导入工程。

  • 方法2

JAR包直接引入到您的工程中。

文档

若您对接口存在疑问,可以查阅:

示例

  • 准备必要参数
// 短信应用SDK AppID
int appid = 1400009099; // 1400开头

// 短信应用SDK AppKey
String appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad";

// 需要发送短信的手机号码
String[] phoneNumbers = {"21212313123", "12345678902", "12345678903"};

// 短信模板ID,需要在短信应用中申请
int templateId = 7839; // NOTE: 这里的模板ID`7839`只是一个示例,真实的模板ID需要在短信控制台中申请

// 签名
String smsSign = "腾讯云"; // NOTE: 这里的签名"腾讯云"只是一个示例,真实的签名需要在短信控制台中申请,另外签名参数使用的是`签名内容`,而不是`签名ID`
  • 指定模板ID单发短信
import com.github.qcloudsms.SmsSingleSender;
import com.github.qcloudsms.SmsSingleSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    String[] params = {"5678"};
    SmsSingleSender ssender = new SmsSingleSender(appid, appkey);
    SmsSingleSenderResult result = ssender.sendWithParam("86", phoneNumbers[0],
        templateId, params, smsSign, "", "");  // 签名不能为空串
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。

  • 指定模板ID群发
import com.github.qcloudsms.SmsMultiSender;
import com.github.qcloudsms.SmsMultiSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    String[] params = {"5678"};
    SmsMultiSender msender = new SmsMultiSender(appid, appkey);
    SmsMultiSenderResult result =  msender.sendWithParam("86", phoneNumbers,
        templateId, params, smsSign, "", "");  // 签名不能为空串
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note 群发一次请求最多支持200个号码,如有对号码数量有特殊需求请联系腾讯云短信技术支持(QQ:3012203387)。 Note 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。

  • 发送语音验证码
import com.github.qcloudsms.SmsVoiceVerifyCodeSender;
import com.github.qcloudsms.SmsVoiceVerifyCodeSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    SmsVoiceVerifyCodeSender vvcsender = new SmsVoiceVerifyCodeSender(appid,appkey);
    SmsVoiceVerifyCodeSenderResult result = vvcsender.send("86", phoneNumbers[0],
        "5678", 2, "");
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note 语音验证码发送只需提供验证码数字,例如当msg=“5678”时,您收到的语音通知为“您的语音验证码是5678”,如需自定义内容,可以使用语音通知。

  • 发送语音通知
import com.github.qcloudsms.SmsVoicePromptSender;
import com.github.qcloudsms.SmsVoicePromptSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    SmsVoicePromptSender vpsender = new SmsVoicePromptSender(appid, appkey);
    SmsVoicePromptSenderResult result = vpsender.send("86", phoneNumbers[0],
        2, 2, "5678", "");
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}
  • 拉取短信回执以及回复
import com.github.qcloudsms.SmsStatusPuller;
import com.github.qcloudsms.SmsStatusPullCallbackResult;
import com.github.qcloudsms.SmsStatusPullReplyResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    // Note: 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限
    int maxNum = 10;  // 单次拉取最大量
    SmsStatusPuller spuller = new SmsStatusPuller(appid, appkey);

    // 拉取短信回执
    SmsStatusPullCallbackResult callbackResult = spuller.pullCallback(maxNum);
    System.out.println(callbackResult);

    // 拉取回复
    SmsStatusPullReplyResult replyResult = spuller.pullReply(maxNum);
    System.out.println(replyResult);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限,量大客户可以使用此功能批量拉取,其他客户不建议使用。

  • 拉取单个手机短信状态
import com.github.qcloudsms.SmsMobileStatusPuller;
import com.github.qcloudsms.SmsStatusPullCallbackResult;
import com.github.qcloudsms.SmsStatusPullReplyResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    int beginTime = 1511125600;  // 开始时间(unix timestamp)
    int endTime = 1511841600;    // 结束时间(unix timestamp)
    int maxNum = 10;             // 单次拉取最大量
    SmsMobileStatusPuller mspuller = new SmsMobileStatusPuller(appid, appkey);

    // 拉取短信回执
    SmsStatusPullCallbackResult callbackResult = mspuller.pullCallback("86",
        phoneNumbers[0], beginTime, endTime, maxNum);
    System.out.println(callbackResult);

    // 拉取回复
    SmsStatusPullReplyResult replyResult = mspuller.pullReply("86",
        phoneNumbers[0], beginTime, endTime, maxNum);
    System.out.println(replyResult);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}
  • 发送国际短信

海外短信与国内短信发送类似, 发送海外短信只需替换相应国家码。

  • 上传语音文件
import com.github.qcloudsms.VoiceFileUploader;
import com.github.qcloudsms.VoiceFileUploaderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

try {
    // Note: 语音文件大小上传限制400K字节
    String filePath = "path/to/example.mp3";
    byte[] content = Files.readAllBytes(Paths.get(filePath));
    VoiceFileUploader uploader = new VoiceFileUploader(appid, appkey);
    VoiceFileUploaderResult result = uploader.upload(content, VoiceFileUploader.ContentType.MP3);
    // 上传成功后,result里会带有语音文件的fid
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note '语音文件上传'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通

  • 查询语音文件审核状态
import com.github.qcloudsms.VoiceFileStatus;
import com.github.qcloudsms.VoiceFileStatusResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

try {
    // Note: 这里fid来自`上传语音文件`接口返回的响应,要按语音
    //       文件fid发送语音通知,需要先上传语音文件获取fid
    String fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3";
    VoiceFileStatus vfstatus = new VoiceFileStatus(appid, appkey);
    VoiceFileStatusResult result = vfstatus.get(fid);
    // result里会带有语音文件审核状态status, {0: 待审核, 1: 通过, 2: 拒绝, 3: 语音文件不存在}
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note '查询语音文件审核状态'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通

  • 按语音文件fid发送语音通知
import com.github.qcloudsms.FileVoiceSender;
import com.github.qcloudsms.FileVoiceSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    // Note: 这里fid来自`上传语音文件`接口返回的响应,要按语音
    //       文件fid发送语音通知,需要先上传语音文件获取fid
    String fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3";
    FileVoiceSender fvsender = new FileVoiceSender(appid, appkey);
    FileVoiceSenderResult result = fvsender.send("86", phoneNumbers[0], fid, 2, "");
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

Note 按'语音文件fid发送语音通知'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通

  • 指定模板发送语音通知
import com.github.qcloudsms.TtsVoiceSender;
import com.github.qcloudsms.TtsVoiceSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import org.json.JSONException;

import java.io.IOException;

try {
    int templateId = 45221;
    String[] params = {"5678"};
    TtsVoiceSender tvsender = new TtsVoiceSender(appid, appkey);
    TtsVoiceSenderResult result = tvsender.send("86", phoneNumbers[0],
        templateId, params, 2, "");
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

使用代理

有的环境需要使用代理才能上网,可使用ProxyHTTPClient来发送请求, 示例如下:

import com.github.qcloudsms.SmsSingleSender;
import com.github.qcloudsms.SmsSingleSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import com.github.qcloudsms.httpclient.ProxyHTTPClient;
import org.json.JSONException;

import java.io.IOException;

try {
   // 创建一个代理httpclient
    ProxyHTTPClient httpclient = new ProxyHTTPClient("127.0.0.1", 8080, "http");

    String[] params = {"5678"};
    SmsSingleSender ssender = new SmsSingleSender(appid, appkey, httpclient);
    SmsSingleSenderResult result = ssender.sendWithParam("86", phoneNumbers[0],
        templateId, params, smsSign, "", "");  // 签名参数未提供或者为空时,会使用默认签名发送短信
    System.out.println(result);
} catch (HTTPException e) {
    // HTTP响应码错误
    e.printStackTrace();
} catch (JSONException e) {
    // json解析错误
    e.printStackTrace();
} catch (IOException e) {
    // 网络IO错误
    e.printStackTrace();
}

使用连接池

多个线程可以共用一个连接池发送API请求,多线程并发单发短信示例如下:

import com.github.qcloudsms.SmsSingleSender;
import com.github.qcloudsms.SmsSingleSenderResult;
import com.github.qcloudsms.httpclient.HTTPException;
import com.github.qcloudsms.httpclient.PoolingHTTPClient;
import org.json.JSONException;

import java.io.IOException;


class SmsThread extends Thread {

    private final SmsSingleSender sender;
    private final String nationCode;
    private final String phoneNumber;
    private final String msg;

    public SmsThread(SmsSingleSender sender, String nationCode, String phoneNumber, String msg) {
        this.sender = sender;
        this.nationCode = nationCode;
        this.phoneNumber = phoneNumber;
        this.msg = msg;
    }

    @Override
    public void run() {
        try {
            SmsSingleSenderResult result = sender.send(0, nationCode, phoneNumber, msg, "", "");
            System.out.println(result);
        } catch (HTTPException e) {
            // HTTP响应码错误
            e.printStackTrace();
        } catch (JSONException e) {
            // json解析错误
            e.printStackTrace();
        } catch (IOException e) {
            // 网络IO错误
            e.printStackTrace();
        }
    }
}

public class SmsTest {

    public static void main(String[] args) {

        int appid = 122333333;
        String appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad";
        String[] phoneNumbers = {
            "21212313123", "12345678902", "12345678903",
            "21212313124", "12345678903", "12345678904",
            "21212313125", "12345678904", "12345678905",
            "21212313126", "12345678905", "12345678906",
            "21212313127", "12345678906", "12345678907",
        };

        // 创建一个连接池httpclient, 并设置最大连接量为10
        PoolingHTTPClient httpclient = new PoolingHTTPClient(10);

        // 创建SmsSingleSender时传入连接池http client
        SmsSingleSender ssender = new SmsSingleSender(appid, appkey, httpclient);

        // 创建线程
        SmsThread[] threads = new SmsThread[phoneNumbers.length];
        for (int i = 0; i < phoneNumbers.length; i++) {
            threads[i] = new SmsThread(ssender, "86", phoneNumbers[i], "您验证码是:5678");
        }

        // 运行线程
        for (int i = 0; i < threads.length; i++) {
            threads[i].start();
        }

        // join线程
        for (int i = 0; i < threads.length; i++) {
            threads[i].join();
        }

        // 关闭连接池httpclient
        httpclient.close();
    }
}

使用自定义HTTP client实现

如果需要使用自定义的HTTP client实现,只需实现com.github.qcloudsms.httpclient.HTTPClient接口,并在构造API对象时传入自定义HTTP client即可,一个参考示例如下:

import com.github.qcloudsms.httpclient.HTTPClient;
import com.github.qcloudsms.httpclient.HTTPRequest;
import com.github.qcloudsms.httpclient.HTTPResponse;

import java.io.IOException;
import java.net.URISyntaxException;

// import com.example.httpclient.MyHTTPClient
// import com.exmaple.httpclient.MyHTTPRequest
// import com.example.httpclient.MyHTTPresponse


public class CustomHTTPClient implements HTTPClient {

    public HTTPResponse fetch(HTTPRequest request) throws IOException, URISyntaxException {
        // 1. 创建自定义HTTP request
        // MyHTTPrequest req = MyHTTPRequest.build(request)

        // 2. 创建自定义HTTP cleint
        // MyHTTPClient client = new MyHTTPClient();

        // 3. 使用自定义HTTP client获取HTTP响应
        // MyHTTPResponse response = client.fetch(req);

        // 4. 转换HTTP响应到HTTPResponse
        // HTTPResponse res = transformToHTTPResponse(response);

        // 5. 返回HTTPResponse实例
        // return res;
    }

    public void close() {
        // 如果需要关闭必要资源
    }
}

// 创建自定义HTTP client
CustomHTTPClient httpclient = new CustomHTTPClient();
// 构造API对象时传入自定义HTTP client
SmsSingleSender ssender = new SmsSingleSender(appid, appkey, httpclient);

Note 注意上面的这个示例代码只作参考,无法直接编译和运行,需要作相应修改。

Versions

Version
0.9.2
0.9.1
0.9.0
0.0.1