Telegram Mini App

Mini App là một dạng "app trong Telegram" — chạy như web app nhưng thừa hưởng ngữ cảnh người dùng Telegram (đã xác thực, theme, language). KOPA Mini App cho phép bạn làm gần đầy đủ thao tác KOPA mà không cần mở browser.

Khi nào dùng Mini App (vs Bot)#

Việc	Bot	Mini App
Duyệt đơn giản 1-tap	✅ Tốt nhất	OK
Sửa bút toán trước khi duyệt	❌	✅ Tốt nhất
Xem báo cáo tài chính	⚠ PDF dài	✅ Tốt nhất
Soạn tin AI dài	❌	✅ Tốt nhất
Số liệu nhanh	✅ Tốt nhất	OK
Xử lý bulk	❌	✅

Tóm tắt: Bot cho 80% việc nhanh hằng ngày. Mini App cho 20% còn lại cần UI đầy đủ — mà bạn vẫn không cần mở browser.

Mở Mini App#

Có 4 cách:

1. Từ tin nhắn Bot — mọi nút như 🔍 Xem, ✏ Sửa, 📊 Dashboard đều mở Mini App.
2. Từ menu Bot — bấm icon menu góc trái ô soạn tin → chọn "Open KOPA".
3. Từ command — gõ /app hoặc /dashboard để mở trang tương ứng.
4. Từ deep link — paste https://t.me/KopaApprovalBot/app?startapp=accounting vào Telegram.

Anatomy Mini App#

Mini App chiếm khoảng 75% chiều cao Telegram (có thể full-screen). Cấu trúc:

Header#

• KOPA logo + tên workspace.
• Period selector.
• Nút đóng (X).

Tab bar (dưới)#

• 🏠 Home — dashboard rút gọn.
• 📋 Pending — đề xuất chờ duyệt.
• 📊 Reports — báo cáo nhanh.
• 💬 Chat — cowork chat với AI.
• ⚙ More — cài đặt + cảnh báo + KPI.

Khu vực chính#

Tùy tab.

Tab Home#

Dashboard rút gọn, scroll vertical:

┌─────────────────────────┐
│ Cash position           │
│ 3.6 tỉ  ▲ 5%            │
└─────────────────────────┘

┌─────────────────────────┐
│ Runway                  │
│ 24 tháng  🟢 Healthy    │
└─────────────────────────┘

┌─────────────────────────┐
│ Pending approvals       │
│ 3 đề xuất               │
│ [Xem hết →]             │
└─────────────────────────┘

┌─────────────────────────┐
│ Active alerts           │
│ 1 Warning, 0 Danger     │
│ [Xem chi tiết →]        │
└─────────────────────────┘

Bấm vào card → drill xuống.

Tab Pending#

Liệt kê đầy đủ đề xuất chờ duyệt:

• Filter theo loại (bút toán / tờ khai / email).
• Sort theo ưu tiên (high-risk, sắp hết hạn, lớn nhất).
• Bulk select để duyệt nhiều cùng lúc.

Mở chi tiết một đề xuất#

Tap vào dòng → màn hình chi tiết:

• Tab Tổng quan — bút toán, đối tượng, số tiền.
• Tab Căn cứ — điều khoản kế toán áp dụng, chứng từ gốc (preview ảnh/PDF).
• Tab Lịch sử — bút toán tương tự gần nhất.
• Tab Sửa — form chỉnh tài khoản nợ/có/số tiền/diễn giải.

Dưới cùng là 3 nút: Duyệt / Sửa rồi duyệt / Từ chối.

Sửa trong Mini App#

Form Sửa có:

• Dropdown tài khoản với search + autocomplete từ CoA.
• Số tiền với calculator inline nếu cần phân bổ.
• Ngày — date picker.
• Diễn giải — textarea.
• Đính kèm chứng từ — upload từ Telegram file picker.

Bấm Lưu rồi duyệt → audit log ghi: "User edited proposal then approved via Telegram Mini App".

Tab Reports#

Truy cập nhanh báo cáo phổ biến:

• 💰 Bảng cân đối kế toán — tháng hiện tại.
• 💵 P&L — tháng / quý / YTD.
• 🏦 Cash flow — tuần / tháng.
• 📈 KPI Watchlist — top 10 KPI.
• 🚨 Alerts — list active alerts.

Tap để mở viewer:

• PDF preview inline (scroll trang).
• Nút Download → lưu vào Telegram cloud chat hoặc share ra ngoài.
• Nút Email → KOPA gửi PDF cho người chỉ định.

Tab Chat#

Cowork chat ngay trong Telegram — gần như đầy đủ tính năng web:

• Composer với attach file/ảnh, slash command.
• Streaming response.
• Tool calls hiển thị inline.
• Trace panel (rút gọn hơn web).
• Lịch sử session 30 ngày gần nhất.

Khác biệt so với chat full-screen web:

• Không có image-paste từ clipboard (Telegram giới hạn).
• Voice input dùng Telegram voice message thay native browser.
• Trace panel rút gọn — drill xuống thì mở Mini App full-screen.

Tab More#

Menu các tính năng phụ:

• 🔔 Alerts — quản lý cảnh báo.
• 📉 KPI editor — chỉnh target KPI.
• 🔄 Connectors — re-auth nhanh khi token hết hạn.
• ⚙ Settings — DND, notification preferences.
• 🌐 Switch workspace — đổi workspace nếu có nhiều.
• ❓ Help — link tới docs này.
• 🚪 Sign out — đăng xuất khỏi Telegram session (giữ Bot link).

Authentication#

Mini App tự xác thực qua Telegram WebApp init data:

• Telegram client gửi signed init data tới KOPA backend.
• KOPA verify signature bằng Bot token (ngăn spoofing).
• Match Telegram user ID với KOPA user (đã link trước đó).
• Tạo session ngắn hạn (1 giờ, refresh tự động).

Bạn không cần đăng nhập lại — đã đăng nhập Telegram là vào Mini App.

Theme#

Mini App tự match theme Telegram:

• Nếu Telegram dark mode → Mini App dark.
• Nếu Telegram light → Mini App light.
• Accent color match Telegram setting.

Mini App không có toggle theme riêng (theo guideline Telegram).

Bảo mật#

Init data#

Mỗi request từ Mini App tới KOPA backend có WebApp init data:

auth_date=1714128000
hash=a1b2c3...
user={"id":12345,"username":"mai_nguyen",...}

KOPA verify hash với Bot token. Nếu mismatch → reject ngay (HTTP 401).

CSP#

Mini App load trong iframe Telegram. CSP của KOPA chỉ cho phép:

• script-src self + Telegram webapp script.
• frame-ancestors chỉ Telegram domain.
• connect-src self + KOPA API.

Block iframe load từ domain khác.

Session timeout#

Session Mini App 1 giờ, refresh tự động khi user active. Nếu không active 1 giờ → close, mở lại sẽ verify Telegram init data lại.

Hạn chế Mini App vs Web full#

Mini App không có:

• Multi-tab — Telegram chỉ cho 1 instance Mini App tại thời điểm.
• Drag-and-drop file phức tạp — Telegram WebApp API hạn chế.
• Print PDF trực tiếp — phải share qua Telegram chat hoặc export ra ngoài.
• Một số quick action keyboard shortcut (ví dụ ⌘ K command palette).
• Full Agent Console — Designer/DAG canvas cần screen rộng.

Cho mọi việc trên: deep link sang web (Bot luôn cung cấp link).

Performance#

Mini App load nhanh:

• Initial bundle ~ 280KB gzipped.
• First paint < 800ms trên 4G.
• Time to interactive < 1.5s.
• Tận dụng Telegram cache — load lại trong session là từ cache.

Đa ngôn ngữ#

Mini App tự match locale Telegram:

• Telegram tiếng Việt → Mini App vi.
• Telegram English → Mini App en.
• Khác → fallback en.

User có thể override trong Tab More → Language.

Self-hosted Mini App (Enterprise)#

Bot self-hosted (xem Telegram Bot — chi tiết) sẽ tự động có Mini App riêng — chỉ cần:

1. Cấu hình Mini App URL trong @BotFather.
2. Trỏ về subdomain workspace, ví dụ https://miniapp-saomai.getkopa.com.
3. KOPA tự CSP + signed deploy.

Mini App có thể có logo riêng, theme riêng, welcome message riêng — phù hợp doanh nghiệp lớn cần brand consistency.

Sự cố thường gặp#

Mini App không mở (chỉ hiện loading mãi)#

Nguyên nhân: Telegram cache cũ.

Giải pháp:

• Telegram → Settings → Advanced → Clear local cache.
• Hoặc: nhắn /app lại sau 5 phút.

"Authentication failed"#

Nguyên nhân: Bot token không match (sau khi rotate).

Giải pháp: Trong KOPA web, Cài đặt → Thông báo → Telegram → Hủy liên kết → Liên kết lại.

Mini App quá chậm#

Nguyên nhân: Workspace có nhiều dữ liệu, latency tới Telegram CDN.

Giải pháp:

• KOPA caches mạnh hơn cho Mini App, tránh refresh không cần.
• Enterprise có thể self-host Mini App ở edge gần user.

Tiếp theo#

• Telegram Bot — chi tiết — bot commands & inline approval.
• Hàng đợi duyệt (HITL) — luồng duyệt.
• API & MCP — tổng quan — xây Mini App tùy biến qua API.