# Hướng dẫn setup Facebook Page Admin cho Hermes từ đầu

Tài liệu này mô tả quy trình **từ con số 0** để một Hermes instance có thể kết nối Facebook/Meta và quản trị Page: tạo Meta Business, tạo Meta App, chọn use case, cấp quyền, tạo OAuth hoặc System User token, lấy Page ID, đăng bài, đọc comment, trả lời comment và mở rộng sang Messenger inbox.

Tài liệu **không phụ thuộc vào app mẫu nào**. Bạn có thể đặt tên app, connector hoặc CLI theo hệ thống riêng. Mục tiêu là tạo được một lớp connector an toàn để Hermes gọi, thay vì đưa token trực tiếp vào prompt/chat.

## 1. Kết quả cuối cùng cần đạt

Hermes cần có một connector nội bộ có thể:

- Liệt kê Facebook Pages mà user/business có quyền quản trị.
- Đăng bài text/link/photo lên Page.
- Đọc bài mới nhất và verify permalink.
- Đọc comment trên post.
- Trả lời comment sau khi dry-run/draft.
- Tuỳ chọn: đọc inbox Page qua Messenger webhook.
- Tuỳ chọn: trả lời Messenger với human approval.

Kiến trúc:

```text
Meta Business Manager
  ├─ Facebook Page
  ├─ Meta App
  │   ├─ Use cases / Products
  │   ├─ Permissions
  │   ├─ OAuth / Login
  │   ├─ System User token hoặc OAuth Page token
  │   └─ Webhooks nếu cần Messenger
  └─ Hermes instance
      ├─ Secret store
      ├─ Facebook connector CLI/API
      ├─ Hermes skill / command
      └─ Telegram / Dashboard interface
```

## 2. Tạo hoặc kiểm tra Meta Business

Mở **Meta Business Settings**:

```text
https://business.facebook.com/settings/
```

Nếu chưa có Business:

1. Chọn **Create business**.
2. Nhập tên doanh nghiệp.
3. Nhập email doanh nghiệp.
4. Hoàn tất xác minh cơ bản.

Nếu đã có Business, chọn đúng Business ở góc trái.

### Thêm Facebook Page vào Business

Trong Business Settings:

1. Vào **Accounts → Pages**.
2. Chọn **Add**.
3. Chọn một trong ba cách:
   - **Add a Page** nếu bạn sở hữu Page.
   - **Request access to a Page** nếu Page thuộc bên khác.
   - **Create a new Page** nếu cần Page mới.
4. Đảm bảo tài khoản triển khai có quyền admin/full control.

### Kiểm tra quyền người triển khai

Vào **Users → People**, chọn người triển khai và kiểm tra:

- Có quyền với Business.
- Có quyền với Page.
- Có quyền quản lý app hoặc asset liên quan.

## 3. Tạo Meta App

Mở:

```text
https://developers.facebook.com/apps/
```

Chọn **Create App**.

### Chọn app type / use case

Meta UI thay đổi theo thời điểm. Có lúc Meta hỏi **Use cases** thay vì app type cũ.

Chọn hướng gần nhất với mục tiêu:

- Quản lý Page/đăng bài: **Manage everything on your Page**, **Business**, hoặc **Other** nếu không thấy lựa chọn đúng.
- Đăng nhập cấp quyền: thêm **Facebook Login for Business**.
- Inbox Messenger: thêm **Messenger**.
- Nhận event real-time: thêm **Webhooks**.

### Gắn app vào Business

Trong App Dashboard:

1. Vào **App settings → Basic**.
2. Kiểm tra app đã gắn với Business Manager chưa.
3. Nếu chưa, vào Business Settings → **Accounts → Apps → Add**.

### Cấu hình thông tin cơ bản

Cần có:

- App name
- App contact email
- App domain nếu dùng production
- Privacy Policy URL nếu public
- Terms URL nếu cần
- Business verification nếu Meta yêu cầu

## 4. Thêm products/use cases

### Facebook Login for Business

Dùng để user admin Page authorize app.

Cấu hình:

- Client OAuth Login: enabled
- Web OAuth Login: enabled
- Valid OAuth Redirect URIs

Ví dụ redirect URI:

```text
https://your-domain.com/auth/meta/callback
```

### Messenger

Cần nếu muốn đọc/trả lời inbox Page.

### Webhooks

Cần nếu muốn nhận message/comment event real-time.

Webhook URL phải là HTTPS public.

## 5. Permissions cần xin

### Bản tối thiểu cho đăng bài + comment

```text
pages_show_list
pages_read_engagement
pages_manage_posts
pages_manage_engagement
```

| Permission | Dùng để |
|---|---|
| pages_show_list | Liệt kê Page mà user quản trị |
| pages_read_engagement | Đọc bài, comment, engagement cơ bản |
| pages_manage_posts | Đăng bài lên Page |
| pages_manage_engagement | Reply comment / quản lý tương tác |

### Bổ sung cho Messenger inbox

```text
pages_messaging
pages_manage_metadata
```

| Permission | Dùng để |
|---|---|
| pages_messaging | Đọc/gửi tin nhắn Messenger cho Page |
| pages_manage_metadata | Subscribe webhook, quản lý metadata Page |

### Bổ sung cho insights

```text
read_insights
```

Một số quyền có thể cần Meta App Review nếu dùng production hoặc dùng cho Page/user ngoài developer/tester.

## 6. Hai cách lấy token

## Cách A — OAuth Page token

Phù hợp khi:

- Mỗi khách hàng tự authorize Page của họ.
- Bạn cần SaaS/multi-tenant.
- Page không nằm trong cùng Business của bạn.

Luồng:

1. Tạo OAuth URL với scopes cần thiết.
2. User admin Page login và authorize.
3. Backend nhận `code`.
4. Exchange `code` lấy user access token.
5. Gọi `/me/accounts` để lấy Page access token.
6. Lưu Page access token trong secret store.

Ưu điểm: phù hợp nhiều khách hàng.  
Nhược điểm: token có thể hết hạn/revoked, cần reconnect flow, production thường cần App Review.

## Cách B — System User token trong Meta Business

Phù hợp khi:

- Page thuộc Business của bạn.
- Cần server-to-server automation ổn định.
- Dùng nội bộ hoặc cho Page do business quản lý.

### Tạo System User

Business Settings → **Users → System users**:

1. Chọn **Add**.
2. Đặt tên, ví dụ: `Hermes Page Automation`.
3. Chọn role phù hợp, thường là **Employee** hoặc **Admin** tuỳ chính sách.

### Gán asset cho System User

Chọn System User:

1. Chọn **Add assets**.
2. Chọn Facebook Page cần quản trị.
3. Cấp quyền cần thiết:
   - Create content / manage posts
   - Manage comments / engagement
   - View Page / engagement
   - Messaging nếu UI cho phép và cần inbox
4. Chọn app liên quan nếu cần.

### Generate token

Trong System User:

1. Chọn **Generate new token**.
2. Chọn app vừa tạo.
3. Chọn permissions cần thiết:
   - pages_show_list
   - pages_read_engagement
   - pages_manage_posts
   - pages_manage_engagement
   - pages_messaging nếu cần inbox
   - pages_manage_metadata nếu cần webhook
4. Copy token một lần duy nhất và lưu vào secret store.

### Kiểm tra token

Dùng curl hoặc Graph API Explorer:

```bash
curl -G 'https://graph.facebook.com/v20.0/me/accounts' \
  --data-urlencode 'fields=id,name,access_token,tasks' \
  --data-urlencode 'access_token=SYSTEM_USER_TOKEN'
```

Kết quả cần thấy Page mong muốn.

Nếu không thấy Page:

- System User chưa được gán Page asset.
- Token thiếu permission.
- App chưa gắn đúng Business.
- Người/business không có quyền Page.

## 7. Lưu secret trên Hermes instance

Tạo secret file ngoài repo:

```bash
mkdir -p /opt/hermes-instance/secrets
chmod 700 /opt/hermes-instance/secrets
nano /opt/hermes-instance/secrets/facebook_page.env
chmod 600 /opt/hermes-instance/secrets/facebook_page.env
```

Nội dung mẫu:

```bash
META_GRAPH_VERSION=v20.0
META_APP_ID=REDACTED
META_APP_SECRET=REDACTED
FACEBOOK_PAGE_ID=123456789
FACEBOOK_PAGE_NAME=Your Page Name
FACEBOOK_ACCESS_TOKEN=REDACTED
```

Không commit file này. Không paste vào chat. Không ghi vào Hermes memory.

## 8. Viết connector nội bộ

Bạn có thể đặt tên connector tuỳ ý. Hermes chỉ nên gọi connector, không trực tiếp cầm token.

CLI generic nên có:

```bash
fbpage auth check
fbpage pages list
fbpage latest-post --page-id PAGE_ID --limit 5
fbpage post --page-id PAGE_ID --text "Nội dung"
fbpage photo-post --page-id PAGE_ID --text "Caption" --image /path/image.jpg
fbpage comments --post-id POST_ID --limit 25
fbpage reply-comment --comment-id COMMENT_ID --message "Nội dung" --dry-run
fbpage inbox latest --page-id PAGE_ID --limit 10
fbpage inbox reply --conversation-id ID --message "Nội dung" --dry-run
```

Yêu cầu kỹ thuật:

- Có `--dry-run` cho lệnh ghi.
- Có JSON output nếu Hermes cần parse.
- Không in token ra stdout/stderr.
- Lỗi thiếu quyền phải rõ.
- Sau khi đăng/trả lời, connector phải verify bằng API.

## 9. Graph API calls cần implement

### Liệt kê Page

```http
GET https://graph.facebook.com/v20.0/me/accounts?fields=id,name,access_token,tasks
Authorization: Bearer USER_OR_SYSTEM_TOKEN
```

### Đăng bài text

```http
POST https://graph.facebook.com/v20.0/{page-id}/feed
message=...
access_token=PAGE_ACCESS_TOKEN
```

### Đăng ảnh

```http
POST https://graph.facebook.com/v20.0/{page-id}/photos
caption=...
source=@image.jpg
access_token=PAGE_ACCESS_TOKEN
```

Khuyến nghị resize ảnh về cạnh dài 1080–1200px, JPEG chất lượng 80–90.

### Verify bài mới nhất

```http
GET https://graph.facebook.com/v20.0/{page-id}/posts?fields=id,message,permalink_url,created_time&limit=3
```

### Đọc comment

```http
GET https://graph.facebook.com/v20.0/{post-id}/comments?fields=id,from,message,created_time,comment_count&limit=25
```

### Reply comment

```http
POST https://graph.facebook.com/v20.0/{comment-id}/comments
message=...
access_token=PAGE_ACCESS_TOKEN
```

## 10. Setup Messenger inbox

Chỉ làm sau khi post/comment đã chạy ổn.

### Trong App Dashboard

1. Thêm product **Messenger**.
2. Thêm product **Webhooks**.
3. Cấu hình callback URL HTTPS.
4. Cấu hình verify token.
5. Subscribe Page vào app.
6. Subscribe fields:
   - messages
   - messaging_postbacks
   - message_deliveries nếu cần
   - message_reads nếu cần

### Webhook verify

Backend cần endpoint:

```text
GET /webhooks/meta?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...
```

Nếu verify token đúng, trả về `hub.challenge`.

### Nhận Messenger event

```text
POST /webhooks/meta
```

Backend cần:

- Verify signature nếu có.
- Parse event.
- Dedupe message id.
- Không xử lý message do Page/bot tự gửi nếu không cần.
- Đưa event vào queue/job cho Hermes.

### Gửi Messenger reply

Dùng Messenger Send API với Page access token. Cần tuân thủ chính sách nhắn tin của Meta, đặc biệt khung 24h.

## 11. Cài Hermes skill/command

Tạo skill generic, ví dụ `facebook-page-admin`.

Skill nên quy định:

1. Đọc Page/comment/inbox: gọi connector read-only.
2. Ghi post/comment/reply: mặc định dry-run/draft trước.
3. Nếu user dùng command explicit, ví dụ `/facebook-auto`, tổ chức có thể coi là approval nếu policy đã định nghĩa rõ.
4. Không yêu cầu user paste token vào chat.
5. Không lưu token/private inbox vào memory.
6. Verify bằng API rồi mới báo thành công.

Command gợi ý:

| Command | Chức năng | Mặc định |
|---|---|---|
| /facebook-connect-status | Kiểm tra kết nối | Read-only |
| /facebook-pages | Liệt kê Page khả dụng | Read-only |
| /facebook-latest | Xem bài mới nhất | Read-only |
| /facebook-post | Draft/đăng bài text | Draft trước |
| /facebook-photo-post | Đăng bài kèm ảnh | Dry-run/approval |
| /facebook-auto | Tạo ảnh + caption + đăng | Theo policy explicit |
| /facebook-comments | Đọc comment | Read-only |
| /facebook-reply | Reply comment | Dry-run trước |
| /facebook-inbox | Đọc inbox mới | Read-only |
| /facebook-draft-replies | Draft phản hồi inbox | Draft |
| /facebook-send-reply | Gửi Messenger reply | Cần duyệt |

## 12. Guardrail bắt buộc

### Với bài viết/comment public

- Không đăng nếu user chưa yêu cầu rõ hoặc chưa duyệt.
- Luôn dry-run khi nội dung có rủi ro.
- Không tự cam kết giá/chính sách nếu không có dữ liệu trong KB.
- Verify sau khi đăng/trả lời.

### Với inbox private

- Mặc định chỉ draft.
- Không auto-reply khiếu nại, hoàn tiền, pháp lý, tài chính, y tế, dữ liệu cá nhân.
- Có escalation sang người thật.
- Có dedupe để tránh trả lời trùng.
- Không lưu toàn bộ inbox vào long-term memory.

### Với secret

- Không paste token vào chat.
- Không commit `.env`.
- Không in token ra log.
- Không đưa token vào prompt hoặc memory.
- Rotate token nếu nghi ngờ đã lộ.

## 13. Checklist nghiệm thu end-to-end

### Business/App

- [ ] Có Meta Business.
- [ ] Page đã nằm trong Business hoặc user có quyền admin Page.
- [ ] Meta App đã tạo.
- [ ] App gắn đúng Business.
- [ ] Use cases/products đúng: Login, Messenger/Webhooks nếu cần.
- [ ] OAuth redirect URL đúng.
- [ ] Permissions đã chọn đúng.

### Token

- [ ] OAuth flow hoặc System User token đã tạo.
- [ ] Token lấy được Page qua `/me/accounts`.
- [ ] Page ID đúng.
- [ ] Token lưu ngoài repo.
- [ ] Connector không in token.

### Post/comment

- [ ] Đọc latest post OK.
- [ ] Đăng text test OK.
- [ ] Đăng photo test OK.
- [ ] Verify permalink OK.
- [ ] Đọc comment OK.
- [ ] Reply comment dry-run OK.
- [ ] Reply comment live sau duyệt OK.

### Messenger nếu cần

- [ ] Webhook verify OK.
- [ ] Page subscribed webhook OK.
- [ ] Nhận message event OK.
- [ ] Dedupe message id OK.
- [ ] Draft reply OK.
- [ ] Send reply sau duyệt OK.

### Hermes

- [ ] Skill được load.
- [ ] Command gọi đúng connector.
- [ ] Lỗi thiếu quyền hiển thị rõ.
- [ ] Không có secret trong output.
- [ ] Có verify sau khi ghi.

## 14. Lỗi thường gặp

| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| `/me/accounts` không có Page | User/system user chưa được gán Page hoặc thiếu `pages_show_list` | Gán asset/reconnect |
| Token có Page nhưng không đăng được | Thiếu `pages_manage_posts` hoặc token không phải Page token | Xin quyền/generate lại token |
| Không đọc comment | Thiếu `pages_read_engagement` | Xin quyền/reconnect |
| Không reply comment | Thiếu `pages_manage_engagement` | Xin quyền/reconnect |
| Webhook verify fail | Verify token sai hoặc callback không trả challenge | Sửa endpoint verify |
| Không nhận inbox | Chưa subscribe Page, thiếu `pages_messaging`, app chưa review | Subscribe/review/quyền đúng |
| Tin nhắn gửi bị chặn | Ngoài chính sách 24h hoặc permission thiếu | Kiểm tra messaging policy |
| AI trả lời sai | Không có KB/FAQ, auto quá rộng | Draft + approval + bổ sung KB |

## 15. Khuyến nghị triển khai theo phase

### Phase 1 — Page posting

- Meta Business + App
- Token
- Đăng bài text/photo
- Verify permalink
- Hermes command đăng bài

### Phase 2 — Comment ops

- Đọc comment
- Draft reply
- Reply comment sau duyệt
- Safe auto-reply dry-run

### Phase 3 — Messenger inbox

- Messenger product
- Webhook
- Inbox queue
- Draft reply
- Send reply sau duyệt

### Phase 4 — Autopilot

- Lịch đăng
- Phân loại comment/inbox
- Auto-reply intent an toàn
- Dashboard giám sát
- Audit log