基于Twilio和Flask的WhatsApp消息回复功能故障排查

错误码含义对应 #

• 30008（未知错误）：Twilio无法成功建立到你的Webhook端点的连接，属于网络层面的访问失败
• 11200（请求失败）：Twilio能发起请求但无法完成交互，通常是SSL证书问题、响应格式错误或请求超时导致

具体排查与修复步骤 #

1. 网络准入规则检查 #

• EC2安全组配置：必须开放入站端口8080给Twilio的IP段（或临时开放0.0.0.0/0用于测试）。如果安全组仅允许你的本地IP访问，Twilio的服务器将无法触达你的Flask应用。
• EC2实例防火墙：检查系统层面的防火墙（如ufw、iptables）是否拦截8080端口流量。执行ufw status查看规则，若未开放则添加：

  ufw allow 8080/tcp
  

2. 强制HTTPS要求处理 #

Twilio的WhatsApp Webhook仅支持HTTPS协议，不接受HTTP请求：

• 为你的域名配置受信任的SSL证书（如Let's Encrypt免费证书），确保https://<domain_name>:8080/whatsapp能正常访问，且证书无警告。自签名证书会被Twilio拒绝。
• 推荐用Nginx做反向代理：将443端口的HTTPS请求转发到Flask的8080端口，这样Twilio可访问标准HTTPS端口（无需带8080后缀），配置示例：

  server {
      listen 443 ssl;
      server_name your-domain.com;
      ssl_certificate /path/to/cert.pem;
      ssl_certificate_key /path/to/key.pem;
  
      location /whatsapp {
          proxy_pass http://localhost:8080/whatsapp;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
      }
  }
  

3. Flask应用响应格式验证 #

Twilio要求Webhook返回标准Twiml XML格式，且路由需支持POST请求：

• 确保视图函数返回正确的Twiml，并设置Content-Type为application/xml：

  from flask import Flask, request, make_response
  from twilio.twiml.messaging_response import MessagingResponse
  
  app = Flask(__name__)
  
  @app.route('/whatsapp', methods=['POST'])  # 必须允许POST请求
  def whatsapp_reply():
      resp = MessagingResponse()
      resp.message('这是自动回复内容')
      return make_response(str(resp), 200, {'Content-Type': 'application/xml'})
  
  if __name__ == '__main__':
      app.run(host='0.0.0.0', port=8080)  # 监听所有网卡，仅监听127.0.0.1会导致外部无法访问
  

• 若返回JSON、普通文本或非Twiml格式，Twilio会判定响应无效，触发11200错误。

4. 沙箱配置正确性校验 #

• Webhook URL必须是完整的HTTPS地址，例如https://your-domain.com/whatsapp（用Nginx反向代理时）或https://your-domain.com:8080/whatsapp（直接用Flask+SSL时）。
• 确认沙箱的"收到消息时"Webhook方法设置为POST（Twilio默认值，勿改为GET）。

5. 请求到达验证 #

在Flask应用中添加日志，确认Twilio的请求是否到达：

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.route('/whatsapp', methods=['POST'])
def whatsapp_reply():
    logger.info(f"请求头：{request.headers}")
    logger.info(f"请求体：{request.form}")
    # 回复逻辑

• 若日志无Twilio请求记录：排查网络连通性问题；若有记录但返回错误：检查响应格式或SSL配置。

内容的提问来源于stack exchange，提问作者Matheus Farias