Bạn đang vận hành một hệ thống backend và muốn biến WhatsApp thành kênh giao tiếp thông minh, không phải chatbot kịch bản cứng nhắc mà là một agent AI thật sự? Hướng dẫn kết nối OpenClaw với WhatsApp dưới đây sẽ đi thẳng vào kỹ thuật: từ khởi tạo App trên Meta Dashboard, cấu hình Webhook, đến xây dựng luồng Trigger–Process–Output hoàn chỉnh. Không lý thuyết vòng vo, chỉ có các bước bạn có thể thực thi ngay hôm nay.
Tiềm năng tự động hóa khi tích hợp OpenClaw cùng WhatsApp
Trước khi bắt tay vào cấu hình, cần hiểu rõ tại sao tích hợp này lại đáng giá, đặc biệt với developer đang xây sản phẩm B2B hoặc chủ doanh nghiệp muốn mở rộng ra thị trường quốc tế.
- Nâng cấp dịch vụ tương tác đa quốc gia: WhatsApp hiện có hơn 2 tỷ người dùng tại hơn 180 quốc gia. Khi kết hợp với OpenClaw, vốn được thiết kế để orchestrate các LLM như Gemini hay Claude, bạn sẽ có một agent có khả năng hiểu và phản hồi tự nhiên bằng tiếng Anh, Tây Ban Nha, Ả Rập hay bất kỳ ngôn ngữ nào khác mà không cần viết thêm một dòng logic phân nhánh nào.
- Thông báo và cảnh báo hệ thống (System Alerts): Ngoài kênh giao tiếp với khách hàng, tích hợp này còn mở ra một use case nội bộ cực kỳ thực dụng: đẩy alert từ máy chủ về điện thoại của admin qua WhatsApp. Ví dụ, khi CPU vượt ngưỡng 90%, một script trên VPS gọi API WhatsApp để gửi tin nhắn cảnh báo ngay lập tức đến số Business của bạn. Nhanh hơn email và thân thuộc hơn Slack với nhiều đội nhỏ.
Chuẩn bị môi trường triển khai
Đây là bước nhiều người bỏ qua và phải quay lại sửa. Hãy đảm bảo đầy đủ ba yếu tố sau trước khi chạm vào dòng code nào.
- Môi trường máy chủ (VPS/Server): Khuyến nghị sử dụng VPS chạy Ubuntu 20.04+ hoặc Windows Server 2019+ với địa chỉ IP tĩnh. Quan trọng hơn, máy chủ bắt buộc phải có chứng chỉ SSL hợp lệ (HTTPS) vì WhatsApp Cloud API từ chối hoàn toàn kết nối HTTP thuần. Nếu chưa có, Let’s Encrypt là lựa chọn miễn phí và đơn giản nhất. Nếu đang test local, có thể dùng ngrok để tạo HTTPS tunnel tạm thời, nhưng đây chỉ phù hợp cho môi trường development.
- Nền tảng Meta for Developers: Bạn cần chuẩn bị đồng thời ba thứ trước khi bắt đầu
- Tài khoản Meta Developer: Đăng ký tại developers.facebook.com
- Business Manager: Tạo tại business.facebook.com
- Số điện thoại “sạch”: Số chưa từng đăng ký WhatsApp cá nhân. Nếu số đó đang dùng app rồi, bạn phải hủy đăng ký trên app trước.
- Trạng thái OpenClaw: Đảm bảo môi trường Node.js (khuyến nghị v18 LTS trở lên) đã được cài đặt và instance OpenClaw lõi đang chạy ổn định.
Khởi tạo ứng dụng và lấy khóa API trên Meta Dashboard
Đây là phần tốn thời gian nhất nếu bạn làm lần đầu. Hãy đọc kỹ từng bước.
Bước 1: Tạo App và thêm sản phẩm WhatsApp:
Để tạo một App mới và thêm Whatsapp, bạn thực hiện từng bước dưới đây:
- Truy cập developers.facebook.com và đăng nhập
- Vào My Apps chọn Create App
- Chọn Business
- Điền tên app, email liên hệ và liên kết với Business Manager
- Sau khi tạo xong, trong Dashboard tìm mục Add Products chọn WhatsApp và nhấn Setup
- Menu bên trái sẽ xuất hiện mục WhatsApp với các submenu như Configuration và API Setup.
Bước 2: Khởi tạo số điện thoại thử nghiệm (Test Number)
Meta cung cấp sẵn một số điện thoại thử nghiệm miễn phí trong mỗi app, bạn không cần dùng số thật ngay.
Vào WhatsApp → API Setup, phần From sẽ hiển thị số test do Meta cấp, còn phần To cho phép nhập số cá nhân để nhận tin nhắn thử. Số test này có giới hạn 1.000 cuộc hội thoại mỗi tháng và chỉ gửi được đến tối đa 5 số điện thoại đã được whitelist, hoàn toàn đủ cho giai đoạn phát triển.
Bước 3: Lấy các thông số xác thực quan trọng
Bạn cần lưu lại ba giá trị sau để dùng ở các bước tiếp theo:
- Access Token (Temporary)
Vị trí: WhatsApp → API Setup → “Temporary access token”
Lưu ý: Hết hạn sau 24 giờ, chỉ dùng để test. - Phone Number ID
Vị trí: Ngay dưới ô “From” trong API Setup
Dạng: Chuỗi số 15-17 chữ số (VD: 123456789012345) - WhatsApp Business Account ID (WABA ID):
Vị trí: WhatsApp → API Setup → phần “WhatsApp Business Account”
Để tạo Permanent Token cho production, vào Business Settings → System Users → Add, tạo System User với quyền Admin, sau đó Generate New Token với permission whatsapp_business_messaging. Token loại này không hết hạn trừ khi bạn thu hồi thủ công.
Thiết lập Webhook để lắng nghe sự kiện nhắn tin
Mỗi khi người dùng gửi tin nhắn đến số Business của bạn, Meta sẽ chủ động gửi (push) một payload JSON về URL máy chủ mà bạn đăng ký. Đây là mô hình event-driven, server của bạn không cần polling liên tục nên tiết kiệm tài nguyên đáng kể. Luồng hoạt động như sau:
Người dùng gửi tin nhắn WhatsApp
↓
Máy chủ Meta xử lý
↓
Meta POST payload JSON → https://your-server.com/webhook
↓
OpenClaw nhận, xử lý, phản hồi
Trong code OpenClaw, khai báo một route lắng nghe cả GET (để xác thực) lẫn POST (để nhận tin nhắn). Đảm bảo firewall VPS đã mở port 443 cho inbound traffic.
const express = require('express');
const router = express.Router();
// GET: Xác thực Webhook với Meta
router.get('/webhook', (req, res) => {
const mode = req.query['hub.mode'];
const token = req.query['hub.verify_token'];
const challenge = req.query['hub.challenge'];
if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
res.status(200).send(challenge);
} else {
res.sendStatus(403);
}
});
// POST: Nhận tin nhắn từ Meta
router.post('/webhook', (req, res) => {
const body = req.body;
// Xử lý logic tại đây
res.sendStatus(200); // Phải trả 200 ngay, tránh Meta retry
});
module.exports = router;Sau khi endpoint đã sẵn sàng, vào WhatsApp → Configuration → Webhook trên Meta Dashboard rồi nhấn Edit. Điền Callback URL là https://your-domain.com/webhook và Verify Token là chuỗi bạn tự đặt, chuỗi này phải khớp hoàn toàn với giá trị WEBHOOK_VERIFY_TOKEN trong file .env. Nhấn Verify and Save, nếu server trả đúng giá trị challenge, Meta sẽ hiển thị trạng thái Complete màu xanh.
Cấu hình biến môi trường (.env) cho OpenClaw
File .env là nơi lưu toàn bộ thông tin nhạy cảm. Tuyệt đối không commit file này lên Git.
1. Khai báo các thông số API
Để thực hiện khai báo các thông số API, bạn cần mở file .env tại thư mục gốc của OpenClaw và khai báo các biến sau:
# Token truy cập WhatsApp (dùng Permanent Token cho production)
WHATSAPP_TOKEN=your_permanent_access_token_here
# Phone Number ID lấy từ Meta Dashboard
WHATSAPP_PHONE_ID=123456789012345
# Chuỗi xác thực Webhook tự đặt
WEBHOOK_VERIFY_TOKEN=my_secret_verify_token_2024
# WhatsApp Business Account ID
WABA_ID=987654321098765
# Cổng server OpenClaw
PORT=3000Đảm bảo đã cài package dotenv và gọi require(‘dotenv’).config() ở đầu file entry point như index.js hoặc app.js.
2. Điều chỉnh giới hạn bảo mật (CORS/Rate Limit)
Meta gửi Webhook từ một dải IP cố định theo kiểu server-to-server, nên CORS không ảnh hưởng trực tiếp. Tuy nhiên nếu VPS đang dùng middleware rate limiting, cần tạo exception cho endpoint /webhook để tránh bị chặn khi Meta gửi request liên tục:
const limiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 100,
skip: (req) => req.path === '/webhook'
});
app.use(limiter);
Xây dựng luồng xử lý (Trigger – Process – Output) cơ bản
Đây là phần “linh hồn” của toàn bộ tích hợp. Ba giai đoạn này quyết định agent của bạn thông minh đến đâu.
1. Kích hoạt Agent (Trigger)
Khi Webhook nhận POST request từ Meta, payload JSON có cấu trúc lồng nhau khá sâu. OpenClaw cần extract hai trường quan trọng là from (số điện thoại người gửi) và text.body (nội dung tin nhắn). Với media như hình ảnh hay audio, trường type sẽ tương ứng là image hoặc audio kèm theo media_id để download về xử lý.
{
"entry": [{
"changes": [{
"value": {
"messages": [{
"from": "84901234567",
"type": "text",
"text": { "body": "Xin chào, tôi cần hỗ trợ" }
}]
}
}]
}]
}
2. Xử lý thông tin (Process)
Sau khi có nội dung, OpenClaw gửi đến LLM để sinh câu trả lời. Bạn có thể maintain conversation context bằng cách lưu lịch sử hội thoại theo phoneNumber vào Redis hoặc database, giúp AI nhớ ngữ cảnh các tin nhắn trước đó.
async function processMessage(userMessage, phoneNumber) {
const aiResponse = await anthropic.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
messages: [{ role: 'user', content: userMessage }]
});
const replyText = aiResponse.content[0].text;
await sendWhatsAppMessage(phoneNumber, replyText);
}
3. Trả kết quả (Output)
Gọi WhatsApp Cloud API để gửi phản hồi về cho người dùng. Lưu ý trường to phải là số điện thoại đầy đủ quốc tế không có dấu cộng, ví dụ 84901234567 thay vì +84901234567.
async function sendWhatsAppMessage(to, message) {
const url = `https://graph.facebook.com/v19.0/${process.env.WHATSAPP_PHONE_ID}/messages`;
await axios.post(url, {
messaging_product: 'whatsapp',
to: to,
type: 'text',
text: { body: message }
}, {
headers: {
'Authorization': `Bearer ${process.env.WHATSAPP_TOKEN}`,
'Content-Type': 'application/json'
}
});
}
Khắc phục các lỗi thường gặp
Dù đã làm đúng từng bước, một số lỗi vẫn có thể xuất hiện. Đây là ba lỗi phổ biến nhất và cách xử lý dứt điểm.
1. Webhook báo lỗi 403 Forbidden hoặc không thể xác minh
Nguyên nhân phổ biến nhất là chứng chỉ SSL không hợp lệ hoặc đã hết hạn, bạn có thể kiểm tra nhanh tại SSL Labs. Nguyên nhân thứ hai là chuỗi Verify Token trong Dashboard và trong .env không khớp, kể cả khoảng trắng thừa. Dùng lệnh curl sau để simulate đúng request xác thực của Meta và kiểm tra server phản hồi gì:
curl "https://your-domain.com/webhook?hub.mode=subscribe&hub.verify_token=my_secret_verify_token_2024&hub.challenge=test123"
# Kết quả mong đợi: test123
2. Lỗi 401 Unauthorized khi gửi tin nhắn
Đây hầu như luôn là do Temporary Access Token đã hết hạn sau 24 giờ. Giải pháp dứt điểm là tạo Permanent Token theo các bước sau:
- Bước 1: Vào Business Settings → System Users → Add
- Bước 2: Đặt tên cho System User, chọn role Admin
- Bước 3: Nhấn Generate New Token và chọn app của bạn
- Bước 4: Tick quyền whatsapp_business_messaging và whatsapp_business_management
- Bước 5: Copy token và cập nhật giá trị WHATSAPP_TOKEN trong file .env
3. Chính sách cửa sổ 24 giờ (24-hour window policy)
Đây là giới hạn quan trọng nhất mà nhiều developer bỏ qua đến tận khi ra production mới phát hiện. Meta chỉ cho phép bot gửi tin nhắn tự do trong vòng 24 giờ kể từ tin nhắn cuối cùng của người dùng. Sau mốc đó, bạn bắt buộc phải dùng Template Messages đã được Meta phê duyệt trước, thay vì gửi free-form text thông thường.
Điều này ảnh hưởng trực tiếp đến các use case như gửi báo cáo định kỳ hay nhắc nhở tái khám sau nhiều ngày. Giải pháp là tạo và submit Message Templates trong WhatsApp theo các bước sau:
- Bước 1: Vào WhatsApp Manager → Message Templates → Create Template
- Bước 2: Chọn danh mục phù hợp (Marketing, Utility, Authentication)
- Bước 3: Soạn nội dung template, có thể dùng biến động như {{1}}, {{2}} để điền thông tin linh hoạt
- Bước 4: Submit và chờ Meta phê duyệt, thường mất 1-2 ngày làm việc
- Bước 5: Sau khi được duyệt, gọi API với type: “template” thay vì type: “text” như ví dụ dưới:
{
messaging_product: 'whatsapp',
to: phoneNumber,
type: 'template',
template: {
name: 'ten_template_cua_ban',
language: { code: 'vi' },
components: [{
type: 'body',
parameters: [{ type: 'text', text: 'Nội dung biến số 1' }]
}]
}
}
Hướng dẫn kết nối OpenClaw với WhatsApp trên đây đã bao phủ toàn bộ vòng đời triển khai: từ khởi tạo hạ tầng, lấy API key, cấu hình Webhook, đến xây dựng luồng AI hoàn chỉnh và xử lý các tình huống lỗi thực tế. Ba điểm mấu chốt cần ghi nhớ là SSL bắt buộc cho Webhook, Token phải là Permanent cho môi trường production, và policy 24 giờ cần được thiết kế vào kiến trúc ngay từ đầu chứ không phải sau khi đã ra live.
Khi đã nắm vững nền tảng này, bạn có thể mở rộng OpenClaw để xử lý media, tích hợp CRM hay xây dựng hệ thống multi-agent phức tạp hơn, tất cả trên cùng một kênh WhatsApp quen thuộc với hàng tỷ người dùng toàn cầu.
