telnyx-whatsapp-curl

用途

本技能面向使用 Telnyx WhatsApp Business API 的开发者，提供基于 curl 的调用方式，用于发送 WhatsApp 消息并管理相关资源（模板、WABA、电话号码）。

主要能力

发送 WhatsApp 模板消息：使用预审批模板，可随时发送，不受 24 小时窗口限制。支持通过模板名称 + 语言代码，或通过 Telnyx 模板 UUID（template_id）引用模板。
发送自由文本消息：仅在客户最后发消息后的 24 小时窗口内可用。
管理消息模板：列出模板（可按 WABA、category、status 过滤）、创建模板（提交 Meta 审核）、获取模板详情。
管理 WABA：列出 WhatsApp Business Account、获取 WABA 详情、查看与更新 WABA 设置（含 Webhook 配置）。
管理电话号码：列出 WABA 电话号码、查看与更新业务资料。
Webhook：接收消息投递状态更新、模板状态变更、电话号码质量变更等事件。

使用方式

安装：curl 在 macOS、Linux 和 Windows 10+ 上已预装。

设置认证：

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

所有请求使用 Authorization: Bearer $TELNYX_API_KEY 头。

发送模板消息示例：

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "from": "+19452940762",
      "to": "+18005551234",
      "type": "WHATSAPP",
      "whatsapp_message": {
        "type": "template",
        "template": {
          "name": "order_confirmation",
          "language": { "code": "en_US" },
          "components": [
            {
              "type": "body",
              "parameters": [
                { "type": "text", "text": "ORD-12345" },
                { "type": "text", "text": "March 15, 2026" }
              ]
            }
          ]
        }
      }
  }' \
  "https://api.telnyx.com/v2/messages/whatsapp"

发送自由文本消息示例：

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "from": "+19452940762",
      "to": "+18005551234",
      "type": "WHATSAPP",
      "whatsapp_message": {
        "type": "text",
        "text": { "body": "Your order has shipped!" }
      }
  }' \
  "https://api.telnyx.com/v2/messages/whatsapp"

创建模板示例：

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "waba_id": "019c1ff0-5c30-7f36-8436-730b1d0b0e56",
      "name": "order_shipped",
      "category": "UTILITY",
      "language": "en_US",
      "components": [
        {
          "type": "BODY",
          "text": "Your order {{1}} has been shipped and will arrive by {{2}}.",
          "example": {
            "body_text": [["ORD-12345", "March 20, 2026"]]
          }
        }
      ]
  }' \
  "https://api.telnyx.com/v2/whatsapp/message_templates"

适用场景

通过模板消息发送订单确认、发货通知、账户提醒等事务性消息。
在客户主动联系后的 24 小时窗口内进行自由文本客服回复。
创建并管理 WhatsApp 消息模板，提交 Meta 审核。
查询 WABA、电话号码与业务资料，配置 Webhook 接收投递与模板状态事件。

限制与注意事项

电话号码必须为 E.164 格式（如 +13125550001），包含 + 前缀和国家代码。
模板消息可随时发送；自由文本（会话）消息只能在客户最后发消息后的 24 小时窗口内发送。
发送号码必须注册到 WhatsApp Business Account（WABA）并关联消息配置文件。
模板必须处于 APPROVED 状态才能用于发送。
模板名称必须为小写并使用下划线（如 order_confirmation），不能有空格、连字符或大写。
创建模板时需为正文参数提供真实示例值，Meta 审核时会检查。
类别选择影响计费：AUTHENTICATION 模板有特殊定价但必须包含 OTP；UTILITY 用于事务性消息；MARKETING 用于推广内容。Meta 可能重新分类模板类别（如 UTILITY 改为 MARKETING），从而影响计费。
常见错误码：401 无效 API 密钥、403 权限不足、404 资源未找到、422 验证错误、429 触发限流（需指数退避重试）。
WhatsApp 特定错误：40008（Meta 通用错误，检查模板参数、号码格式与 24 小时窗口规则）、131047（24 小时窗口内发送失败，客户未先发消息）、131026（接收方不是 WhatsApp 用户）、132000（模板参数数量不匹配）、132015（模板因质量问题被 Meta 暂停或禁用）。
Webhook 使用 Ed25519 签名，请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头，生产环境应验证签名。
不要臆造 Telnyx 参数、枚举、响应字段或 Webhook 字段；如需未内联展示的字段，应查阅 references/api-details.md。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项