用途
twilio-send-message 用于通过 Twilio 的 Programmable Messaging API 在多种消息渠道上发送消息，包括 SMS、MMS、RCS 和 WhatsApp。它通过单次 messages.create() 调用即可在任意渠道发送，具体渠道由发送方地址和接收方能力决定。
主要能力
- 支持 SMS、MMS、RCS（含或不含 SMS 回退）以及 WhatsApp 渠道。
- 支持发送文本消息、媒体附件（图片、PDF、音频、视频，单附件最大 5 MB）以及模板消息（WhatsApp 在 24 小时窗口外必须使用模板；RCS 富内容）。
- 支持通过 status_callback 跟踪送达状态，Twilio 会在 queued → sent → delivered（或 failed/undelivered）等状态转换时发送 POST 回调。
- 支持通过 Messaging Service 配置 RCS→SMS 回退，该配置在 Messaging Service 上完成，而非逐条消息设置。
- 生产环境建议使用 messagingServiceSid 而非 from，以启用发送方池管理、RCS→SMS 回退、SMS 防刷保护、链接缩短、合规工具包和定时发送等功能。
使用方式
前置条件：
- Twilio 账户。
- 环境变量：TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN。
- SDK：pip install twilio 或 npm install twilio。
- 渠道专用发送方：SMS/MMS 需要 Twilio 电话号码；RCS 需要添加到 Messaging Service 的 RCS 发送方；WhatsApp 需要活跃的 WhatsApp 发送方。
各渠道的 to 格式：
- SMS/MMS：+15551234567（MMS 仅限美国/加拿大/澳大利亚）。
- RCS（含 SMS 回退）：+15551234567，通过同时具有 RCS 发送方和 SMS 发送方的 Messaging Service 发送，Twilio 先尝试 RCS，失败后回退到 SMS。
- RCS（无回退）：rcs:+15551234567，强制仅使用 RCS，若接收方不支持 RCS 则失败。
- WhatsApp：whatsapp:+15551234567，通过带 whatsapp: 前缀的 from 发送；在 24 小时窗口外需要模板。
Python 示例：
import os from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
SMS
sms = client.messages.create( from_="+15017122661", to="+15558675310", body="Your order has shipped." )
RCS — forces RCS only, no fallback
rcs = client.messages.create( messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to="rcs:+15558675310", body="Your order has shipped." )
whatsapp = client.messages.create( from_="whatsapp:+15017122661", to="whatsapp:+15558675310", body="Your order has shipped." )
Via Messaging Service (recommended — attempts RCS first, falls back to SMS)
msg = client.messages.create( messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to="+15558675310", body="Your order has shipped." )
Node.js 示例：
const client = require("twilio")(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
// SMS const sms = await client.messages.create({ from: "+15017122661", to: "+15558675310", body: "Your order has shipped.", });
// RCS — forces RCS only, no fallback const rcs = await client.messages.create({ messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to: "rcs:+15558675310", body: "Your order has shipped.", });
// WhatsApp const whatsapp = await client.messages.create({ from: "whatsapp:+15017122661", to: "whatsapp:+15558675310", body: "Your order has shipped.", });
// Via Messaging Service (attempts RCS first, falls back to SMS) const msg = await client.messages.create({ messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to: "+15558675310", body: "Your order has shipped.", });
发送媒体（MMS、WhatsApp、RCS）：
client.messages.create( from_="+15017122661", to="+15558675310", body="Here is your invoice.", media_url=["https://example.com/invoice.pdf"] )
发送模板（WhatsApp 在 24 小时窗口外必需；RCS 富内容）：
client.messages.create( messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to="+15558675310", content_sid="HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", content_variables='{"1": "Sarah", "2": "12345"}' )
跟踪送达状态：
client.messages.create( messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to="+15558675310", body="Hello!", status_callback="https://yourapp.com/status" )
适用场景
- 发送订单状态、通知等文本消息。
- 发送带媒体附件的消息（发票、图片等）。
- 使用模板发送 WhatsApp 消息或 RCS 富内容。
- 需要 RCS→SMS 回退的生产环境消息发送。
- 需要跟踪消息送达状态的场景。
- OTP/验证用例（可参考 twilio-verify-send-otp）。
限制
- 无法在单次 API 调用中跨渠道发送。一次 messages.create() 对应一个渠道。多渠道回退需通过 Messaging Service 实现 RCS→SMS，或在应用中自行实现顺序发送。
- 无法在 24 小时服务窗口外发送 WhatsApp 自由格式消息，必须使用预先批准的模板（content_sid）。
- 无法在美国/加拿大以外发送 MMS。国际富媒体请使用 WhatsApp 或 RCS。
- 没有 Messaging Service 就无法配置 RCS→SMS 回退。原始 from 发送不支持 FallbackFrom。
- 无法保证任何渠道的送达。应始终实现状态回调。
常见错误
- 21211：无效的 to 号码，需验证 E.164 格式。
- 21408：地区不允许，需在控制台启用地理权限。
- 21610：接收方已退订，不要重试，尊重退订。
- 21664：FallbackFrom 不能与 From 发送方一起使用，改用 messaging_service_sid 而非 from。
- 21666：FallbackFrom 需要 MessagingServiceSid，通过 Messaging Service 发送。
- 21667：FallbackFrom 需要 Messaging Service 上的 RCS 发送方，配置回退前先添加 RCS 发送方。
- 30003：目标不可达，运营商无法送达。
- 30007：消息被过滤为垃圾信息，检查内容和发送方信誉。
- 30034：美国 A2P 10DLC — 发送方未注册，需注册品牌和活动。
- 30036：有效期已过，消息过期，通常表明 RCS 回退配置错误。
- 63036：RCS 接收方不可达，在 Messaging Service 上配置 SMS 回退。