pancake-skills

# pancake-skills

## Mục tiêu

Skill này cung cấp khả năng tương tác với Pancake Platform API - nền tảng quản lý bán hàng đa kênh. Hỗ trợ đầy đủ các thao tác:

- **Pages**: Liệt kê pages, tạo page access token
- **Conversations**: Quản lý hội thoại, gán tags, assign staff, đánh dấu read/unread
- **Messages**: Lấy lịch sử tin nhắn, gửi tin nhắn (inbox, reply comment, private reply)
- **Customers**: Quản lý khách hàng, thêm/sửa/xóa notes
- **Statistics**: Thống kê ads, engagement, page, tags, users
- **Tags**: Liệt kê tags của page
- **Posts**: Liệt kê bài viết
- **Users**: Quản lý staff, cấu hình round robin
- **Upload**: Upload media content
- **Chat Plugin**: Gửi tin nhắn qua chat plugin

## Thiết lập môi trường (bắt buộc)

**User API** (endpoints `/api/v1/pages`):
- `USER_ACCESS_TOKEN`: Token cá nhân, lấy từ **Account → Personal Settings**. Có hiệu lực 90 ngày.

**Page API** (endpoints `/api/public_api/v1` và `/api/public_api/v2`):
- `PAGE_ACCESS_TOKEN`: Token của page, lấy từ **Settings → Tools**. Không hết hạn trừ khi xóa/renew.

**Tuỳ chọn**:
- `PANCAKE_BASE_URL`: Mặc định `https://pages.fm`
- `CONFIRM_WRITE`: Set `YES` để cho phép thao tác ghi (POST/PUT/DELETE)

## Cách gọi nhanh

Script gợi ý: `scripts/pancake.sh`

### Ví dụ GET

```bash
# Liệt kê pages (User API)
export USER_ACCESS_TOKEN="***"
bash scripts/pancake.sh pages-list

# Liệt kê conversations của page (Page API)
export PAGE_ACCESS_TOKEN="***"
bash scripts/pancake.sh conversations-list 123456789

# Lọc conversations theo tags và type
bash scripts/pancake.sh conversations-list 123456789 "?tags=1,2&type=INBOX"

# Lấy tin nhắn trong conversation
bash scripts/pancake.sh messages-list 123456789 conv_abc123

# Liệt kê tags
bash scripts/pancake.sh tags-list 123456789

# Liệt kê staff
bash scripts/pancake.sh users-list 123456789

# Thống kê page (SINCE/UNTIL là Unix timestamp)
bash scripts/pancake.sh stats-page 123456789 1704067200 1706745600
```

### Ví dụ WRITE

```bash
export PAGE_ACCESS_TOKEN="***"
export CONFIRM_WRITE=YES

# Gửi tin nhắn inbox
echo '{"action":"reply_inbox","message":"Xin chào!"}' | \
  bash scripts/pancake.sh messages-send 123456789 conv_abc123

# Gửi tin nhắn với attachment (dùng content_ids từ upload API)
echo '{"action":"reply_inbox","content_ids":["xxx"]}' | \
  bash scripts/pancake.sh messages-send 123456789 conv_abc123

# Reply comment
echo '{"action":"reply_comment","message_id":"comment123","message":"Cảm ơn bạn!"}' | \
  bash scripts/pancake.sh messages-send 123456789 conv_abc123

# Private reply từ comment
echo '{"action":"private_replies","post_id":"post123","message_id":"comment123","message":"Inbox nhé!"}' | \
  bash scripts/pancake.sh messages-send 123456789 conv_abc123

# Thêm tag vào conversation
echo '{"action":"add","tag_id":"123"}' | \
  bash scripts/pancake.sh conversations-tag 123456789 conv_abc123

# Gỡ tag khỏi conversation
echo '{"action":"remove","tag_id":"123"}' | \
  bash scripts/pancake.sh conversations-tag 123456789 conv_abc123

# Assign staff vào conversation
echo '{"assignee_ids":["user-uuid-1","user-uuid-2"]}' | \
  bash scripts/pancake.sh conversations-assign 123456789 conv_abc123

# Đánh dấu conversation đã đọc
bash scripts/pancake.sh conversations-read 123456789 conv_abc123

# Cập nhật thông tin khách hàng
echo '{"changes":{"name":"Nguyễn Văn A","gender":"male","birthday":"1990-01-15"}}' | \
  bash scripts/pancake.sh customers-update 123456789 customer_uuid

# Thêm ghi chú cho khách hàng
echo '{"message":"Khách hàng VIP, ưu tiên hỗ trợ"}' | \
  bash scripts/pancake.sh customers-add-note 123456789 customer_uuid

# Upload file
bash scripts/pancake.sh upload 123456789 /path/to/image.jpg

# Cập nhật round robin users
echo '{"inbox":["user-uuid-1"],"comment":["user-uuid-2"]}' | \
  bash scripts/pancake.sh users-round-robin 123456789
```

## Guardrails

- Không ghi dữ liệu khi chưa set `CONFIRM_WRITE=YES`
- Với thao tác ghi: luôn chạy 1 lệnh GET trước để xác nhận ID/shape dữ liệu
- Không lưu access token vào repo
- **QUAN TRỌNG**: Khi gửi message, `message` và `content_ids` là **MUTUALLY EXCLUSIVE** - không được gửi cả hai cùng lúc

## Endpoint thuộc skill này

### User API (`https://pages.fm/api/v1`)
- `GET /pages` - Liệt kê pages
- `POST /pages/{page_id}/generate_page_access_token` - Tạo page access token

### Page API v2 (`https://pages.fm/api/public_api/v2`)
- `GET /pages/{page_id}/conversations` - Liệt kê conversations

### Page API v1 (`https://pages.fm/api/public_api/v1`)

**Conversations:**
- `POST /pages/{page_id}/conversations/{conversation_id}/tags` - Thêm/xóa tag
- `POST /pages/{page_id}/conversations/{conversation_id}/assign` - Assign staff
- `POST /pages/{page_id}/conversations/{conversation_id}/read` - Đánh dấu đã đọc
- `POST /pages/{page_id}/conversations/{conversation_id}/unread` - Đánh dấu chưa đọc

**Messages:**
- `GET /pages/{page_id}/conversations/{conversation_id}/messages` - Lấy tin nhắn
- `POST /pages/{page_id}/conversations/{conversation_id}/messages` - Gửi tin nhắn

**Customers:**
- `GET /pages/{page_id}/page_customers` - Liệt kê khách hàng
- `PUT /pages/{page_id}/page_customers/{page_customer_id}` - Cập nhật khách hàng
- `POST /pages/{page_id}/page_customers/{page_customer_id}/notes` - Thêm ghi chú
- `PUT /pages/{page_id}/page_customers/{page_customer_id}/notes` - Sửa ghi chú
- `DELETE /pages/{page_id}/page_customers/{page_customer_id}/notes` - Xóa ghi chú

**Statistics:**
- `GET /pages/{page_id}/statistics/pages_campaigns` - Thống kê chiến dịch quảng cáo
- `GET /pages/{page_id}/statistics/ads` - Thống kê quảng cáo
- `GET /pages/{page_id}/statistics/customer_engagements` - Thống kê tương tác
- `GET /pages/{page_id}/statistics/pages` - Thống kê page
- `GET /pages/{page_id}/statistics/tags` - Thống kê tags
- `GET /pages/{page_id}/statistics/users` - Thống kê users

**Other:**
- `GET /pages/{page_id}/tags` - Liệt kê tags
- `GET /pages/{page_id}/posts` - Liệt kê bài viết
- `GET /pages/{page_id}/users` - Liệt kê users
- `POST /pages/{page_id}/round_robin_users` - Cập nhật round robin
- `GET /pages/{page_id}/sip_call_logs` - Lấy lịch sử cuộc gọi
- `GET /pages/{page_id}/export_data` - Export dữ liệu
- `POST /pages/{page_id}/upload_contents` - Upload media

### Chat Plugin (`https://pages.fm/api/v1`)
- `POST /pke_chat_plugin/messages` - Gửi tin nhắn qua chat plugin
- `GET /pke_chat_plugin/messages` - Lấy tin nhắn chat plugin

## Tham chiếu

- OpenAPI spec: `references/openapi-pancake.yaml`
- Xem chi tiết parameters và response schema trong file OpenAPI