pos-system/microservices/services/mkt-whatsapp-service-net/docs/vi/WHATSAPP_SETUP.md

Hướng Dẫn Thiết Lập WhatsApp

Cập nhật lần cuối: 2026-01-18

Hướng dẫn này hướng dẫn bạn thiết lập quyền truy cập WhatsApp Business API cho MKT WhatsApp Service.

Yêu Cầu Tiên Quyết

• Tài khoản Meta Business
• Quyền truy cập Facebook Business Manager
• Doanh nghiệp đã xác minh (cho giới hạn tier cao hơn)
• Domain với HTTPS (cho webhook)

Bước 1: Tạo Tài Khoản Meta Business

1. Truy cập Meta Business Suite
2. Nhấp "Create Account"
3. Nhập tên doanh nghiệp và thông tin chi tiết
4. Xác minh email doanh nghiệp của bạn

Bước 2: Truy Cập WhatsApp API

Tùy Chọn A: Cloud API (Khuyến Nghị)

1. Truy cập Meta for Developers
2. Nhấp "My Apps" → "Create App"
3. Chọn "Business" làm loại app
4. Điền thông tin app (tên, email liên hệ, tài khoản doanh nghiệp)
5. Sau khi tạo, nhấp "Add Product"
6. Chọn "WhatsApp" → "Set Up"

Tùy Chọn B: On-Premise API

Không được khuyến nghị cho hầu hết các trường hợp sử dụng. Yêu cầu cơ sở hạ tầng máy chủ chuyên dụng và hợp tác BSP.

Bước 3: Lấy Số Điện Thoại

Số Điện Thoại Thử Nghiệm (Development)

Meta cung cấp số thử nghiệm cho phát triển:

1. Trong cài đặt sản phẩm WhatsApp, bạn sẽ thấy một số điện thoại thử nghiệm
2. Sao chép Phone Number ID
3. Thêm người nhận thử nghiệm (tối đa 5) trong tab Configuration

Số Điện Thoại Production

1. Nhấp "Add Phone Number"
2. Chọn một trong hai:
   • Use existing: Di chuyển số WhatsApp Business hiện có
   • Register new: Lấy số mới từ Meta
3. Xác minh số điện thoại qua SMS/cuộc gọi
4. Hoàn tất xác minh doanh nghiệp

Quan Trọng: Sau khi kết nối với API, bạn không thể sử dụng Ứng dụng WhatsApp Business trên số này.

Bước 4: Tạo Access Token

Token Tạm Thời (24 giờ)

1. Truy cập WhatsApp → API Setup
2. Sao chép access token tạm thời
3. Chỉ sử dụng để thử nghiệm

Token Vĩnh Viễn

1. Truy cập Meta Business Suite → Settings → System Users
2. Nhấp "Add" → Tạo system user (tên: "WhatsApp API")
3. Gán vai trò "Admin"
4. Nhấp "Generate Token"
5. Chọn app của bạn
6. Chọn quyền:
   • whatsapp_business_management
   • whatsapp_business_messaging
7. Sao chép token (lưu trữ an toàn, chỉ hiển thị một lần)

Bước 5: Cấu Hình Webhook

Lấy Webhook URL

Từ dịch vụ đã triển khai của bạn:

https://yourdomain.com/api/v1/whatsapp/webhooks

Tạo Verify Token

Tạo chuỗi ngẫu nhiên để xác minh webhook:

# Tạo token ngẫu nhiên
openssl rand -hex 32

Lưu điều này dưới dạng WHATSAPP_WEBHOOK_VERIFY_TOKEN trong .env của bạn

Thiết Lập Trong Meta

1. Truy cập WhatsApp → Configuration → Webhook
2. Nhấp "Edit"
3. Nhập:
   • Callback URL: https://yourdomain.com/api/v1/whatsapp/webhooks
   • Verify Token: Token bạn đã tạo
4. Nhấp "Verify and Save"

Đăng Ký Sự Kiện

Sau khi xác minh, đăng ký:

• ✅ messages - Tin nhắn khách hàng đến
• ✅ message_status (tùy chọn) - Cập nhật trạng thái gửi/đã đọc
• ✅ messaging_postbacks (tùy chọn) - Tương tác nút

Bước 6: Lấy App Secret

Để xác minh chữ ký webhook:

1. Truy cập App Dashboard → Settings → Basic
2. Nhấp "Show" bên cạnh "App Secret"
3. Sao chép và lưu dưới dạng WHATSAPP_APP_SECRET

Bước 7: Cấu Hình Dịch Vụ

Cập nhật file .env của bạn:

# WhatsApp Configuration
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_ACCESS_TOKEN=your_permanent_token_here
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_verify_token_here
WHATSAPP_APP_SECRET=your_app_secret_here
WHATSAPP_API_VERSION=v21.0

Bước 8: Kiểm Tra Tích Hợp

Xác Minh Webhook

Dịch vụ sẽ tự động xử lý xác minh webhook. Kiểm tra logs:

docker-compose logs -f mkt-whatsapp-service-net

Bạn nên thấy:

[INFO] Webhook verification successful

Gửi Tin Nhắn Thử Nghiệm

1. Lấy số WhatsApp của khách hàng thử nghiệm
2. Sử dụng API để gửi tin nhắn:

curl -X POST http://localhost/api/v1/whatsapp/conversations/{conversationId}/messages \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "text",
      "text": "Xin chào từ MKT WhatsApp Service!"
    }
  }'

Nhận Tin Nhắn Thử Nghiệm

1. Gửi tin nhắn từ WhatsApp của khách hàng thử nghiệm đến số doanh nghiệp của bạn
2. Kiểm tra service logs cho webhook đến
3. Xác minh tin nhắn được lưu trữ trong database

Bước 9: Message Templates

Đối với tin nhắn ngoài cửa sổ 24 giờ, bạn cần templates đã phê duyệt.

Tạo Template

1. Truy cập WhatsApp → Message Templates
2. Nhấp "Create Template"
3. Điền:
   • Name: order_confirmation (chữ thường, chỉ dấu gạch dưới)
   • Category: Utility/Marketing/Authentication
   • Language: Vietnamese, English, v.v.
   • Content: Sử dụng placeholders như {{1}}, {{2}}

Ví dụ template:

Xin chào {{1}}!

Đơn hàng #{{2}} của bạn đã được xác nhận.
Tổng tiền: {{3}} VNĐ

Cảm ơn bạn đã mua hàng!

4. Gửi để xem xét (phê duyệt mất 1-3 ngày)

Sử Dụng Template Trong Dịch Vụ

Sau khi được phê duyệt, cập nhật .env:

WHATSAPP_TEMPLATE_ORDER_CONFIRMATION=order_confirmation

Bước 10: Nâng Cấp Giới Hạn Tier

Tier Ban Đầu

Số điện thoại mới bắt đầu ở Tier 1 (1.000 cuộc hội thoại/ngày).

Quy Trình Nâng Cấp

Tier tự động nâng cấp dựa trên:

1. Chất lượng số điện thoại (tỷ lệ chặn thấp)
2. Khối lượng gửi
3. Thời gian (tối thiểu 7 ngày ở tier hiện tại)

Các Mức Tier

Tier	Giới Hạn Hàng Ngày	Tiêu Chí Nâng Cấp
Tier 1	1.000	Tier khởi đầu
Tier 2	10.000	7 ngày + chất lượng tốt
Tier 3	100.000	7 ngày + khối lượng cao
Unlimited	Không giới hạn	Yêu cầu từ Meta

Khắc Phục Sự Cố

Xác Minh Webhook Thất Bại

Vấn Đề: "Verification token mismatch"

Giải Pháp:

1. Kiểm tra WHATSAPP_WEBHOOK_VERIFY_TOKEN khớp chính xác
2. Đảm bảo dịch vụ đang chạy và có thể truy cập
3. Kiểm tra HTTPS hoạt động (WhatsApp yêu cầu HTTPS)

Tin Nhắn Không Gửi Được

Vấn Đề: API trả về lỗi (#131030) Recipient phone number not valid

Giải Pháp:

1. Đảm bảo số bao gồm mã quốc gia không có + hoặc 0
2. Định dạng: 84901234567 (Vietnam), không phải +84901234567

Vấn Đề: (#368) Template not found

Giải Pháp:

1. Xác minh template đã được phê duyệt trong Meta dashboard
2. Kiểm tra tên template khớp chính xác
3. Đảm bảo mã ngôn ngữ đúng

Vượt Giới Hạn Tốc Độ

Vấn Đề: (#130429) Rate limit exceeded

Giải Pháp:

1. Kiểm tra tier hiện tại trong Meta dashboard
2. Triển khai exponential backoff
3. Yêu cầu nâng cấp tier nếu cần

Access Token Không Hợp Lệ

Vấn Đề: (#190) Invalid OAuth access token

Giải Pháp:

1. Token có thể đã hết hạn - tạo token vĩnh viễn mới
2. Kiểm tra token có quyền đúng
3. Xác minh token thuộc về app đúng

Thực Hành Bảo Mật Tốt Nhất

1. Không bao giờ commit tokens - Sử dụng biến môi trường
2. Xoay tokens thường xuyên - Tạo tokens mới mỗi 6 tháng
3. Xác minh chữ ký webhook - Luôn xác thực X-Hub-Signature-256
4. Chỉ sử dụng HTTPS - WhatsApp sẽ từ chối webhooks HTTP
5. Hạn chế truy cập IP - Whitelist dải IP của Meta nếu có thể

Tối Ưu Hóa Chi Phí

1. Sử dụng utility templates - Rẻ hơn marketing
2. Tận dụng cửa sổ 24 giờ - Tin nhắn miễn phí trong cửa sổ
3. Tránh spam - Tỷ lệ chặn cao có thể giới hạn tài khoản của bạn
4. Theo dõi hội thoại - Theo dõi loại nào mở/đóng cửa sổ

Bước Tiếp Theo

• Tài Liệu API - Tìm hiểu các endpoints có sẵn
• Hướng Dẫn Automation - Thiết lập luồng tự động
• Hướng Dẫn AI Chatbot - Cấu hình AI agent

Tài Nguyên

• WhatsApp Cloud API Docs
• Business Verification
• Hướng Dẫn Message Templates
• Tham Chiếu Webhook