使用说明

🤖 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:run
```
MCP服务器将启动 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=8080

MCP服务器(`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和模型上下文协议