# Hướng Dẫn Thiết Lập Facebook Messenger

Hướng dẫn từng bước để thiết lập tích hợp Facebook Messenger Platform.

## Yêu Cầu

- Tài khoản Facebook
- Facebook Page (đã tạo sẵn)
- Tài khoản developer trên Meta for Developers
- HTTPS endpoint cho webhook (production)
- ngrok (cho local testing)

## Bước 1: Tạo Facebook App

### 1.1 Truy Cập Meta for Developers

1. Truy cập [developers.facebook.com](https://developers.facebook.com/)
2. Click "My Apps" → "Create App"
3. Chọn use case: **"Other"**
4. Chọn app type: **"Business"**

### 1.2 Cấu Hình App

- **App Name**: ví dụ, "My Shop Chatbot"
- **App Contact Email**: email của bạn
- **Business Account**: Chọn hoặc tạo mới

> **Lưu ý**: Copy **App ID** và **App Secret** (Settings → Basic). Bạn sẽ cần chúng sau.

---

## Bước 2: Thêm Messenger Product

### 2.1 Thêm Messenger

1. Trong app dashboard, click **"Add Product"**
2. Tìm **"Messenger"** và click **"Set Up"**

### 2.2 Generate Page Access Token

1. Trong Messenger Settings, scroll đến **"Access Tokens"**
2. Click **"Add or Remove Pages"**
3. Chọn Facebook Page của bạn
4. Click **"Generate Token"**
5. **Copy và lưu** Page Access Token

```bash
# Lưu vào file .env
FACEBOOK_PAGE_ACCESS_TOKEN="EAAxxxxxxxxxx..."
```

> **Cảnh báo**: Page Access Token rất nhạy cảm! Không bao giờ commit vào Git hoặc công khai.

---

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

### 3.1 Deploy Service hoặc Dùng ngrok

**Option A: Local Development với ngrok**

```bash
# Cài đặt ngrok
brew install ngrok  # macOS

# Chạy service local
dotnet run --project src/MktFacebookService.API

# Expose service local
ngrok http 5000

# Copy HTTPS URL, ví dụ, https://abc123.ngrok.io
```

**Option B: Production Deployment**

Deploy service lên production server với HTTPS enabled.

### 3.2 Thêm Webhook trong Facebook App

1. Vào Messenger → Settings → **"Webhooks"**
2. Click **"Add Callback URL"**
3. Nhập:
   - **Callback URL**: `https://your-domain.com/api/v1/webhooks/facebook`
   - **Verify Token**: Tạo chuỗi random (ví dụ, `my_verify_token_12345`)
4. Click **"Verify and Save"**

```bash
# Lưu vào .env
FACEBOOK_VERIFY_TOKEN="my_verify_token_12345"
```

> **Quan trọng**: Verify Token phải match với giá trị trong service configuration!

### 3.3 Subscribe Webhook Events

Sau khi webhook được verified, chọn các fields:

- [x] **messages** - Nhận customer messages
- [x] **messaging_postbacks** - Nhận button clicks
- [x] **message_reads** - Nhận read receipts (tùy chọn)
- [x] **messaging_optins** - Nhận opt-in events

Click **"Subscribe"**.

---

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

### 4.1 Gửi Test Message

1. Vào Facebook Page của bạn
2. Click **"Send Message"** (với tư cách user, không phải admin)
3. Gõ: `Hello`
4. Kiểm tra logs của service cho incoming webhook event

**Log mong đợi**:
```
[INFO] Received message event from user: 1234567890
[INFO] Processing incoming message: "Hello"
[INFO] Sending response via Facebook Messenger
```

### 4.2 Test Nút Get Started

Cấu hình nút Get Started để trigger welcome flow.

**Lệnh cURL**:
```bash
curl -X POST "https://graph.facebook.com/v21.0/me/messenger_profile" \
  -H "Content-Type: application/json" \
  -d '{
    "get_started": {
      "payload": "GET_STARTED"
    }
  }' \
  -d "access_token=YOUR_PAGE_ACCESS_TOKEN"
```

---

## Tổng Hợp Biến Môi Trường

```bash
# Cấu hình Facebook App
FACEBOOK_APP_ID="123456789012345"
FACEBOOK_APP_SECRET="abcdef1234567890abcdef1234567890"
FACEBOOK_VERIFY_TOKEN="my_verify_token_12345"

# Facebook Page Access Token
FACEBOOK_PAGE_ACCESS_TOKEN="EAAxxxxxxxxxx..."

# Facebook API Version
FACEBOOK_API_VERSION="v21.0"
```

---

## Xử Lý Sự Cố

### Issue 1: Webhook Verification Failed

**Vấn đề**: 
```
The URL couldn't be validated. Callback verification failed...
```

**Giải pháp**:
1. Kiểm tra service đang chạy và accessible qua HTTPS
2. Verify `FACEBOOK_VERIFY_TOKEN` match exactly
3. Check logs cho webhook GET request
4. Đảm bảo returning hub.challenge as plain text (không phải JSON)

### Issue 2: Không Nhận Được Messages

**Vấn đề**: Service không nhận được messages

**Giải pháp**:
1. Verify webhook subscriptions active (messages, messaging_postbacks)
2. Check Page Access Token chưa expire
3. Test webhook manually với curl

### Issue 3: Không Gửi Được Messages

**Vấn đề**: 
```
(#200) This user can't receive messages from this bot
```

**Giải pháp**:
- User phải gửi message trước (GDPR compliance)
- Hoặc user phải opt-in qua checkbox plugin
- Page Access Token phải có `pages_messaging` permission

---

## Danh Sách Kiểm Tra

- [ ] Facebook App đã tạo và Messenger product đã thêm
- [ ] Page Access Token đã generate và save
- [ ] Webhook đã configure và verified
- [ ] Webhook events đã subscribe (messages, postbacks)
- [ ] Test message đã gửi và nhận thành công
- [ ] Bot response đã gửi lại cho user
- [ ] Nút Get Started triggers welcome flow
- [ ] Signature verification hoạt động

---

## Tài Nguyên

### Tài Liệu Chính Thức Facebook
- [Tổng Quan Messenger Platform](https://developers.facebook.com/docs/messenger-platform/)
- [Webhooks Reference](https://developers.facebook.com/docs/messenger-platform/webhooks)
- [Send API Reference](https://developers.facebook.com/docs/messenger-platform/send-messages)

### Công Cụ
- [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/)
- [ngrok](https://ngrok.com/) - Local HTTPS tunnel

### Tài Liệu Nội Bộ
- [Tài Liệu API](./API.md)
- [Tài Liệu Kiến Trúc](./ARCHITECTURE.md)
- [Cấu Hình AI Chatbot](./AI_CHATBOT.md)
