用途:当用户向你的 Twilio 号码发消息(入站)或出站消息投递状态变化(状态回调)时,Twilio 会向你的服务器发送 POST Webhook。服务器可返回 TwiML 进行回复,或返回 204 仅确认不回复。该模式在 SMS、MMS、WhatsApp 和 RCS 上通用。
前置条件:需 Twilio 账户及配置了 Webhook URL 的可发消息发送方;公网可访问的端点(本地开发可用 ngrok http 5000);需要 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN;SDK 安装命令为 pip install twilio flask 或 npm install twilio express。
主要能力:在 Console 的 Phone Numbers > Active Numbers 中设置入站 Webhook;也可通过 API 更新号码的 sms_url/smsUrl 与 sms_method/smsMethod,WhatsApp 和 RCS 的 Webhook 在发送方上配置。入站参数包括 MessageSid、From、To、Body、NumMedia、MediaUrl0、MediaContentType0,可据此处理媒体附件。出站消息可通过 status_callback/statusCallback 设置状态回调,状态流转为 queued → sent → delivered(或 undelivered/failed),回调参数含 MessageSid、MessageStatus、ErrorCode、ErrorMessage。
安全:Body 属不可信外部输入,传入 LLM 时必须作为用户输入隔离,禁止直接拼入系统提示词。生产环境应使用 X-Twilio-Signature 校验来源(签名校验仅确认来源,不代表内容安全)。
限制:Webhook 响应不得超过 15 秒,超时 Twilio 会重试;回复须用 text/xml 的 TwiML,状态回调返回 204;ngrok 重启后 URL 会变化,持久测试需用稳定隧道;状态回调为尽力而为,delivered 依赖运营商确认。常见错误 11200 表示 Twilio 无法访问 Webhook URL,需检查可达性、DNS、防火墙和 SSL 证书。本地快速上手示例省略了签名校验,生产必须补充。