技术咨询：如何使用Twilio创建WhatsApp的List message

一、前置准备 #

• 注册并登录Twilio控制台，获取账户SID和Auth Token（控制台首页直接可见）。
• 激活WhatsApp服务：在控制台左侧导航进入Messaging > Try it out > Send a WhatsApp message，获取沙盒号码（正式环境需申请认证号码）。
• 安装Twilio SDK（以Python为例）：执行命令 pip install twilio。
• （可选）准备公网可访问的Webhook地址：本地开发可使用ngrok等工具暴露端口，用于接收用户选择后的回调。

二、核心结构说明 #

WhatsApp列表消息的必填组成部分：

• Header：列表顶部标题（最多60字符）。
• Body：列表上方的说明文本（最多1024字符）。
• Action：包含触发列表的按钮文本，以及分组的sections：
  • 每个section有独立标题（最多24字符），可包含多个rows。
  • 每个row需设置唯一id（用户选择后Twilio会返回此ID）、title（最多24字符），可选description（最多72字符）。

三、发送List Message的代码实现 #

以Python为例，完整发送代码如下：

from twilio.rest import Client

# 替换为你的Twilio账户信息
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
client = Client(account_sid, auth_token)

# 构造列表消息并发送
message = client.messages.create(
    from_='whatsapp:+14155238886',  # 替换为你的Twilio沙盒/正式号码
    to='whatsapp:+8613XXXXXXXXX',   # 替换为目标用户的WhatsApp号码
    content={
        "type": "list",
        "list": {
            "header": {
                "type": "text",
                "text": "选择服务类别"
            },
            "body": {
                "text": "请从下方选项中挑选你需要的服务"
            },
            "action": {
                "button": "查看选项",
                "sections": [
                    {
                        "title": "生活服务",
                        "rows": [
                            {
                                "id": "service_1",
                                "title": "家政保洁",
                                "description": "专业上门清洁服务"
                            },
                            {
                                "id": "service_2",
                                "title": "快递代取",
                                "description": "帮你代收各类包裹"
                            }
                        ]
                    },
                    {
                        "title": "娱乐休闲",
                        "rows": [
                            {
                                "id": "ent_1",
                                "title": "电影购票",
                                "description": "最新影片在线选座"
                            },
                            {
                                "id": "ent_2",
                                "title": "景点门票",
                                "description": "热门景区折扣门票"
                            }
                        ]
                    }
                ]
            }
        }
    }
)

print(f"消息发送成功，SID: {message.sid}")

四、处理用户的列表选择 #

用户点击选项后，Twilio会向你设置的Webhook URL发送POST请求，携带用户选择的row.id（在Body字段）、用户号码（WaId字段）等信息。以下是Flask处理回调的示例：

from flask import Flask, request
from twilio.rest import Client

app = Flask(__name__)

# 初始化Twilio客户端
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
client = Client(account_sid, auth_token)

@app.route('/whatsapp-webhook', methods=['POST'])
def handle_webhook():
    # 获取回调参数
    selected_id = request.values.get('Body', '').strip()
    user_number = request.values.get('WaId', '')
    
    # 根据选择返回对应回复
    response_map = {
        "service_1": "你选择了家政保洁服务，请告知具体地址和时间，我们将安排人员上门。",
        "service_2": "快递代取服务已确认，请提供快递单号和取件地址。",
        "ent_1": "电影购票通道已开启，请回复你想看的影片名称。",
        "ent_2": "景点门票服务已激活，请回复你想去的景区名称。"
    }
    reply_text = response_map.get(selected_id, "抱歉，我无法识别你的选择，请重新操作。")
    
    # 发送回复
    client.messages.create(
        from_='whatsapp:+14155238886',
        body=reply_text,
        to=f'whatsapp:{user_number}'
    )
    
    return '', 200

if __name__ == '__main__':
    app.run(port=5000, debug=True)

设置Webhook：在Twilio控制台的WhatsApp沙盒设置中，将When a message comes in的URL改为你的公网地址（如https://xxx.ngrok.io/whatsapp-webhook），请求方法选POST。

五、测试与注意事项 #

• 测试环境：目标号码需先发送join 沙盒代码到Twilio沙盒号码，完成绑定。
• 字符限制：严格遵守各字段的长度限制，超出会导致发送失败。
• 正式环境：如需向非沙盒用户发送消息，需申请Twilio正式WhatsApp号码并完成业务认证。

内容的提问来源于stack exchange，提问作者Ahmed Abdelmohsen