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_SID
• TWILIO_AUTH_TOKEN
• TWILIO_REGION
• TWILIO_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或想要添加新功能，请随时在此仓库中提出问题或拉取请求！