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

# 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

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