用途
Telnyx Verify - Go 是 Telnyx 官方 Go 语言 SDK 的使用技能，面向需要在 Go 应用中集成电话号码信息查询与用户验证（OTP）能力的开发者。它可用于两类任务：一是查询电话号码的相关数据，二是通过短信、语音呼叫或闪信向用户发送验证码并完成校验。
主要能力
电话号码数据查询
通过 GET /number_lookup/{phone_number} 接口返回指定号码的信息，包括：caller_name（来电者名称对象）、carrier（运营商对象）、country_code（国家代码）、fraud（欺诈标识，可能为 null）、national_format（国内格式）、phone_number（号码）、portability（携号转网信息对象）、record_type（记录类型）。
验证（OTP）流程
支持三种验证触发方式：
- 短信验证：
POST /verifications/sms，必填 phone_number、verify_profile_id，可选 custom_code、timeout_secs。 - 语音呼叫验证：
POST /verifications/call，必填 phone_number、verify_profile_id，可选 custom_code、extension、timeout_secs。 - 闪信验证：
POST /verifications/flashcall，必填 phone_number、verify_profile_id，可选 timeout_secs。
验证码校验支持两种方式：
- 按电话号码校验：
POST /verifications/by_phone_number/{phone_number}/actions/verify，必填 code、verify_profile_id。 - 按验证 ID 校验：
POST /verifications/{verification_id}/actions/verify，可选 code、status。
校验返回 phone_number 与 response_code（accepted 或 rejected）。
验证记录查询
- 按电话号码列出验证记录：
GET /verifications/by_phone_number/{phone_number}。 - 按验证 ID 获取单条验证：
GET /verifications/{verification_id}。
验证记录包含 created_at、custom_code、id、phone_number、record_type、status（pending、accepted、invalid、expired、error）、timeout_secs、type（sms、call、flashcall）、updated_at、verify_profile_id。
Verify 配置文件管理
- 列出所有配置文件：
GET /verify_profiles（分页）。 - 创建配置文件：
POST /verify_profiles，必填 name，可选 call、flashcall、language、rcs、sms、webhook_failover_url、webhook_url。 - 获取单个配置文件：
GET /verify_profiles/{verify_profile_id}。 - 更新配置文件：
PATCH /verify_profiles/{verify_profile_id}。 - 删除配置文件：
DELETE /verify_profiles/{verify_profile_id}。
配置文件返回字段包括 call、created_at、flashcall、id、language、name、rcs、record_type、sms、updated_at、webhook_failover_url、webhook_url。
消息模板管理
- 列出模板：
GET /verify_profiles/templates。 - 创建模板：
POST /verify_profiles/templates，必填 text。 - 更新模板：
PATCH /verify_profiles/templates/{template_id}，必填 text。
模板返回 id 与 text，示例文本为 "Your {{app_name}} verification code is: {{code}}."。
使用方式
安装：
go get github.com/team-telnyx/telnyx-go
初始化客户端：
import ( "context" "fmt" "os"
"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )
client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )
所有示例均假设 client 已按上述方式初始化。
错误处理：所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败，生产代码中应始终处理错误。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 限流（使用指数退避重试）。
重要说明：电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀与国家代码，不能有空格、短横线或括号。分页可使用 ListAutoPaging() 自动迭代：iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }。
适用场景
- 用户注册或登录时的手机号验证。
- 敏感操作前的二次验证。
- 电话号码数据补充，例如获取运营商、号码类型与来电者名称。
- 需要按号码或按验证 ID 查询验证状态与历史记录的场景。
限制
- 电话号码必须为 E.164 格式。
- 需要有效的 TELNYX_API_KEY 环境变量。
- 调用可能受到限流、认证与校验错误影响，需要实现错误处理与重试。
- 关于收费、价格、具体平台支持范围等资料暂未提供。