---

name: twilio-communications description: "使用 Twilio 构建通信功能：短信消息、语音通话、WhatsApp Business API 和用户验证（2FA）。涵盖从简单通知到复杂 IVR 系统和多渠道认证的完整范围。" risk: unknown source: vibeship-spawner-skills (Apache 2.0) date_added: 2026-02-27

Twilio 通信

使用 Twilio 构建通信功能：短信消息、语音通话、WhatsApp Business API 和用户验证（2FA）。涵盖从简单通知到复杂 IVR 系统和多渠道认证的完整范围。重点关注合规性、速率限制和错误处理。

模式

短信发送模式

使用 Twilio 发送短信的基本模式。处理基础功能：电话号码格式化、消息投递和投递状态回调。

关键注意事项：

• 电话号码必须使用 E.164 格式（+1234567890）
• 默认速率限制：每秒 80 条消息（MPS）
• 超过 160 个字符的消息会被拆分（且费用更高）
• 运营商过滤可能会阻止消息（尤其是发往美国号码的）

何时使用：向用户发送通知、事务性消息（订单确认、发货通知）、提醒和警报

from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
import os
import re

class TwilioSMS:
    """
    带有适当错误处理和验证的短信发送。
    """

    def __init__(self):
        self.client = Client(
            os.environ["TWILIO_ACCOUNT_SID"],
            os.environ["TWILIO_AUTH_TOKEN"]
        )
        self.from_number = os.environ["TWILIO_PHONE_NUMBER"]

    def validate_e164(self, phone: str) -> bool:
        """验证电话号码是否为 E.164 格式。"""
        pattern = r'^\+[1-9]\d{1,14}$'
        return bool(re.match(pattern, phone))

    def send_sms(
        self,
        to: str,
        body: str,
        status_callback: str = None
    ) -> dict:
        """
        发送短信。

        Args:
            to: E.164 格式的收件人电话号码
            body: 消息文本（160 字符 = 1 段）
            status_callback: 投递状态 webhook URL

        Returns:
            消息 SID 和状态
        """
        # 验证电话号码格式
        if not self.validate_e164(to):
            return {
                "success": False,
                "error": "Phone number must be in E.164 format (+1234567890)"
            }

        # 检查消息长度（警告分段）
        segment_count = (len(body) + 159) // 160
        if segment_count > 1:
            print(f"Warning: Message will be sent as {segment_count} segments")

        try:
            message = self.client.messages.create(
                to=to,
                from_=self.from_number,
                body=body,
                status_callback=status_callback
            )

            return {
                "success": True,
                "message_sid": message.sid,
                "status": message.status,
                "segments": segment_count
            }

        except TwilioRestException as e:
            return self._handle_error(e)

    def _handle_error(self, error: TwilioRestException) -> dict:
        """处理 Twilio 特定错误。"""
        error_handlers = {
            21610: "收件人已退订。他们必须回复 START。",
            21614: "无效的收件人电话号码格式。",
            21211: "发件人电话号码无效。",
            30003: "电话不可达（关机、飞行模式、无信号）。",
            30005: "未知目的地（无效号码或固定电话）。",
            30006: "固定电话或不可达运营商。",
            30429: "超出速率限制。实现指数退避。",
        }

        return {
            "success": False,
            "error_code": error.code,
            "error": error_handlers.get(error.code, error.msg),
            "details": str(error)
        }

# 使用示例
sms = TwilioSMS()
result = sms.send_sms(
    to="+14155551234",
    body="Your order #1234 has shipped!",
    status_callback="https://your-app.com/webhooks/twilio/status"
)

反模式

• 发送前不验证 E.164 格式
• 在代码中硬编码 Twilio 凭据
• 忽略投递状态回调
• 不处理退订（21610）错误

Twilio Verify 模式（2FA/OTP）

使用 Twilio Verify 进行电话号码验证和双因素认证。处理代码生成、投递、速率限制和欺诈防护。

相比自建 OTP 的关键优势：

• Twilio 管理代码生成和过期
• 内置欺诈防护（已为客户节省 8200 万美元以上，阻止 7.47 亿次尝试）
• 自动处理速率限制
• 多渠道：短信、语音、邮件、推送、WhatsApp

Google 发现短信 2FA 可阻止"100% 的自动化机器人、96% 的批量钓鱼攻击和 76% 的定向攻击。"

何时使用：注册时的用户电话号码验证、双因素认证（2FA）、密码重置验证