用 Python 打造的经济实惠 WhatsApp AI 聊天机器人：每月仅需 6 美元

只需每月 6 美元（WaSenderAPI 订阅）加上 Google Gemini API 的免费层级（每月 1500 次请求），即可创建一个由 Google Gemini AI 提供支持的强大 WhatsApp 聊天机器人。该基于 Python 的解决方案使用 Flask 通过 WaSenderAPI Webhook 处理传入消息，并利用 Gemini 先进的 AI 功能生成智能、对话式的响应。

💰 高性价比方案

• WaSenderAPI：仅需每月 6 美元即可实现 WhatsApp 集成
• Gemini AI：免费层级，每月 1500 次请求
• 托管：可在本地运行或选择低成本云服务
• 无需支付 WhatsApp Business API 费用：使用 WaSenderAPI 作为经济实惠的替代方案

🔥 核心功能

• WhatsApp 集成：通过 WaSenderAPI 接收和发送消息
• AI 驱动的回复：使用 Google Gemini AI 生成智能回复
• 媒体支持：支持文本、图片、音频、视频和文档消息
• 智能消息拆分：自动将长回复拆分为多条消息，提升可读性
• 可定制的 AI 角色：通过简单的 JSON 配置调整机器人的个性与行为
• 对话历史：保持消息间的上下文，实现自然流畅的对话
• 错误处理：强大的日志记录和错误管理机制，确保稳定运行
• 易于配置：通过环境变量进行简单设置

📁 项目结构

/whatsapp-python-chatbot/
├── script.py         # 主 Flask 应用程序及机器人逻辑
├── requirements.txt  # Python 依赖项
├── .env              # 环境变量（API 密钥等）
├── persona.json      # 可定制的 AI 角色设置
└── README.md         # 当前文件

🚀 设置与安装

1. 克隆仓库（如适用）或按照说明创建文件。

2. 建议创建虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # Windows 用户请使用 `venv\Scripts\activate`
   

3. 安装依赖项：

   pip3 install -r requirements.txt
   

4. 配置环境变量： 在项目根目录下创建 .env 文件，复制下方示例内容。请勿将包含敏感密钥的 .env 文件提交到版本控制中。

   GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"  # 免费层级：每月 1500 次请求
   WASENDER_API_TOKEN="YOUR_WASENDER_API_TOKEN_HERE"  # 每月 6 美元订阅
   # 可选：若在 script.py 中更改了端口，请在此处更新以供 ngrok 或其他服务使用
   # FLASK_RUN_PORT=5000
   

   将占位符替换为您的实际 API 密钥：

   • GEMINI_API_KEY：您的 Gemini API 密钥（提供免费层级）
   • WASENDER_API_TOKEN：您从 WaSenderAPI 获取的 API 令牌（每月 6 美元订阅）

🏃‍♂️ 运行应用程序

1. 开发模式（使用 Flask 内置服务器）

适用于本地开发和测试。

python3 script.py

应用程序默认将在 http://0.0.0.0:5001/ 上运行。

2. 使用 ngrok 测试 Webhook

WaSenderAPI 需要将 Webhook 事件（传入消息）发送到一个可公开访问的 URL。如果您在本地运行 Flask 应用程序，ngrok 可以将您的本地服务器暴露到互联网上。

a. 安装 ngrok（如尚未安装）：https://ngrok.com/。

b. 启动 ngrok，将其转发到 Flask 应用的端口（例如 5001）：

ngrok http 5001

c. ngrok 将为您提供一个公共 URL（例如 https://xxxx-xx-xxx-xxx-xx.ngrok-free.app）。

d. 在 WaSenderAPI 控制台中将此 ngrok URL 配置为您的 Webhook URL，用于已连接的设备/会话。请务必添加 /webhook 路径（例如 https://xxxx-xx-xxx-xxx-xx.ngrok-free.app/webhook）。

3. 生产部署（使用 Gunicorn）

在生产环境中，建议使用 Gunicorn 等专业的 WSGI 服务器，而非 Flask 自带的开发服务器。

a. 安装 Gunicorn：

pip3 install gunicorn

b. 使用 Gunicorn 运行应用程序： 如果文件名或 Flask 应用实例名称有更改，请将 script:app 替换为 your_filename:your_flask_app_instance_name。

gunicorn --workers 4 --bind 0.0.0.0:5001 script:app

• --workers 4：根据您的服务器 CPU 核心数调整工作进程数量（常见起始值为 2 * num_cores + 1）。
• --bind 0.0.0.0:5001：指定 Gunicorn 监听的地址和端口。

c. 反向代理（推荐）： 在典型的生产环境中，您会将 Gunicorn 部署在 Nginx 或 Apache 等反向代理之后。反向代理负责处理传入的 HTTPS 请求、SSL 终止、静态文件服务（如有），并将请求转发至 Gunicorn。

🔄 WaSenderAPI Webhook 配置

• 登录您的 WaSenderAPI 控制台。
• 导航到会话管理部分。
• 将您的手机号码连接到会话。
• 找到设置或更新 Webhook URL 的选项。
• 输入您的 Flask 应用程序 /webhook 端点所运行的可公开访问的 URL（例如开发阶段的 ngrok URL，或生产服务器的 URL）。
• 确保仅选择 message_upsert。
• 保存更改。

📝 自定义机器人个性

聊天机器人包含一个可定制的基础提示，用于定义 AI 的角色和行为。编辑 persona.json 文件，以调整 Gemini 对消息的响应方式，使机器人更正式、更随意、更具信息性或更富对话感，从而满足您的具体使用场景需求。

{
  "name": "WhatsApp 助手",
  "base_prompt": "您是一位在 WhatsApp 聊天中回答问题的乐于助人且简洁的 AI 助手……",
  "description": "您是一位乐于助人的 WhatsApp 助手。请保持回复简洁……"
}

📊 日志记录与错误处理

• 应用程序使用 Python 内置的 logging 模块。
• 默认情况下，日志会打印到控制台。
• 日志格式为：%(asctime)s - %(levelname)s - %(message)s。
• 未处理的异常也会被记录。
• 生产环境注意事项：建议将日志写入文件，使用集中式日志服务（如 ELK 堆栈、Sentry、Datadog），并实施日志轮转。

📚 WaSenderAPI 文档

请参阅官方 WaSenderAPI 文档，获取关于 API 端点、请求/响应格式以及 Webhook 详情的最新信息：https://wasenderapi.com/api-docs

💡 为什么选择此方案？

这款聊天机器人提供了一种极具成本效益的方式，让您无需承担通常与 WhatsApp Business API 相关的高昂费用，即可部署一款 AI 驱动的 WhatsApp 机器人。通过结合 WaSenderAPI 每月 6 美元的经济实惠订阅和 Google 免费的 Gemini API 层级，您将以远低于企业级解决方案的成本获得一个功能强大且可定制的聊天机器人解决方案。

whatsapp-python-chatbot 快速上手指南

本指南帮助中国开发者快速部署基于 Python 和 Google Gemini AI 的低成本 WhatsApp 聊天机器人。该方案利用 WaSenderAPI（$6/月）替代昂贵的官方 Business API，并结合 Gemini 免费额度，实现智能对话功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • WaSenderAPI 账号：需订阅基础套餐（约 $6/月），获取 API Token。
  • Google Gemini API Key：注册 Google AI Studio 获取免费 API Key（每月 1500 次请求额度）。
  • 网络环境：由于涉及 Google API 和 WaSenderAPI，请确保服务器或本地环境具备访问国际互联网的能力。
  • 内网穿透工具（开发用）：推荐安装 ngrok，用于将本地服务暴露给公网以接收 WhatsApp webhook 回调。

安装步骤

1. 获取代码与创建虚拟环境

克隆项目或手动创建文件结构后，建议创建独立的 Python 虚拟环境以避免依赖冲突。

python3 -m venv venv
source venv/bin/activate  # Windows 用户请使用：venv\Scripts\activate

2. 安装依赖

使用 pip 安装所需库。国内用户如遇下载缓慢，可临时切换至清华或阿里镜像源。

# 使用默认源
pip3 install -r requirements.txt

# 或使用国内镜像加速（推荐）
pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置环境变量

在项目根目录创建 .env 文件，填入您的 API 密钥。切勿将此文件提交到版本控制系统。

GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"
WASENDER_API_TOKEN="YOUR_WASENDER_API_TOKEN_HERE"
# FLASK_RUN_PORT=5001

• GEMINI_API_KEY: 替换为您的 Google Gemini API Key。
• WASENDER_API_TOKEN: 替换为您的 WaSenderAPI Token。

4. 自定义机器人人设（可选）

编辑 persona.json 文件，调整机器人的性格、语气和行为模式。

{
  "name": "WhatsApp Assistant",
  "base_prompt": "You are a helpful and concise AI assistant replying in a WhatsApp chat...",
  "description": "You are a helpful WhatsApp assistant. Keep your responses concise..."
}

基本使用

1. 启动本地服务

运行主脚本启动 Flask 应用，默认监听端口通常为 5001。

python3 script.py

2. 配置公网回调（Webhook）

WaSenderAPI 需要将消息推送到公网地址。若在本地开发，需使用 ngrok 进行穿透。

启动 ngrok：

ngrok http 5001

获取并配置 Webhook URL：

1. 复制 ngrok 生成的公网地址（例如：https://xxxx-xx-xxx-xxx-xx.ngrok-free.app）。
2. 登录 WaSenderAPI 控制台，进入会话管理页面。
3. 连接您的手机号码到对应会话。
4. 设置 Webhook URL 为：<ngrok 地址>/webhook（务必加上 /webhook 后缀）。
5. 重要：在事件订阅选项中，仅勾选 message_upsert。
6. 保存设置。

3. 测试运行

完成上述配置后，向绑定的 WhatsApp 号码发送任意消息。机器人将通过 Gemini AI 处理上下文并返回智能回复。

4. 生产环境部署（可选）

正式部署时，建议使用 gunicorn 替代 Flask 内置服务器，并配合 Nginx 反向代理。

# 安装 gunicorn
pip3 install gunicorn

# 启动服务（4 个工作进程，监听 5001 端口）
gunicorn --workers 4 --bind 0.0.0.0:5001 script:app