twilio-send-message

用途

本技能用于通过 Twilio 的 Programmable Messaging API 在多种消息渠道发送消息，包括 SMS、MMS、RCS 和 WhatsApp。核心方式是调用一次 messages.create()，具体渠道由发送方地址（from）和接收方能力共同决定。

主要能力

多渠道发送：SMS、MMS、RCS、WhatsApp 均可通过同一 API 调用发送。
媒体消息：支持图片（JPEG、PNG、GIF）、PDF、音频、视频，单个附件最大 5 MB。
模板消息：通过 content_sid 发送模板，WhatsApp 在 24 小时服务窗口之外必须使用预批准模板；RCS 富内容也使用模板。
投递状态跟踪：通过 status_callback 接收状态回调，Twilio 会在 queued → sent → delivered（或 failed/undelivered）等状态转换时 POST 通知。
RCS→SMS 回退：在 Messaging Service 上同时配置 RCS 发送方和 SMS 发送方，Twilio 会先尝试 RCS，失败时回退到 SMS。

渠道与收件人格式

SMS/MMS：to 使用 +15551234567 格式；MMS 仅限美国、加拿大、澳大利亚；无需模板。
RCS（带 SMS 回退）：to 使用 +15551234567，通过同时具备 RCS 发送方和 SMS 发送方的 Messaging Service 发送；无需模板。
RCS（无回退）：to 使用 rcs:+15551234567，强制仅走 RCS，若接收方不支持 RCS 则失败；无需模板。
WhatsApp：to 使用 whatsapp:+15551234567，from 也需带 whatsapp: 前缀；在 24 小时窗口之外需要模板。

生产环境建议使用 messagingServiceSid 而非 from 发送，以启用发送方池管理、RCS→SMS 回退、短信防刷保护、链接缩短、合规工具包和定时发送等能力。

使用方式

前置条件：

Twilio 账户。
环境变量：TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN。
SDK：pip install twilio 或 npm install twilio。
渠道对应的发送方：SMS/MMS 需要 Twilio 电话号码；RCS 需要添加到 Messaging Service 的 RCS 发送方；WhatsApp 需要有效的 WhatsApp 发送方。

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
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"
)

配置 RCS→SMS 回退：在 Messaging Service 上配置，而非逐条消息配置。将 RCS 发送方和 SMS 发送方添加到同一个 Messaging Service，Twilio 会先尝试 RCS，失败时回退到 SMS。

适用场景

订单发货、通知等文本消息发送。
发送发票、图片等媒体内容。
在 WhatsApp 24 小时窗口外使用预批准模板触达用户。
需要 RCS 优先、SMS 兜底的多渠道触达。
需要跟踪消息投递状态的业务场景。

限制

无法在单次 API 调用中跨渠道发送：一次 messages.create() 只对应一个渠道。多渠道回退可通过 Messaging Service 实现 RCS→SMS，或在应用中自行编排。
无法在 WhatsApp 24 小时服务窗口之外发送自由格式消息，必须使用预批准模板（content_sid）。
MMS 无法在美国、加拿大以外的地区发送；国际富媒体请使用 WhatsApp 或 RCS。
没有 Messaging Service 就无法配置 RCS→SMS 回退；直接使用 from 发送不支持 FallbackFrom。
任何渠道都无法保证投递，应始终实现状态回调。

常见错误

21211：to 号码无效，需校验 E.164 格式。
21408：地区不被允许，需在控制台启用地理权限。
21610：接收方已退订，不要重试，尊重退订。
21664：FallbackFrom 不能与 From 发送方一起使用，改用 messaging_service_sid。
21666：FallbackFrom 需要 MessagingServiceSid，需通过 Messaging Service 发送。
21667：FallbackFrom 需要 Messaging Service 上的 RCS 发送方，配置回退前先添加 RCS 发送方。
30003：目的地不可达，运营商无法投递。
30007：消息被过滤为垃圾信息，需检查内容和发送方信誉。
30034：美国 A2P 10DLC 发送方未注册，需注册品牌和活动。
30036：有效期过期，消息超时，通常表明 RCS 回退配置有误。
63036：RCS 接收方不可达，需在 Messaging Service 上配置 SMS 回退。