twilio-send-message

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

A single
messages.create()
call sends on any messaging channel — SMS, MMS, RCS, or WhatsApp. The channel is determined by the sender address and the recipient's capabilities. For channel selection guidance and the full onboarding sequence, see

twilio-messaging-overview

and

twilio-messaging-channel-advisor

Channel	`to` format	Notes	Template required?
SMS/MMS	`+15551234567`	MMS: US/CA/AU only	No
RCS (with SMS fallback)	`+15551234567`	Send via Messaging Service that has both an RCS sender and an SMS sender — Twilio attempts RCS first, falls back to SMS on failure	No
RCS (no fallback)	`rcs:+15551234567`	Forces RCS only — fails if recipient isn't RCS-capable	No
WhatsApp	`whatsapp:+15551234567`	Send via `whatsapp:` -prefixed `from`	Outside 24-hr window: yes

For production: Send via

messagingServiceSid

instead of

from

. This enables sender pool management, RCS→SMS fallback, SMS pumping protection, link shortening, compliance toolkit, and scheduling. See

twilio-messaging-services

单次
messages.create()
调用即可在任意消息渠道发送消息——SMS、MMS、RCS或WhatsApp。渠道由发送方地址和接收方的功能决定。如需渠道选择指导和完整的入门流程，请查看

twilio-messaging-overview

和

twilio-messaging-channel-advisor

。

渠道	`to` 格式	说明	是否需要模板？
SMS/MMS	`+15551234567`	MMS：仅支持美国/加拿大/澳大利亚	否
RCS（带SMS fallback）	`+15551234567`	通过同时包含RCS发送方和SMS发送方的Messaging Service发送——Twilio优先尝试RCS，失败则 fallback 到SMS	否
RCS（无fallback）	`rcs:+15551234567`	强制仅使用RCS——若接收方不支持RCS则发送失败	否
WhatsApp	`whatsapp:+15551234567`	通过前缀为 `whatsapp:` 的 `from` 发送	超出24小时窗口：是

生产环境建议： 使用

messagingServiceSid

而非

from

发送消息。这将启用发送方池管理、RCS→SMS fallback、SMS防滥用保护、链接缩短、合规工具包和调度功能。请查看

twilio-messaging-services

。

Prerequisites

前置条件

Twilio account — New to Twilio? See
```
twilio-account-setup
```

Environment variables:

TWILIO_ACCOUNT_SID

TWILIO_AUTH_TOKEN

— see

twilio-iam-auth-setup

SDK:
```
pip install twilio
```
/
```
npm install twilio
```
Channel-specific senders:
- SMS/MMS: a Twilio phone number (see
```
twilio-account-setup
```
  )
- RCS: an RCS sender added to a Messaging Service (see
```
twilio-rcs-messaging
```
  )
- WhatsApp: an active WhatsApp sender (see
```
twilio-whatsapp-send-message
```
  for sandbox,
```
twilio-whatsapp-manage-senders
```
  for production)

Twilio账户——首次使用Twilio？请查看
```
twilio-account-setup
```

环境变量：

TWILIO_ACCOUNT_SID

、

TWILIO_AUTH_TOKEN

——请查看

twilio-iam-auth-setup

SDK：
```
pip install twilio
```
/
```
npm install twilio
```
渠道专属发送方：
- SMS/MMS：一个Twilio电话号码（查看
```
twilio-account-setup
```
  ）
- RCS：已添加到Messaging Service的RCS发送方（查看
```
twilio-rcs-messaging
```
  ）
- WhatsApp：一个活跃的WhatsApp发送方（沙箱环境查看
```
twilio-whatsapp-send-message
```
  ，生产环境查看
```
twilio-whatsapp-manage-senders
```
  ）

Quickstart

快速入门

Python

python

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

Python

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**
```javascript
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.",
});

msg = client.messages.create( messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", to="+15558675310", body="Your order has shipped." )


**Node.js**
```javascript
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.",
});

Key Patterns

核心模式

Send with media (MMS, WhatsApp, RCS)

发送带媒体的消息（MMS、WhatsApp、RCS）

python

client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Here is your invoice.",
    media_url=["https://example.com/invoice.pdf"]
)

Supported: images (JPEG, PNG, GIF), PDF, audio, video. 5 MB max per attachment.

python

client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Here is your invoice.",
    media_url=["https://example.com/invoice.pdf"]
)

支持的媒体类型：图片（JPEG、PNG、GIF）、PDF、音频、视频。每个附件最大5MB。

Send a template (WhatsApp required outside 24-hr window; RCS rich content)

发送模板消息（WhatsApp超出24小时窗口时必填；RCS富内容）

python

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    content_sid="HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    content_variables='{"1": "Sarah", "2": "12345"}'
)

See

twilio-content-template-builder

for building templates.

python

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    content_sid="HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    content_variables='{"1": "Sarah", "2": "12345"}'
)

如需创建模板，请查看

twilio-content-template-builder

。

Track delivery status

跟踪消息送达状态

python

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Hello!",
    status_callback="https://yourapp.com/status"
)

Twilio POSTs at each state transition:

queued → sent → delivered

(or

failed

undelivered

python

client.messages.create(
    messaging_service_sid="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to="+15558675310",
    body="Hello!",
    status_callback="https://yourapp.com/status"
)

Twilio会在每个状态转换时发送POST请求：

queued → sent → delivered

（或

failed

undelivered

）。

Configure RCS→SMS fallback

配置RCS→SMS fallback

Configured on the Messaging Service, not per-message. Add both an RCS sender and an SMS sender to the same Messaging Service. Twilio attempts RCS first and falls back to SMS on failure. See

twilio-messaging-services

and

twilio-rcs-messaging

需在Messaging Service上配置，而非单条消息。将RCS发送方和SMS发送方添加到同一个Messaging Service中。Twilio会优先尝试RCS，失败则fallback到SMS。请查看

twilio-messaging-services

和

twilio-rcs-messaging

。

Common Errors

常见错误

Code	Meaning	Fix
21211	Invalid `to` number	Validate E.164 format
21408	Region not permitted	Enable geo-permissions in Console
21610	Recipient opted out	Do not retry; respect opt-out
21664	`FallbackFrom` cannot be used with `From` sender	Use `messaging_service_sid` instead of `from`
21666	`FallbackFrom` requires `MessagingServiceSid`	Send via a Messaging Service
21667	`FallbackFrom` requires an RCS Sender on the Messaging Service	Add an RCS sender before configuring fallback
30003	Unreachable destination	Carrier cannot deliver
30007	Message filtered as spam	Review content and sender reputation
30034	US A2P 10DLC — sender not registered	Register brand + campaign. See `twilio-compliance-onboarding`
30036	Validity Period expired	Message aged out. Often indicates RCS fallback is misconfigured
63036	RCS recipient unreachable	Configure SMS fallback on the Messaging Service

错误码	含义	修复方案
21211	`to` 号码无效	验证E.164格式
21408	区域不被允许	在控制台启用地域权限
21610	接收方已退订	请勿重试；尊重退订请求
21664	`FallbackFrom` 无法与 `From` 发送方一起使用	使用 `messaging_service_sid` 替代 `from`
21666	`FallbackFrom` 需要 `MessagingServiceSid`	通过Messaging Service发送消息
21667	`FallbackFrom` 要求Messaging Service上存在RCS发送方	配置fallback前先添加RCS发送方
30003	目标地址不可达	运营商无法送达
30007	消息被标记为垃圾信息	检查内容和发送方信誉
30034	美国A2P 10DLC——发送方未注册	注册品牌和营销活动。请查看 `twilio-compliance-onboarding`
30036	有效期已过期	消息超时。通常表示RCS fallback配置错误
63036	RCS接收方不可达	在Messaging Service上配置SMS fallback

CANNOT

注意事项（无法实现的操作）

Cannot send cross-channel in a single API call. One
```
messages.create()
```
= one channel. For multi-channel fallback, use RCS→SMS via a Messaging Service, or implement sequencing in your app.
Cannot send WhatsApp free-form outside the 24-hour service window. Use a pre-approved template (
```
content_sid
```
). See
```
twilio-whatsapp-send-message
```
.
Cannot send MMS outside US/Canada. For international rich media, use WhatsApp or RCS.
Cannot configure RCS→SMS fallback without a Messaging Service. Raw
```
from
```
sends don't support
```
FallbackFrom
```
.
Cannot guarantee delivery on any channel. Always implement status callbacks.

无法通过单次API调用跨渠道发送消息。 一次
```
messages.create()
```
调用对应一个渠道。如需多渠道fallback，请通过Messaging Service使用RCS→SMS，或在你的应用中实现序列发送逻辑。
无法在WhatsApp的24小时服务窗口外发送自由格式消息。 请使用预先审核通过的模板（
```
content_sid
```
）。查看
```
twilio-whatsapp-send-message
```
。
无法在美国/加拿大以外地区发送MMS。 如需国际富媒体消息，请使用WhatsApp或RCS。
无Messaging Service时无法配置RCS→SMS fallback。 直接使用
```
from
```
发送不支持
```
FallbackFrom
```
。
无法保证任意渠道的消息送达率。 请始终实现状态回调。

Next Steps

下一步操作

Pick a channel for your use case:
```
twilio-messaging-channel-advisor
```
Full messaging platform overview:
```
twilio-messaging-overview
```

Channel-specific deep dives:

twilio-sms-send-message

twilio-rcs-messaging

twilio-whatsapp-send-message

Sender pools, fallback, production features:
```
twilio-messaging-services
```
Build templates (cards, carousels, quick replies):
```
twilio-content-template-builder
```
Handle inbound messages and status callbacks:
```
twilio-messaging-webhooks
```
US A2P 10DLC compliance:
```
twilio-compliance-onboarding
```
OTP / verification use cases:
```
twilio-verify-send-otp
```

为你的场景选择渠道：
```
twilio-messaging-channel-advisor
```
完整消息平台概述：
```
twilio-messaging-overview
```

渠道深度指南：

twilio-sms-send-message

、

twilio-rcs-messaging

、

twilio-whatsapp-send-message

发送方池、fallback、生产环境功能：
```
twilio-messaging-services
```
创建模板（卡片、轮播、快捷回复）：
```
twilio-content-template-builder
```
处理入站消息和状态回调：
```
twilio-messaging-webhooks
```
美国A2P 10DLC合规：
```
twilio-compliance-onboarding
```
OTP/验证码场景：
```
twilio-verify-send-otp
```