用途
本技能面向使用 Telnyx WhatsApp Business API 的开发者，提供基于 curl 的调用示例，用于发送 WhatsApp 消息、管理消息模板、WABA（WhatsApp Business Account）以及电话号码。curl 在 macOS、Linux 和 Windows 10+ 上已预装，无需额外安装。
认证与准备
通过环境变量设置 API 密钥：
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
所有示例均使用 $TELNYX_API_KEY 进行认证。电话号码必须为 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码。
主要能力
发送模板消息
发送预审批的模板消息，模板可随时发送，不受 24 小时窗口限制。接口为 POST /messages/whatsapp。关键参数包括 from、to、type（须为 WHATSAPP）、whatsapp_message.type（须为 template）、模板名称与语言代码，或直接使用 Telnyx 模板 UUID（template_id，提供后自动解析名称与语言）。可附带 components 参数值、messaging_profile_id 和 webhook_url。
发送自由文本消息
在客户最后一次发消息后的 24 小时客服窗口内发送文本消息，接口同为 POST /messages/whatsapp，whatsapp_message.type 为 text，正文放在 whatsapp_message.text.body。
管理 WABA
列出账户下所有 WABA：GET /v2/whatsapp/business_accounts，支持分页参数 page[number] 与 page[size]。
管理模板
列出模板：GET /v2/whatsapp/message_templates，可按 waba_id、category（AUTHENTICATION、MARKETING、UTILITY）、status（APPROVED、PENDING、REJECTED、DISABLED）过滤。创建模板：POST /v2/whatsapp/message_templates，需提供 waba_id、name、category、language、components。模板名称须为小写加下划线（如 order_update），提交后通常需数分钟到数小时由 Meta 审核。
管理电话号码
列出电话号码：GET /v2/whatsapp/phone_numbers，可按 waba_id 过滤，返回号码、Meta 号码 ID、质量评级（GREEN、YELLOW、RED）和消息发送层级。
Webhook 与错误处理
Telnyx 使用 Ed25519 对 Webhook 签名，请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头，生产环境应验证签名。常见错误码包括 401（无效 API 密钥）、403（权限不足）、404（资源未找到）、422（校验错误）、429（限流，建议指数退避重试）。WhatsApp 专有错误码包括 40008（Meta 通用错误）、131047（24 小时窗口外发送失败）、131026（接收方非 WhatsApp 用户）、132000（模板参数数量不匹配）、132015（模板因质量问题被暂停或禁用）。
使用方式
所有操作通过 curl 命令调用 Telnyx REST API，认证头为 Authorization: Bearer $TELNYX_API_KEY，内容类型为 application/json。发送消息、创建模板等写操作使用 POST，查询使用 GET，更新使用 PATCH。
适用场景
适用于需要通过 Telnyx 集成 WhatsApp Business 消息能力的后端开发、自动化脚本和运维场景，包括订单通知、验证码、营销推送等模板消息发送，以及模板生命周期管理和号码质量监控。
限制与注意事项
发送号码必须注册到 WABA 并关联消息配置文件；模板须处于 APPROVED 状态才能发送；模板名称须为小写加下划线，不能含空格、连字符或大写；创建模板时需为正文参数提供真实示例值，Meta 审核时会检查；类别选择影响计费，AUTHENTICATION 模板须包含 OTP，UTILITY 用于事务性消息，MARKETING 用于推广内容；Meta 可能重新分类模板类别从而影响计费。自由文本消息只能在客户最后发消息后的 24 小时窗口内发送。不要自行编造 Telnyx 参数、枚举、响应字段或 Webhook 字段；若所需字段未在技能中内联展示，应先阅读 references/api-details.md。