twilio-sms-send-message

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

SMS is one channel in Twilio's Messaging platform. All channels — SMS, WhatsApp, RCS, Facebook Messenger — share the same

messages.create()

API. See

twilio-messaging-overview

for the full channel comparison and onboarding sequence.

When to use SMS	When to consider alternatives
Reach any phone number globally	Need rich media outside US/CA/AU → WhatsApp
No app install required	Opted-in audience prefers chat apps → WhatsApp
Time-sensitive alerts (OTP, outage)	Marketing campaigns → `twilio-marketing-promotions-advisor`
Regulatory/compliance requires SMS	Cost-sensitive high-volume → WhatsApp (lower per-msg cost in many markets)

For production SMS: Use a Messaging Service (

messagingServiceSid

) instead of a raw

from

number. It enables sender pool management, compliance toolkit, SMS pumping protection, link shortening, and message scheduling. See

twilio-messaging-services

Every outbound SMS requires a

from

Twilio number (or

messagingServiceSid

) and a

to

recipient — both in E.164 format.

SMS是Twilio消息平台中的一个渠道。 所有渠道——SMS、WhatsApp、RCS、Facebook Messenger——都共享相同的

messages.create()

API。如需完整的渠道对比和入门流程，请查看

twilio-messaging-overview

。

何时使用SMS	何时考虑替代方案
触达全球任意电话号码	需要美国/加拿大/澳大利亚以外地区的富媒体内容 → WhatsApp
无需安装应用	已订阅用户偏好聊天应用 → WhatsApp
时间敏感型提醒（OTP、故障通知）	营销活动 → `twilio-marketing-promotions-advisor`
监管/合规要求使用SMS	对成本敏感的高发送量场景 → WhatsApp（在许多市场中每条消息成本更低）

生产环境SMS建议： 使用消息服务（

messagingServiceSid

）而非原始

from

号码。它支持发送方池管理、合规工具包、短信泵防护、链接缩短和消息调度。详情请查看

twilio-messaging-services

。

每条外发SMS都需要一个Twilio的

from

号码（或

messagingServiceSid

）和一个

to

接收方——两者都必须采用E.164格式。

Prerequisites

前提条件

Twilio account with an SMS-capable phone number — New to Twilio? See
```
twilio-account-setup
```
for signup, getting a number, and trial limitations
Environment variables:
- ```
TWILIO_ACCOUNT_SID
```
- ```
TWILIO_AUTH_TOKEN
```
  — See
```
twilio-iam-auth-setup
```
  for credential setup and best practices
SDK:
```
pip install twilio
```
/
```
npm install twilio
```

拥有支持SMS功能电话号码的Twilio账户 —— 新用户？请查看
```
twilio-account-setup
```
了解注册流程、获取号码及试用限制
环境变量：
- ```
TWILIO_ACCOUNT_SID
```
- ```
TWILIO_AUTH_TOKEN
```
  —— 请查看
```
twilio-iam-auth-setup
```
  了解凭证设置及最佳实践
SDK：
```
pip install twilio
```
/
```
npm install twilio
```

Quickstart

快速入门

Python

python

import os
from twilio.rest import Client

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

message = client.messages.create(
    from_="+15017122661",   # Your Twilio number (E.164)
    to="+15558675310",      # Recipient (E.164)
    body="Your appointment is confirmed for tomorrow at 2pm."
)

print(message.sid)     # SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
print(message.status)  # queued | sent | delivered | failed

Node.js

node

const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Your appointment is confirmed for tomorrow at 2pm.",
});

console.log(message.sid);
console.log(message.status);

Python

python

import os
from twilio.rest import Client

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

message = client.messages.create(
    from_="+15017122661",   # 你的Twilio号码（E.164格式）
    to="+15558675310",      # 接收方号码（E.164格式）
    body="Your appointment is confirmed for tomorrow at 2pm."
)

print(message.sid)     # SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
print(message.status)  # queued | sent | delivered | failed

Node.js

node

const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Your appointment is confirmed for tomorrow at 2pm.",
});

console.log(message.sid);
console.log(message.status);

Key Patterns

核心模式

Send MMS (with media)

发送MMS（含媒体内容）

Python

python

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

Node.js

node

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Here is your invoice.",
    mediaUrl: ["https://example.com/invoice.pdf"],
});

Supported media types: images (JPEG, PNG, GIF), PDF, audio, video. Max 5 MB per message.

Python

python

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

Node.js

node

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Here is your invoice.",
    mediaUrl: ["https://example.com/invoice.pdf"],
});

支持的媒体类型：图片（JPEG、PNG、GIF）、PDF、音频、视频。单条消息最大5 MB。

Send via Messaging Service (recommended for scale)

通过消息服务发送（推荐用于大规模场景）

Use

messagingServiceSid

instead of

from

— Twilio picks the best sender automatically from your pool.

Python

python

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

Node.js

node

const message = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "+15558675310",
    body: "Your order has shipped.",
});

使用

messagingServiceSid

替代

from

——Twilio会自动从你的发送方池中选择最佳发送号码。

Python

python

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

Node.js

node

const message = await client.messages.create({
    messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    to: "+15558675310",
    body: "Your order has shipped.",
});

Track Delivery Status

跟踪交付状态

Python

python

message = client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Hello!",
    status_callback="https://yourapp.com/sms-status"
)

Node.js

node

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Hello!",
    statusCallback: "https://yourapp.com/sms-status",
});

Twilio POSTs to your URL at each transition:

queued → sent → delivered

(or

failed

undelivered

Python

python

message = client.messages.create(
    from_="+15017122661",
    to="+15558675310",
    body="Hello!",
    status_callback="https://yourapp.com/sms-status"
)

Node.js

node

const message = await client.messages.create({
    from: "+15017122661",
    to: "+15558675310",
    body: "Hello!",
    statusCallback: "https://yourapp.com/sms-status",
});

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

queued → sent → delivered

（或

failed

undelivered

）。

Response Fields

响应字段

Field	Description
`sid`	Message identifier ( `SM...` )
`status`	`queued` , `sent` , `delivered` , `undelivered` , `failed`
`error_code`	Populated on failure
`error_message`	Human-readable description
`price`	Cost (populated after delivery)
`date_sent`	UTC timestamp

字段	描述
`sid`	消息标识符（ `SM...` ）
`status`	状态： `queued` （已排队）、 `sent` （已发送）、 `delivered` （已交付）、 `undelivered` （未交付）、 `failed` （失败）
`error_code`	失败时填充
`error_message`	易读的错误描述
`price`	费用（交付后填充）
`date_sent`	UTC时间戳

Common Errors

常见错误

Code	Meaning	Fix
21211	Invalid `to` number	Validate E.164 format
21408	Permission to send to region not enabled	Enable geo-permissions in Console
21610	Number is on blocklist (opted out)	Do not retry; respect opt-out
30003	Unreachable destination	Carrier cannot deliver; try later
30007	Message filtered as spam	Review content and sender reputation
30034	Message from unregistered number	Complete A2P 10DLC registration — see `twilio-compliance-onboarding`
30450	SMS pumping detected	Message blocked by SMS pumping protection — see `twilio-messaging-services`

代码	含义	修复方案
21211	无效的 `to` 号码	验证E.164格式
21408	未启用向目标地区发送的权限	在控制台中启用地理权限
21610	号码在黑名单中（已退订）	请勿重试；尊重退订请求
30003	目标不可达	运营商无法交付；稍后重试
30007	消息被标记为垃圾短信	检查内容和发送方信誉
30034	来自未注册号码的消息	完成A2P 10DLC注册 —— 查看 `twilio-compliance-onboarding`
30450	检测到短信泵行为	消息被短信泵防护拦截 —— 查看 `twilio-messaging-services`

Messages Being Filtered or Blocked?

消息被过滤或拦截？

If your messages aren't being delivered, check these causes in order:

Unregistered sender (error 30034) — US 10DLC numbers must be registered. See
```
twilio-compliance-onboarding
```
Spam filtered (error 30007) — Carrier flagged content. Check: opt-out language included? URL shorteners avoided? Content matches registered campaign?
Opted-out recipient (error 21610) — Recipient sent STOP. Do not retry. See
```
twilio-compliance-traffic
```
Geo-permissions disabled (error 21408) — Enable the destination country in Console > Messaging > Settings > Geo Permissions. See
```
twilio-security-hardening
```
SMS pumping (error 30450) — Artificial traffic detected. Whitelist known prefixes via Global Safe List. See
```
twilio-messaging-services
```
Account suspended — Check Console for account status notifications. See
```
twilio-account-setup
```

For delivery event tracking, set up StatusCallbacks or use

twilio-debugging-observability

如果你的消息无法交付，请按以下顺序排查原因：

发送方未注册（错误码30034） —— 美国10DLC号码必须注册。查看
```
twilio-compliance-onboarding
```
被标记为垃圾短信（错误码30007） —— 运营商标记了内容。检查：是否包含退订语言？是否避免使用链接缩短器？内容是否与注册的活动匹配？
接收方已退订（错误码21610） —— 接收方发送了STOP指令。请勿重试。查看
```
twilio-compliance-traffic
```
地理权限未启用（错误码21408） —— 在控制台 > 消息 > 设置 > 地理权限中启用目标国家。查看
```
twilio-security-hardening
```
检测到短信泵行为（错误码30450） —— 检测到人工流量。通过全球安全名单白名单已知前缀。查看
```
twilio-messaging-services
```
账户被暂停 —— 在控制台中检查账户状态通知。查看
```
twilio-account-setup
```

如需跟踪交付事件，请设置StatusCallbacks或使用

twilio-debugging-observability

。

CANNOT

注意事项

Cannot send without E.164 format — Both
```
from
```
and
```
to
```
must be
```
+
```
followed by country code and number
Cannot send to unverified numbers on trial accounts — Upgrade to paid or verify recipient numbers first
Cannot send MMS outside US, Canada, and Australia — MMS is only supported on US/CA/AU numbers; for international rich media use WhatsApp
Cannot exceed 1,600 characters per message — Longer messages are automatically split into segments (each billed separately)
Cannot prevent SMS pumping without a Messaging Service — Enable SMS pumping protection via Messaging Services to prevent artificial traffic inflation. See
```
twilio-messaging-services
```

必须使用E.164格式 ——
```
from
```
和
```
to
```
号码都必须以
```
+
```
开头，后跟国家代码和号码
试用账户无法向未验证号码发送消息 —— 升级为付费账户或先验证接收方号码
无法在美国、加拿大和澳大利亚以外地区发送MMS —— MMS仅支持美国/加拿大/澳大利亚号码；国际富媒体内容请使用WhatsApp
单条消息长度不能超过1600字符 —— 更长的消息会自动拆分为多个片段（每个片段单独计费）
不使用消息服务无法防范短信泵行为 —— 通过消息服务启用短信泵防护，防止人工流量膨胀。查看
```
twilio-messaging-services
```

Next Steps

下一步

Channel overview and onboarding guide:
```
twilio-messaging-overview
```
Receive inbound SMS and delivery status:
```
twilio-messaging-webhooks
```
Manage sender pools at scale:
```
twilio-messaging-services
```
US compliance for A2P traffic:
```
twilio-compliance-onboarding
```
Send via WhatsApp instead:
```
twilio-whatsapp-send-message
```

渠道概述及入门指南：
```
twilio-messaging-overview
```
接收 inbound SMS 和交付状态：
```
twilio-messaging-webhooks
```
大规模管理发送方池：
```
twilio-messaging-services
```
美国A2P流量合规：
```
twilio-compliance-onboarding
```
改用WhatsApp发送：
```
twilio-whatsapp-send-message
```