🤖 WhatsApp AI BOT
一个由Spring AI、OpenAI的GPT-4和模型上下文协议（MCP）支持的智能WhatsApp聊天机器人，用于动态工具管理和员工数据查询。
🌟 特性
- 智能对话 -使用OpenAI的GPT-4模型和上下文感知的AI驱动响应
- 对话记忆 -维护聊天历史记录，以便进行连贯的多回合对话
- 工具集成 -通过MCP服务器动态调用工具以查找员工信息
- 实时消息 -通过Meta的Graph API实现双向WhatsApp集成
- Webhook验证 -使用ngrok隧道支持进行安全的Meta webhook验证
- 模块化架构 -与专用MCP服务器模块分离的问题
- MCP检查员 -内置调试和工具检查界面
- 生产就绪 -与ngrok一起部署，以便在开发过程中为公众提供无障碍服务
🏗️ 建筑
┌─────────────────────────────────────────────────────────────────┐
│ WhatsApp Users │
└────────────────────┬────────────────────────────────────────────┘
│
│ Messages
▼
┌─────────────────────────────────────────────────────────────────┐
│ Meta WhatsApp API │
│ (Webhook for incoming messages) │
└────────────────────┬────────────────────────────────────────────┘
│
ngrok Tunnel (Public URL)
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ WhatsApp Bot Service (Port 8080) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ WebhookController │ │
│ │ • Receives messages from Meta API │ │
│ │ • Verifies webhook integrity │ │
│ └────────┬─────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────▼─────────────────────────────────────────────────┐ │
│ │ AIAgent │ │
│ │ • Maintains conversation memory │ │
│ │ • Calls MCP tools dynamically │ │
│ │ • Generates intelligent responses via GPT-4 │ │
│ └────────┬─────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────▼─────────────────────────────────────────────────┐ │
│ │ WhatsAppService │ │
│ │ • Formats and sends messages back via Meta API │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────────────┘
│
│ HTTP Calls
▼
┌──────────────────────────────────────────────────────────────────┐
│ MCP Server Service (Port 8989) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ MCPTools │ │
│ │ • getEmployee(name) - Retrieve employee info │ │
│ │ • getAllEmployees() - List all employees │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ MCP Inspector (Debugging Interface) │ │
│ │ • Tool inspection and testing │ │
│ │ • Connection monitoring │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘📋 项目结构
whatsapp_bot/
├── whatsapp_bot/ # Main bot service (Port 8080)
│ ├── src/main/java/ma/youhad/whatsapp_bot/
│ │ ├── agents/
│ │ │ └── AIAgent.java # Core AI logic with MCP integration
│ │ ├── service/
│ │ │ └── WhatsAppService.java # Meta API integration
│ │ ├── web/
│ │ │ └── WebhookController.java # Webhook endpoints
│ │ └── WhatsappBotApplication.java
│ ├── src/main/resources/
│ │ └── application.properties # Bot configuration
│ └── pom.xml
│
├── mcp_server/ # Separate MCP Server (Port 8989)
│ ├── src/main/java/ma/youhad/mcp_server/
│ │ ├── tools/
│ │ │ ├── MCPTools.java # Tool definitions
│ │ │ └── Employee.java # Data model
│ │ └── McpServerApplication.java
│ ├── src/main/resources/
│ │ └── application.properties # MCP configuration
│ └── pom.xml
│
├── .gitignore
├── node_modules/
├── pom.xml # Parent POM
└── README.md🚀 快速开始
先决条件
- Java 17+
- Maven 3.8+
- Node.js 16+（用于MCP检查器）
- OpenAI API密钥
- 使用WhatsApp Business API访问的Meta Business帐户
- WhatsApp商务电话号码ID
- Webhook验证令牌
安装
- 克隆存储库
git clone https://github.com/youhad/whatsapp_bot.git
cd whatsapp_bot- 设置环境变量
# Windows (PowerShell)
$env:OPENAI_API_KEY = "your_openai_api_key"
$env:WHATSAPP_ACCESS_TOKEN = "your_meta_access_token"
$env:WHATSAPP_VERIFY_TOKEN = "your_webhook_verification_token"
# macOS/Linux
export OPENAI_API_KEY=your_openai_api_key
export WHATSAPP_ACCESS_TOKEN=your_meta_access_token
export WHATSAPP_VERIFY_TOKEN=your_webhook_verification_token- 启动MCP服务器（终端1）
cd mcp_server
mvn spring-boot:runMCP服务器将启动 http://localhost:8989
- 启动MCP检查器（端子2）-可选，但建议
npx @modelcontextprotocol/inspector http://localhost:8989/mcp这将为测试工具打开一个交互式调试界面
- 访问地址： http://localhost:6274 （带身份验证令牌）
- 启动主机器人服务（终端3）
cd whatsapp_bot
mvn spring-boot:run机器人服务将于启动 http://localhost:8080
- 使用ngrok暴露本地服务器（终端4）
ngrok http 8080这将生成一个公共URL，如下所示： https://your-unique-id.ngrok-free.dev
- 在Meta Dashboard中配置Webhook
- 前往元应用仪表板>WhatsApp>配置 - 设置回调URL: https://your-unique-id.ngrok-free.dev/webhook - 验证令牌：使用来自的相同令牌 WHATSAPP_VERIFY_TOKEN - 订阅webhook字段： messages, message_status
🔧 配置
机器人服务(whatsapp_bot/application.properties)
spring.application.name=whatsapp_bot
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o
# MCP Server Connection
spring.ai.mcp.client.streamable-http.connections.mcprh.url=http://localhost:8989
# WhatsApp Configuration
whatsapp.access.token=${WHATSAPP_ACCESS_TOKEN}
whatsapp.phone.number.id=806864275852077
whatsapp.verify.token=${WHATSAPP_VERIFY_TOKEN}
server.port=8080MCP服务器(mcp_server/application.properties)
spring.application.name=mcp_server
spring.ai.mcp.server.protocol=streamable
spring.ai.mcp.server.name=RH-MCP-SERVER
server.port=8989📡 API终点
Webhook端点
GET/webhook -Webhook验证
curl "http://localhost:8080/webhook?hub.mode=subscribe&hub.challenge=test123&hub.verify_token=YOUR_VERIFY_TOKEN"POST/webhook -接收传入消息
- Meta API自动触发
- 处理短信并生成人工智能响应
- 成功时返回HTTP 200
💬 运作原理
- 用户发送消息 通过WhatsApp
- Meta API 将webhook发送到
/webhook经由ngrok隧道的终点 - Webhook控制器 接收并解析消息
- A代理人 使用以下方式处理查询：
- 对话记忆（维护消息之间的上下文） - MCP工具调用（如果需要，获取员工数据） - GPT-4模型（生成智能响应）
- WhatsAppService 通过Meta Graph API发回响应
- 用户收到 人工智能实时生成回复
🛠️ 可用工具
MCP服务器为AI代理提供以下工具：
getEmployee（姓名）
检索特定员工的信息。
参数：
name（string）：员工姓名
例子：
User: "Tell me about Hassan"
AI: [Calls getEmployee("Hassan")]
Response: "Hassan has a salary of 1,274 and 3 years of seniority."获取所有员工（）
列出所有员工及其信息。
例子：
User: "Who are the employees?"
AI: [Calls getAllEmployees()]
Response: "We have Hassan (salary: 1,274, seniority: 3), Jacklin (salary: 6,789, seniority: 8), and Ahmed (salary: 9,234, seniority: 23)."🔍 使用MCP检查器进行调试
MCP检查器提供了一个web界面来测试和调试您的工具：
- 启动MCP检查器：
npx @modelcontextprotocol/inspector http://localhost:8989/mcp - 在浏览器中打开提供的URL
- 使用 工具 选项卡指向：
- 列出可用工具 - 使用参数测试单个工具 - 查看工具描述和模式
- 实时监控工具调用和响应
- 检查连接状态和服务器通知
特征：
- 工具检查和参数验证
- 直接执行工具进行测试
- 连接历史和日志记录
- 服务器通知监控
📊 Webhook验证流程
webhook验证可确保与Meta的安全通信：
Meta Dashboard → ngrok → WhatsApp Bot (Port 8080)
↓
WebhookController
↓
Verify Token Match?
↓
YES: Return challenge token (HTTP 200)
NO: Return error (HTTP 403)🔐 安全
- 敏感凭据的环境变量（API密钥、令牌）
- 对所有请求进行元webhook令牌验证
- WhatsApp API呼叫的承载令牌身份验证
- 消息内容的输入验证和JSON转义
- 用于调试的错误处理和日志记录
- ngrok为开发提供加密隧道
📝 系统提示
AI代理按照以下系统指令进行操作：
你是一个有用的WhatsApp机器人助手。根据提供的上下文回答用户问题。如果你没有足够的上下文来准确回答，礼貌地让用户知道你需要更多的信息，而不是猜测。
📦 依赖项
主机器人服务
- 弹簧靴3.x
- Spring AI（OpenAI集成）
- Spring AI社区MCP客户端
- 项目反应器（反应流）
- Jackson（JSON处理）
MCP服务器
- 弹簧靴3.x
- Spring AI社区MCP服务器
- Java记录（数据模型）
开发工具
- MCP检查器（调试接口）
- ngrok（webhooks隧道）
- Maven（构建管理）
🧪 测试
测试Webhook验证
curl -X GET "http://localhost:8080/webhook?hub.mode=subscribe&hub.challenge=test_challenge&hub.verify_token=YOUR_VERIFY_TOKEN"预期响应：
200 OK
test_challenge手动消息模拟
使用Postman或curl对示例webhook进行POST：
curl -X POST http://localhost:8080/webhook \
-H "Content-Type: application/json" \
-d '{
"entry": [{
"changes": [{
"value": {
"messages": [{
"from": "212696376120",
"type": "text",
"text": {"body": "Tell me about Hassan"}
}]
}
}]
}]
}'通过检查员测试MCP工具
- 打开MCP检查器
http://localhost:6274 - 导航至 工具 标签
- 选择
getEmployee或getAllEmployees - 带参数测试或无参数运行
- 查看结果和执行时间
🐛 故障排除
| 问题 | 解决方案 |
|---|---|
| MCP服务器连接被拒绝 | 确保MCP服务器在端口8989上运行： mvn spring-boot:run |
| Webhook未收到消息 | 验证ngrok是否正在运行，以及Meta仪表板中是否配置了URL |
| “验证令牌不匹配” | 检查 WHATSAPP_VERIFY_TOKEN 匹配Meta仪表板配置 |
| OpenAI API错误 | 验证 OPENAI_API_KEY 已设置且有效 |
| MCP检查器连接问题 | 清除浏览器缓存并重新启动检查器 |
| 未发送邮件 | 检查 WHATSAPP_ACCESS_TOKEN 和 whatsapp.phone.number.id |
| 重复响应 | 在Meta仪表板中检查多个webhook订阅 |
🚢 部署
发展
- 使用ngrok隧道在当地运行
- 使用MCP检查器进行调试
- 监控日志中的错误
生产
- 将机器人服务部署到云平台（AWS、Azure、GCP）
- 在同一网络上或公开部署MCP服务器
- 将Meta仪表板中的webhook URL更新到生产端点
- 对所有凭据使用环境变量
- 启用正确的日志记录和监控
- 为HTTPS设置SSL/TLS证书
机器人交互示例
以下GIF演示了消息流、使用其内部工具的AI以及在WhatsApp上响应的机器人。
📚 资源
🤝 贡献
欢迎投稿！请按照以下步骤操作：
📄 许可证
该项目根据麻省理工学院许可证获得许可-
✨ 未来的增强功能
- 员工数据的数据库集成
- 支持媒体消息（图像、文档）
- 多语言支持
- 速率限制和使用分析
- 消息加密
👨💻 作者
阿尤布·尤哈德
- github： @你有08
- 电子邮件：ayoubyouhad79@gmail.com
______________________________________________________________________
内置于❤️ 使用Spring AI、OpenAI和模型上下文协议