SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场twilio-sms-send-message

twilio-sms-send-message

通用与其它

查看项目

更新于 10-14 05:35

技能介绍

概述

SMS 是 Twilio 消息平台中的一个渠道。所有渠道——SMS、WhatsApp、RCS、Facebook Messenger——共用相同的 messages.create() API。完整渠道对比与接入流程参见 twilio-messaging-overview。

适用场景与替代方案

  • 覆盖全球任意手机号 → 使用 SMS
  • 需要在美加澳以外发送富媒体 → 使用 WhatsApp
  • 无需安装 App → 使用 SMS
  • 已订阅用户更偏好聊天应用 → 使用 WhatsApp
  • 时效性告警（OTP、故障通知）→ 使用 SMS
  • 营销活动 → 参见 twilio-marketing-promotions-advisor
  • 合规/监管要求使用短信 → 使用 SMS
  • 成本敏感的大批量发送 → 使用 WhatsApp（在许多市场单条成本更低）

生产环境短信建议：使用 Messaging Service（messagingServiceSid）而非直接使用某个 from 号码。它可以实现发送方池管理、合规工具包、短信泵送保护、链接缩短和消息排程。参见 twilio-messaging-services。

每条出站短信都需要一个 from Twilio 号码（或 messagingServiceSid）和一个 to 收件人，二者均需使用 E.164 格式。

前置条件

  • 拥有一个支持短信的 Twilio 账号与电话号码
  • 初次使用 Twilio？参见 twilio-account-setup 了解注册、获取号码及试用限制
  • 环境变量：TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN（凭据设置与最佳实践参见 twilio-iam-auth-setup）
  • SDK：pip install twilio / npm install twilio

快速开始

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：

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

核心模式

发送 MMS（带媒体）

Python：

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

Node.js：

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。

通过 Messaging Service 发送（推荐用于扩展）

使用 messagingServiceSid 替代 from——Twilio 会自动从你的号码池中选择最佳发送方。

Python：

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

Node.js：

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

追踪投递状态

Python：

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

Node.js：

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）。

响应字段

  • sid：消息标识符（SM...）
  • status：queued、sent、delivered、undelivered、failed
  • error_code：失败时填充
  • error_message：人类可读的描述
  • price：费用（投递后填充）
  • date_sent：UTC 时间戳

常见错误

  • 21211：无效的 to 号码 → 校验 E.164 格式
  • 21408：未开启向该地区发送的权限 → 在 Console 中启用地区权限
  • 21610：号码在阻止列表中（已退订）→ 不要重试，尊重退订
  • 30003：目的地不可达 → 运营商无法投递，可稍后重试
  • 30007：消息被判定为垃圾信息而过滤 → 检查内容与发送方信誉
  • 30034：消息来自未注册号码 → 完成 A2P 10DLC 注册，参见 twilio-compliance-onboarding
  • 30450：检测到短信泵送 → 消息被短信泵送保护拦截，参见 twilio-messaging-services

消息被过滤或拦截？

如果消息未能投递，请按顺序检查以下原因：

  1. 未注册发送方（错误 30034）——美国 10DLC 号码必须注册。参见 twilio-compliance-onboarding
  2. 垃圾信息过滤（错误 30007）——运营商标记了内容。检查：是否包含退订说明？是否避免使用 URL 缩短器？内容是否与注册的活动一致？
  3. 收件人已退订（错误 21610）——收件人回复了 STOP。不要重试。参见 twilio-compliance-traffic
  4. 地区权限被禁用（错误 21408）——在 Console > Messaging > Settings > Geo Permissions 中启用目标国家。参见 twilio-security-hardening
  5. 短信泵送（错误 30450）——检测到人为流量。通过 Global Safe List 将已知前缀加入白名单。参见 twilio-messaging-services
  6. 账户被暂停——在 Console 中查看账户状态通知。参见 twilio-account-setup

如需投递事件追踪，可设置 StatusCallbacks 或使用 twilio-debugging-observability。

限制

  • 必须使用 E.164 格式——from 和 to 都必须是 + 后接国家代码和号码
  • 试用账户不能向未验证号码发送——需升级为付费或先验证收件人号码
  • 不支持在美国、加拿大、澳大利亚以外发送 MMS——MMS 仅支持美/加/澳号码；国际富媒体请使用 WhatsApp
  • 单条消息不得超过 1600 字符——超长消息会自动拆分为多个分段（每段单独计费）
  • 没有 Messaging Service 就无法防止短信泵送——需通过 Messaging Services 启用短信泵送保护以防止人为流量膨胀。参见 twilio-messaging-services

后续步骤

  • 渠道概览与接入指南：twilio-messaging-overview
  • 接收入站短信与投递状态：twilio-messaging-webhooks
  • 大规模管理发送方池：twilio-messaging-services
  • 美国 A2P 流量合规：twilio-compliance-onboarding
  • 改用 WhatsApp 发送：twilio-whatsapp-send-message