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](https://business.facebook.com/)
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](https://developers.facebook.com/)
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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
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`:
```bash
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](API.md) - Tìm hiểu các endpoints có sẵn
- [Hướng Dẫn Automation](AUTOMATION_GUIDE.md) - Thiết lập luồng tự động
- [Hướng Dẫn AI Chatbot](AI_CHATBOT_GUIDE.md) - Cấu hình AI agent

## Tài Nguyên

- [WhatsApp Cloud API Docs](https://developers.facebook.com/docs/whatsapp/cloud-api)
- [Business Verification](https://www.facebook.com/business/help/2058515294227817)
- [Hướng Dẫn Message Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)
- [Tham Chiếu Webhook](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks)