如何使用 n8n 和 WAHA 构建一个自我托管的 WhatsApp 机器人

services:
  waha:
    # ... 现有的配置项

  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PORT=5678
      - N8N_protocol=https
      - WEBHOOK_URL=https://n8n.example.com/
      - GENERIC_TIMEZONE=UTC
    volumes:
      - ./n8n-data:/home/node/.n8n

请将n8n.example.com替换为您的实际域名。如果只是进行本地测试，可以将其设置为：

- N8N_HOST=localhost
- N8N_protocol=http
- WEBHOOK_URL=http://localhost:5678/

如果你想在没有服务器的情况下在笔记本电脑上测试Webhook，可以在另一个终端中运行ngrok http 5678，然后将ngrok提供的HTTPS地址设置为WEBHOOK_URL。n8n会使用这个URL来指示外部服务应该将数据发送到哪里；如果设置错误，Webhook就会收到404错误响应。

启动开发环境：

docker compose up -d

访问http://your-server:5678。在第一次访问时，n8n会引导你创建一个账户（需要输入电子邮件地址和密码）。之后的每次访问都需要进行登录操作。为了在生产环境中增加安全性，建议将n8n部署在反向代理后面，并设置允许列表或额外的认证机制——这些我们稍后会进行配置。

第5部分：在n8n中创建Webhook触发器

点击“创建工作流”，你会看到一个空白的编辑界面。

添加一个Webhook节点并进行配置：

• HTTP方法：POST

• 路径：whatsapp（这个路径会出现在URL中）

• 响应方式：立即响应

• 响应数据：以JSON格式发送第一条消息的数据

点击“监听测试事件”，n8n会显示两个URL：一个用于测试的URL，另一个用于正式使用的URL。请复制正式使用的URL，它的格式如下：

https://n8n.example.com/webhook/whatsapp

注意不要使用webhook-test这个URL——因为只有当编辑器处于打开状态时，这个URL才会被触发。你应该使用webhook这个URL。

第6部分：将WAHA与n8n连接起来

WAHA可以在发生任何WhatsApp事件时向Webhook发送数据。你需要指定这些数据应该被发送到哪个Webhook地址。

在WAHA的仪表板上，打开你的会话并设置Webhook URL。或者也可以通过API来设置：

curl -X PUT http://your-server:3000/api/sessions/default \
  -H "X-Api-Key: super-secret-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "webhooks": [
        {
          "url": "https://n8n.example.com/webhook/whatsapp",
          "events": ["message", "session.status"]
        }
      ]
    }
  }'

message事件会在每次收到新的WhatsApp消息时被触发。session.status事件则会在会话连接、断开或重新连接时被触发——这对于在机器人出现故障时发出警报非常有用。

进行测试吧。用另一部手机给你的机器人的WhatsApp账号发送一条消息，然后回到n8n编辑器中。一两秒钟后，Webhook节点就会显示接收到的事件数据。

事件数据的大致格式如下：

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "false_15555550123@c.us_3EB0...",
    "from": "15555550123@c.us",
    "body": "Hello",
    "timestamp": 1713801234,
    "fromMe": false
  }
}

所有你需要的信息都包含在payload字段中：消息的发送者(from)、发送的内容(body)以及消息发送的时间(timestamp)。

第7部分：构建第一个自动回复系统

仅仅能够接收用户输入的机器人是很无趣的。让我们让它也能做出回应吧。

你将构建一个简单的关键词路由系统：如果用户发送“hi”或“hello”，机器人会向他们打招呼；如果他们发送“price”，机器人就会发送价格信息；对于其他所有输入，系统都会采用默认的处理方式。

在Webhook节点之后，添加一个Switch节点。

配置Switch节点：

• 模式：表达式匹配

• 值：{{ $json.payload.body.toLowerCase().trim() }}

• 添加路由规则：

  • 规则1：如果输入等于“hi”——输出0

  • 规则2：如果输入等于“hello”——输出0

  • 规则3：如果输入等于“price”——输出1

  • 默认输出：2

在Switch节点之后，再添加三个HTTP请求节点，每个输出对应一个请求节点。

所有HTTP请求节点的配置都相同，唯一的区别在于发送的请求体内容：

• 方法：POST

• URL：http://waha:3000/api/sendText（在Docker网络中，可以通过服务名称访问WAHA；外部则需要使用完整的公共URL）

• 请求头信息：启用

  • X-Api-Key：super-secret-key-change-me

  • Content-Type：application/json

• 请求体内容：启用

  • 内容类型：JSON

  • 请求体内容：使用JSON格式发送

对于用于打招呼的节点，其JSON请求体内容如下：

{
  "session": "default",
  "chatId": "={{ $('Webhook').item.json.payload.from }}",
  "text": "嗨！我是这个机器人。如果想了解价格信息，请发送‘price’；如需其他帮助，也可以发送其他内容。”
}

对于用于提供价格信息的节点，其JSON请求体内容如下：

{
  "session": "default",
  "chatId": "={{ $('Webhook').item.json.payload.from }}",
  "text": "我们的套餐价格最低为49美元/月。如果想与人工客服沟通，请回复‘sales’。”
}

对于默认处理节点，其JSON请求体内容如下：

{
  "session": "default",
  "chatId": "={{ $('Webhook').item.json.payload.from }}",
  "text": "我没有听清你的请求。请尝试发送‘hi’或‘price’。”
}

其中{{{ ... }}这种语法是一种n8n表达式——在运行时，它会从之前的节点中获取相应的值。

将Switch节点的各个输出端与对应的HTTP请求节点连接起来。保存工作流程设置，然后点击右上角的“激活”按钮。

用任何手机发送“hi”给你的机器人，它应该会在一秒钟内做出回应。

恭喜你——你已经成功创建了一个完全运行在你自己基础设施上的WhatsApp机器人。

第8部分：第二个示例——主动发送预订确认信息

自动回复功能确实很有用，但主动向用户发送信息时，其价值才会真正得到体现。下面是一个新的工作流程示例：每当数据库中新增一条记录时，这个系统就会自动发送预订确认信息。

在n8n中创建第二个工作流。可以使用以下触发器之一：

• 定时触发器 — 每分钟检查数据库一次，以获取新的记录

• Webhook触发器 — 监听您的预订系统发送的通知

• 数据库触发器（适用于Postgres、MySQL、Supabase） — 实时响应数据表的插入操作

在这个示例中，使用定时触发器，设置每分钟检查一次数据库，然后使用Postgres的执行查询节点来读取尚未确认的预订信息：

SELECT id, customer_phone, service_name, booking_time
FROM bookings
WHERE confirmation_sent = false
LIMIT 20;

在Postgres节点之后，添加一个HTTP请求节点，该节点指向之前使用过的WAHA的sendText接口。请求内容如下：

{
  "session": "default",
  "chatId": "={{ $json.customer_phone }}@c.us",
  "text": "您好！您在{{ \)json.booking_time }}预约的{{ \(json.service_name }}服务已经确认。如需重新安排时间，请回复‘change’。”
}

最后，再添加一个Postgres节点，将这些预订状态标记为“已发送”：

UPDATE bookings
SET confirmation_sent = true, confirmation_sent_at = NOW()
WHERE id = {{ $json.id.;

激活这个工作流后，n8n会每分钟检查一次尚未确认的预订信息，通过WhatsApp发送确认通知，并将这些预订状态标记为“已完成”。

这种模式具有通用性。您可以将SQL语句替换为调用Shopify来获取订单确认信息，或者使用Stripe来处理收款通知，再或者利用Calendly来发送预约提醒。不过，WhatsApp相关的部分保持不变——只有数据来源会发生变化。

第9部分：投入生产环境

上述设置虽然可以正常使用，但尚未达到生产环境的要求。在将真实客户的数据接入之前，还需要进行以下优化。

1. 将所有服务置于HTTPS环境中

切勿直接通过普通的HTTP协议暴露n8n或WAHA服务。应在前面添加反向代理服务器。Caddy是一个非常方便的选择，因为它能自动处理Let’s Encrypt证书的配置。

一个简单的Caddyfile配置文件如下：

n8n.example.com {
    reverse_proxy n8n:5678
}

waha.example.com {
    reverse_proxy waha:3000
}

可以在同一个Docker Compose环境中将Caddy作为单独的服务运行。TLS证书会自动生成并更新。

2. 更换API密钥

切勿将super-secret-key-change-me这样的临时密钥用于生产环境。请生成一个真正的API密钥：

openssl rand -hex 32

将新生成的密钥保存到.env文件中，在docker-compose.yml文件中将其设置为${WHATSAPP_API_KEY}，同时确保.env文件不会被包含在.gitignore列表中。

3>限制对外发送消息的频率

WhatsApp会封禁那些频繁且快速发送大量消息的账户。对于新注册的账户来说，每分钟发送消息的数量应控制在20条以下。如果需要批量回复客户，可以在每次发送消息之前添加一个n8n的等待节点，或者通过一个自定义函数节点来控制消息发送的间隔时间。

4. 使用队列模式扩展n8n系统

默认情况下，n8n会在单个进程中运行所有任务。对于处理量较小的场景来说，这种配置完全适用。但当需要提高处理效率时，可以切换到队列模式：

• 添加一个Redis容器。

• 运行一个n8n主容器（用于提供Web界面和接收Webhook请求）。

• 运行一个或多个n8n-worker容器，这些容器会从队列中获取任务并执行相应操作。

关于队列模式的详细信息，请参阅docs.n8n.io/hosting/scaling/queue-mode/。配置队列模式需要设置两个环境变量：EXECUTIONS_MODE=queue和QUEUE_BULL_REDIS_HOST=redis），这样就能将接收到的Webhook请求与工作流程的执行过程分离开来。Webhook会立即作出响应，而后台的worker进程则会继续处理队列中的任务。

5. 监控会话状态

WhatsApp Web会话状态可能会突然发生变化——比如手机断开连接、WhatsApp更新了安全令牌，或者你的服务器重启了。因此，必须及时发现这些变化。

在WAHA系统中，订阅session.status这个Webhook事件。当会话状态变为FAILED或STOPPED时，立即将相关信息转发给n8n工作流程，让该流程在Slack上发布公告、发送电子邮件或通知你。越早发现问题，就越快能够恢复正常运行。

为了了解系统的整体运行状况，可以在WAHA系统中访问GET /api/sessions/default这个接口。如果系统显示“WORKING”，那就说明一切正常；否则就会触发警报。

6. 备份会话数据

waha-sessions目录中保存了用户的登录状态信息。如果这些数据丢失，用户就需要重新扫描QR码进行登录——而有时候可能找不到那部手机了。因此，建议每晚自动备份这些数据。使用tar和rclone工具将数据备份到支持S3协议的存储系统中，这样就足够了。