telnyx-10dlc-java

Telnyx 10DLC Java 是 Telnyx 官方 Java SDK 中面向美国 A2P 10DLC（10 Digit Long Code）品牌与活动注册合规的模块。它允许 Java 开发者通过 SDK 调用 Telnyx API，完成品牌注册、活动提交、消息配置文件分配以及电话号码与活动的绑定，并处理相关的 Webhook 事件。

用途

该模块主要用于满足美国 A2P 短信的合规要求。10DLC 注册流程是顺序性的：首先创建品牌（Brand），然后提交活动（Campaign），最后将消息基础设施（如消息配置文件）与活动关联。注册调用本身并不足够，必须成功完成分配步骤后，消息才能使用该活动。开发者应将注册状态字段视为控制流的一部分，在返回的状态字段确认之前，不应假设活动已可发送。

主要能力

创建品牌：通过 client.messaging10dlc().brand().create() 提交品牌注册，需要提供实体类型、显示名称、国家、邮箱、行业垂直等参数。
提交活动：通过 client.messaging10dlc().campaignBuilder().submit() 提交活动，需要品牌 ID、描述、用例等参数。
分配消息配置文件：通过 client.messaging10dlc().phoneNumberAssignmentByProfile().assign() 将消息配置文件与活动关联。
Webhook 验证：Telnyx 使用 Ed25519 签名 Webhook，请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境应始终验证签名。
辅助操作：包括获取品牌、按用例资格查询、创建电话号码活动、获取活动、列出品牌、获取品牌反馈等。
其他操作：获取品牌短信 OTP 状态、更新品牌、删除品牌、重发品牌 2FA 邮件、列出外部审核、订购品牌外部审核、导入外部审核记录、重新审核品牌、按品牌 ID 获取品牌短信 OTP 状态、触发品牌短信 OTP 等。

使用方式

安装

Maven：

<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.89.0</version>
</dependency>

Gradle：

implementation("com.telnyx.sdk:telnyx:6.89.0")

初始化

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

错误处理

所有 API 调用可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率限制（使用指数退避重试）。

分页

列表方法返回一页。使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }。手动控制可使用 .hasNextPage() 和 .nextPage()。

核心任务示例

创建品牌：

import com.telnyx.sdk.models.messaging10dlc.brand.BrandCreateParams;
import com.telnyx.sdk.models.messaging10dlc.brand.EntityType;
import com.telnyx.sdk.models.messaging10dlc.brand.TelnyxBrand;
import com.telnyx.sdk.models.messaging10dlc.brand.Vertical;

BrandCreateParams params = BrandCreateParams.builder()
    .country("US")
    .displayName("ABC Mobile")
    .email("support@example.com")
    .entityType(EntityType.PRIVATE_PROFIT)
    .vertical(Vertical.TECHNOLOGY)
    .build();
TelnyxBrand telnyxBrand = client.messaging10dlc().brand().create(params);

主要响应字段：telnyxBrand.brandId、telnyxBrand.identityStatus、telnyxBrand.status、telnyxBrand.displayName、telnyxBrand.state、telnyxBrand.altBusinessId。

提交活动：

import com.telnyx.sdk.models.messaging10dlc.campaign.TelnyxCampaignCsp;
import com.telnyx.sdk.models.messaging10dlc.campaignbuilder.CampaignBuilderSubmitParams;

CampaignBuilderSubmitParams params = CampaignBuilderSubmitParams.builder()
    .brandId("BXXXXXX")
    .description("Two-factor authentication messages")
    .usecase("2FA")
    .sample1("Your verification code is {{code}}")
    .build();
TelnyxCampaignCsp telnyxCampaignCsp = client.messaging10dlc().campaignBuilder().submit(params);

主要响应字段：telnyxCampaignCsp.campaignId、telnyxCampaignCsp.brandId、telnyxCampaignCsp.campaignStatus、telnyxCampaignCsp.submissionStatus、telnyxCampaignCsp.failureReasons、telnyxCampaignCsp.status。

分配消息配置文件：

import com.telnyx.sdk.models.messaging10dlc.phonenumberassignmentbyprofile.PhoneNumberAssignmentByProfileAssignParams;
import com.telnyx.sdk.models.messaging10dlc.phonenumberassignmentbyprofile.PhoneNumberAssignmentByProfileAssignResponse;

PhoneNumberAssignmentByProfileAssignParams params = PhoneNumberAssignmentByProfileAssignParams.builder()
    .messagingProfileId("4001767e-ce0f-4cae-9d5f-0d5e636e7809")
    .campaignId("CXXX001")
    .build();
PhoneNumberAssignmentByProfileAssignResponse response = client.messaging10dlc().phoneNumberAssignmentByProfile().assign(params);

主要响应字段：response.messagingProfileId、response.campaignId、response.taskId、response.tcrCampaignId。

Webhook 验证示例：

import com.telnyx.sdk.core.UnwrapWebhookParams;
import com.telnyx.sdk.core.http.Headers;

@PostMapping("/webhooks")
public ResponseEntity<String> handleWebhook(
    @RequestBody String payload,
    HttpServletRequest request) {
  try {
    Headers headers = Headers.builder()
        .put("telnyx-signature-ed25519", request.getHeader("telnyx-signature-ed25519"))
        .put("telnyx-timestamp", request.getHeader("telnyx-timestamp"))
        .build();
    var event = client.webhooks().unwrap(
        UnwrapWebhookParams.builder()
            .body(payload)
            .headers(headers)
            .build());
    System.out.println("Received webhook event");
    return ResponseEntity.ok("OK");
  } catch (Exception e) {
    System.err.println("Webhook verification failed: " + e.getMessage());
    return ResponseEntity.badRequest().body("Invalid signature");
  }
}

适用场景

需要在美国发送 A2P 短信的 Java 应用，必须完成 10DLC 品牌与活动注册。
需要以编程方式管理品牌、活动、电话号码与消息配置文件关联的自动化流程。
需要处理 Telnyx Webhook 事件（如活动状态更新）并验证签名的服务端应用。

限制

10DLC 注册是顺序性的，必须按品牌、活动、分配的顺序执行。
注册调用本身不足以使消息可用，必须成功完成分配步骤。
不应假设活动已可发送，直到返回的状态字段确认。
不要虚构 Telnyx 参数、枚举、响应字段或 Webhook 字段。如果需要的参数、枚举或响应字段未在技能中内联显示，应阅读 references/api-details.md。
使用“附加操作”中的任何操作前，应阅读可选参数部分和响应模式部分。
阅读或匹配内联示例之外的 Webhook 字段前，应阅读 Webhook 负载参考。
关于收费、价格、平台支持等具体信息，资料中暂未提供。