访问官网
Github
文档twilio-java
文档
Twilio API 的文档可以在这里找到。
Java 库文档可以在这里找到。
版本
twilio-java 使用修改版的语义化版本控制来管理所有变更。查看此文档了解详情。
TLS 1.2 要求
新账户和子账户现在必须使用 TLS 1.2 访问 REST API。"需要升级"错误表示正在使用 TLS 1.0/1.1。
支持的 Java 版本
本库支持以下 Java 实现：
- OpenJDK 8
- OpenJDK 11
- OpenJDK 17
- OracleJDK 8
- OracleJDK 11
- OracleJDK 17
对于 Java 7 支持，请使用 twilio-java 主版本 7.X.X。
安装
twilio-java 使用 Maven。目前可以从公共的 maven 仓库获取 jar 包。
在你的项目中使用以下依赖来通过 Maven 获取：
<dependency>
<groupId>com.twilio.sdk</groupId>
<artifactId>twilio</artifactId>
<version>10.X.X</version>
<scope>compile</scope>
</dependency>
或者使用 Gradle：
implementation "com.twilio.sdk:twilio:10.X.X"
如果你想自己编译，方法如下：
git clone git@github.com:twilio/twilio-java
cd twilio-java
mvn install # 需要 maven，从 https://maven.apache.org/download.html 下载
如果你想构建自己的 .jar 文件，在克隆的目录中执行以下命令：
mvn package
如果遇到本地测试问题，可以使用：
mvn package -Dmaven.test.skip=true
测试你的安装
尝试给自己发送一条短信，像这样：
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;
public class Example {
// 在 console.twilio.com 找到你的 Account Sid 和 Token
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
public static final String AUTH_TOKEN = "your_auth_token";
public static void main(String[] args) {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Message message = Message
.creator(
new PhoneNumber("+15558675309"),
new PhoneNumber("+15017250604"),
"这是在十四秒差距内完成克赛尔航程的飞船？"
)
.create();
System.out.println(message.getSid());
}
}
警告 在本地测试时硬编码你的凭证是可以的，但在提交任何代码或部署到生产环境之前，你应该使用环境变量来保密。查看 如何设置环境变量 获取更多信息。
使用方法
初始化客户端
import com.twilio.Twilio;
import com.twilio.exception.AuthenticationException;
public class Example {
private static final String ACCOUNT_SID =
"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
private static final String AUTH_TOKEN = "your_auth_token";
public static void main(String[] args) throws AuthenticationException {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
}
}
当端点不使用基本认证时初始化客户端
上面的例子展示了当端点使用基本认证时如何初始化客户端。当端点不需要任何认证时，请使用 TwilioNoAuth 客户端。 有些端点，如 Organization 域，使用承载令牌认证。在这种情况下需要使用自定义客户端，并用生成访问令牌所需的值初始化它们。
要跳过初始化步骤，你也可以使用自定义令牌管理器实现。令牌管理器类应实现 Token 接口，并调用你选择的令牌生成端点。 详细示例在这里
环境变量
twilio-java 支持存储在以下环境变量中的凭证、区域和边缘值：
TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKENTWILIO_REGIONTWILIO_EDGE
如果使用这些变量，可以跳过上述客户端初始化。
拨打电话
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;
import com.twilio.type.PhoneNumber;
import java.net.URI;
import java.net.URISyntaxException;
public class Example {
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
public static final String AUTH_TOKEN = "your_auth_token";
public static void main(String[] args) throws URISyntaxException {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Call call = Call
.creator(
new PhoneNumber("+14155551212"),
new PhoneNumber("+15017250604"),
new URI("http://demo.twilio.com/docs/voice.xml")
)
.create();
System.out.println(call.getSid());
}
}
获取现有通话
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;
public class Example {
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
public static final String AUTH_TOKEN = "your_auth_token";
public static void main(String[] args) {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
Call call = Call.fetcher("CA42ed11f93dc08b952027ffbc406d0868").fetch();
System.out.println(call.getTo());
}
}
遍历记录
库会自动为你处理分页。使用 read 方法时，你可以指定想要接收的记录数量（limit）和每页获取的最大大小（pageSize）。然后库会为你处理这个任务，在你遍历记录时自动获取新的页面。
更多信息，请查看 自动生成的库文档。
使用 read 方法
import com.twilio.Twilio;
import com.twilio.base.ResourceSet;
import com.twilio.rest.api.v2010.account.Call;
public class Example {
public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
public static final String AUTH_TOKEN = "你的身份验证令牌";
public static void main(String[] args) {
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
ResourceSet<Call> calls = Call.reader().read();
for (Call call : calls) {
System.out.println(call.getDirection());
}
}
指定区域和/或边缘
要利用Twilio的全球基础设施，为客户端指定目标区域和/或边缘：
Twilio.init(accountSid, authToken);
Twilio.setRegion("au1");
Twilio.setEdge("sydney");
这将导致hostname从api.twilio.com转变为api.sydney.au1.twilio.com。
启用调试日志
该库使用SLF4J进行日志记录。有关日志配置的信息，请参阅SFL4J文档。
例如，如果你使用log4j：
-
确保在你的
pom.xml文件中有log4j-slf4j-impl、log4j-core和log4j-api -
在你的配置中定义Twilio HTTP客户端的日志级别。例如，在
src/main/resources/log4j2.xml中：<?xml version="1.0" encoding="UTF-8"?> <Configuration status="WARN"> <Appenders> <Console name="Console" target="SYSTEM_OUT"> <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level - %msg%n"/> </Console> </Appenders> <Loggers> <!--你的Twilio日志配置放在这里--> <Logger name="com.twilio.http" level="debug" additivity="false"> <AppenderRef ref="Console"/> </Logger> <Root level="info"> <AppenderRef ref="Console"/> </Root> </Loggers> </Configuration>
处理异常
import com.twilio.exception.ApiException;
try {
Message message = Message.creator(
new PhoneNumber("+15558881234"), // 接收号码
new PhoneNumber("+15559994321"), // 发送号码
"你好世界！" // 短信内容
).create();
System.out.println(message.getSid());
} catch (final ApiException e) {
System.err.println(e);
}
使用PKCV认证的客户端
更多文档请参见：https://twilio.com/docs/iam/pkcv/quickstart
ValidationClient httpClient = new ValidationClient(ACCOUNT_SID, key.getSid(), signingKey.getSid(), pair.getPrivate());
TwilioRestClient client = new TwilioRestClient.Builder(signingKey.getSid(), signingKey.getSecret())
.accountSid(ACCOUNT_SID)
.httpClient(httpClient)
.build();
生成TwiML
要控制电话呼叫，你的应用程序需要输出TwiML。
twilio-java中的TwiML现在使用构建器模式！
TwiML twiml = new VoiceResponse.Builder()
.say(new Say.Builder("你好世界！").build())
.play(new Play.Builder("https://api.twilio.com/cowbell.mp3").loop(5).build())
.build();
这将输出如下XML：
<Response>
<Say>你好世界！</Say>
<Play loop="5">https://api.twilio.com/cowbell.mp3</Play>
</Response>
使用自定义HTTP客户端
要在此帮助库中使用自定义HTTP客户端，请参阅如何执行此操作的高级示例。
Docker镜像
本仓库中的Dockerfile及其相应的twilio/twilio-java Docker镜像目前仅供Twilio用于测试目的。
获取帮助
如果你在安装或使用库时需要帮助，请先查看Twilio支持帮助中心，如果找不到问题的答案，请提交支持票据。
如果你发现了库中的bug或想要添加新功能，请随时在此仓库中提出问题或拉取请求！
