用途:通过 Telnyx WhatsApp Business API 的 Ruby SDK 发送 WhatsApp 消息,并管理模板、WABA(WhatsApp Business Account)和电话号码。
安装与初始化:gem install telnyx;require "telnyx";client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])。
主要能力:发送模板消息(client.messages.send_whatsapp,POST /messages/whatsapp,模板可随时发送);发送自由格式文本消息(仅限客户最后发消息后 24 小时窗口内);列出 WABA(client.whatsapp.business_accounts.list);列出/创建模板(client.whatsapp.templates.list / create);列出电话号码(client.whatsapp.phone_numbers.list);获取模板详情、业务资料、配置 webhook。
用法要点:电话号码须为 E.164 格式(含 + 和国家代码);模板可用 name+language 或 Telnyx template_id 引用;模板名须小写加下划线;创建模板需提供真实示例值;列表接口支持 auto_paging_each 自动分页;webhook 使用 Ed25519 签名,生产环境应验证。
限制与错误:需处理 401/403/404/422/429 等错误;WhatsApp 特有错误如 131047(24 小时窗口外)、131026(非 WhatsApp 用户)、132000(模板参数数量不匹配)、132015(模板被暂停);发送号码须注册 WABA 并关联消息配置文件;模板须为 APPROVED 状态;Meta 可能重新分类模板类别影响计费。
适用场景:Ruby 应用中集成 WhatsApp 通知、订单更新、验证码等消息发送与模板管理。