用途
Telnyx Verify - Java 面向需要在 Java 应用中集成电话号码验证与号码信息查询的开发者。它提供两类核心能力：一是查询电话号码的相关信息（运营商、号码类型、主叫名称等），用于数据补全；二是通过短信、语音电话、闪信呼叫或 WhatsApp 向用户发送一次性验证码（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();
主要能力
号码信息查询
调用 client.numberLookup().retrieve("+18665552368") 查询号码信息，返回字段包括 caller_name、carrier、country_code、fraud、national_format、phone_number、portability、record_type。
验证的触发与校验
支持四种验证触发方式，均需提供 phone_number 与 verify_profile_id：
- 语音电话验证：
client.verifications().triggerCall(params)，可选 custom_code、extension、timeout_secs。 - 闪信呼叫验证：
client.verifications().triggerFlashcall(params)，可选 timeout_secs。 - 短信验证：
client.verifications().triggerSms(params)，可选 custom_code、timeout_secs。 - WhatsApp 验证：
client.verifications().triggerWhatsappVerification(params)，可选 custom_code、timeout_secs。
触发后返回验证对象，包含 created_at、custom_code、id、phone_number、record_type、status（pending、accepted、invalid、expired、error）、timeout_secs、type（sms、call、flashcall、whatsapp）、updated_at、verify_profile_id。
校验方式有两种：
- 按电话号码校验：
client.verifications().byPhoneNumber().actions().verify(params)，需提供 code 与 verify_profile_id，返回 phone_number 与 response_code（accepted、rejected）。 - 按验证 ID 校验：
client.verifications().actions().verify("12ade33a-21c0-473b-b055-b3c836e1c292")，可选 code、status。
此外可通过 client.verifications().byPhoneNumber().list("+13035551234") 按号码列出验证记录，或通过 client.verifications().retrieve("12ade33a-21c0-473b-b055-b3c836e1c292") 按 ID 获取单条验证。
验证配置（Verify profile）管理
- 列出：
client.verifyProfiles().list()，返回分页结果。 - 创建：
client.verifyProfiles().create(params)，必填 name，可选 call、daily_spend_limit、daily_spend_limit_enabled、flashcall、language、sms、webhook_failover_url、webhook_url、whatsapp。 - 获取：
client.verifyProfiles().retrieve("12ade33a-21c0-473b-b055-b3c836e1c292")。 - 更新：
client.verifyProfiles().update("12ade33a-21c0-473b-b055-b3c836e1c292")。 - 删除：
client.verifyProfiles().delete("12ade33a-21c0-473b-b055-b3c836e1c292")。
配置对象返回字段包括 call、created_at、daily_spend_limit、daily_spend_limit_enabled、flashcall、id、language、name、record_type、sms、updated_at、webhook_failover_url、webhook_url、whatsapp。
消息模板管理
- 列出模板：
client.verifyProfiles().retrieveTemplates()，返回 id 与 text。 - 创建模板：
client.verifyProfiles().createTemplate(params)，必填 text，例如 "Your {{app_name}} verification code is: {{code}}."。 - 更新模板：
client.verifyProfiles().updateTemplate(params)，需提供 template_id 与 text。
使用方式要点
- 电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀与国家代码，不能有空格、短横线或括号。
- 分页：列表方法返回一页结果，可用
.autoPager()自动迭代，例如for (var item : page.autoPager()) { ... }；也可用.hasNextPage()与.nextPage()手动控制。 - 错误处理：所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败。生产代码应捕获
TelnyxServiceException，读取e.statusCode()与e.getMessage()。常见错误码：401 无效 API key、403 权限不足、404 资源不存在、422 校验错误（检查字段格式）、429 限流（使用指数退避重试）。
适用场景
适用于需要在 Java 后端集成手机号验证流程（注册、登录、敏感操作二次确认）以及号码数据补全（识别运营商、号码类型、主叫名称）的应用。
限制
资料未提供价格、计费方式、速率上限、各接口的配额、支持的国家或地区范围、SLA 等信息，暂未提供。