Nối WA Auto với app AI và phần mềm của bạn

Ba cửa vào

Ba cửa dùng chung một bộ kiểm: quyền, số được dùng, gói, chống trùng, xác nhận 2 bước và nút tạm dừng khẩn.

API v1 cũ vẫn chạy ít nhất 6 tháng — xem tài liệu v1.

Xác thực & quyền

Chủ hoặc quản trị tạo khoá trong Cài đặt → Kết nối AI & API; khoá chỉ hiện một lần. Gửi khoá trong header Authorization: Bearer …. Mỗi khoá có:

• Quyền theo từng tài nguyên (đọc / ghi / gửi / xoá…). Quyền xoá tắt sẵn. Khoá không bao giờ vượt vai trò người tạo; người tạo rời workspace hoặc bị hạ quyền thì khoá tạm khoá.
• Số được dùng: mọi số, hoặc chọn số / nhãn số (tính lúc gọi — số mới gắn nhãn dùng được ngay).
• Hạn dùng và danh sách IP (tuỳ chọn), hồ sơ công cụ MCP.

App AI đăng nhập qua MCP thì người dùng chọn quyền, số và hồ sơ trên trang cho phép; app hành động bằng đúng quyền của người đó, không hơn.

curl https://<ten-mien-cua-ban>/api/public/v2/me \
  -H "Authorization: Bearer $WA_AUTO_KEY"

Lệnh & chờ kết quả

Mọi thao tác WhatsApp trả về lệnh (202 + header Location). Chờ tối đa 25 giây bằng header Prefer: wait=N, hoặc gọi operation_wait. Hết giờ chờ không phải lỗi — gọi chờ tiếp.

Lệnh unverified hoặc lỗi outcome_unknown: tin có thể đã đi. Đọc lại lệnh theo mã — không gửi lại.

Chống trùng

• REST: mọi POST cần header Idempotency-Key (1–255 ký tự, mỗi lệnh một giá trị). Gọi lại cùng khoá + cùng nội dung nhận đúng kết quả cũ kèm Idempotent-Replayed: true; khác nội dung → 422; lần đầu còn chạy → 409.
• MCP: trường idempotencyKey tuỳ chọn; không có thì cùng một lời gọi trong 60 giây được coi là một lệnh.

Phiên bản cấu hình

Cấu hình có phiên bản (hạn mức số, luật tự động, lịch chạy…) trả ETag. Khi sửa, gửi If-Match (MCP: trường revision) với bản đã đọc; người khác sửa trước → 412 revision_conflict, đọc lại rồi sửa trên bản mới. Không bao giờ ghi đè lặng lẽ.

Xác nhận 2 bước

Thao tác xoá hoặc khó hoàn tác: lần gọi đầu trả 409 confirmation_required kèm confirmation.summary và confirmation.code (hạn 10 phút). Hỏi người dùng, rồi gọi lại đúng nội dung kèm header X-Confirmation-Code (MCP: confirmationCode). Mã chỉ dùng một lần.

Sự kiện & webhook

Đọc thay đổi bằng events_poll với con trỏ (lưu nextCursor, lần sau đọc tiếp), hoặc nhận webhook. Cả hai đọc từ cùng một nhật ký sự kiện, giao ít nhất một lần — lọc trùng theo id.

Webhook: thêm địa chỉ https trong Cài đặt → Kết nối AI & API → Webhook. Trả 2xx trong 8 giây; lỗi thì thử lại sau 1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ. Thân theo CloudEvents 1.0:

{
  "specversion": "1.0",
  "id": "b6f1c2d0-6c55-4c1e-9a43-5d1d3b1e7a10",
  "type": "message.received",
  "version": 1,
  "time": "2026-10-17T07:28:01.000Z",
  "source": "wa-auto/<workspace-id>",
  "datacontenttype": "application/json",
  "data": {
    "…": "…"
  },
  "event": "message.received",
  "at": "2026-10-17T07:28:01.000Z"
}

Kiểm chữ ký: header x-wa-auto-signature = sha256= + HMAC-SHA256 của <timestamp>.<body gốc>; hoặc chuẩn Standard Webhooks (webhook-signature):

// npm i standardwebhooks — dùng đúng bí mật ký whsec_… của webhook
import { Webhook } from "standardwebhooks";
const wh = new Webhook(secret);
const event = wh.verify(rawBody, {
  "webhook-id": req.header("webhook-id"),
  "webhook-timestamp": req.header("webhook-timestamp"),
  "webhook-signature": req.header("webhook-signature"),
}); // ném lỗi nếu sai chữ ký hoặc quá cũ

Giới hạn tốc độ

• Tối đa 60 yêu cầu mỗi phút cho mỗi khoá hoặc kết nối AI; quá thì 429 kèm Retry-After. Mọi phản hồi có RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.
• Danh sách trả nextCursor; limit tối đa 100. Thân yêu cầu tối đa 64 KiB.
• Hạn mức gửi của từng số do người dùng đặt (mặc định mở). Không xoay vòng hay đổi số để né giới hạn — cổng giao việc chặn và ghi nhận.

Mã lỗi

Lỗi theo RFC 9457 (application/problem+json): { type, title, status, detail, code, retryable, requestId }.

Nối Claude / ChatGPT

1. Trong app AI, thêm connector / MCP server tuỳ chỉnh với địa chỉ https://<ten-mien-cua-ban>/mcp.
2. App AI mở trang đăng nhập WA Auto. Đăng nhập, chọn workspace, quyền, số được dùng và hồ sơ công cụ, rồi bấm Cho phép.
3. Hỏi app AI “tôi đang có những số WhatsApp nào?” để thử. Sửa hoặc thu hồi bất cứ lúc nào trong Cài đặt → Kết nối AI & API.

Server hoặc n8n dùng cổng khoá https://<ten-mien-cua-ban>/api/public/mcp với header Authorization: Bearer ….

Hồ sơ công cụ MCP

Hồ sơ chỉ quyết định app AI thấy công cụ nào (để danh sách gọn); quyền mới quyết định làm được gì. Hồ sơ Lõi luôn có.