Cấu hình Telegram

Telegram là kênh chat thật đầu tiên sau terminal chat. Bot chạy local bằng long polling và mặc định chỉ cho owner sử dụng.

Thiết lập

Chạy helper:

bestie channels telegram setup

Helper sẽ hỏi owner id hoặc username và bot token. Nếu bạn để trống prompt owner, Bestie sẽ thử phát hiện owner từ tin nhắn mới nhất không phải bot gửi tới bot Telegram. Hãy gửi một tin nhắn cho bot trước, rồi chạy setup.

Bạn cũng có thể phát hiện owner sau khi setup:

bestie channels telegram whoami

whoami đọc các update gần đây của bot và in numeric id, username nếu có, cùng giá trị channels.telegram.ownerUserId có thể dùng trong config.

Hoặc cấu hình thủ công trong .bestie/config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenEnv": "BESTIE_TELEGRAM_BOT_TOKEN",
      "ownerUserId": "123456789"
    }
  }
}

Thêm token vào .bestie/.env:

BESTIE_TELEGRAM_BOT_TOKEN=123456:bot-token-here

Không commit .bestie/.env.

Chạy bot

bestie channels telegram

Chạy một vòng update để smoke/debug:

bestie channels telegram --once

Để chạy nền, dùng daemon manager:

bestie daemon start --channel telegram
bestie daemon status --channel telegram

Xem Chạy Bestie trong nền để biết cách restart, stop, xử lý stale state và hành vi systemd service.

Transcript logging

Để smoke test và debug integration, ghi transcript JSONL local:

bestie channels telegram --once --transcript .bestie/logs/telegram-smoke.jsonl

Transcript logging ghi lại polling, outbound messages, chat actions, metadata file đính kèm, lượt tải attachment, chỉnh sửa progress message, và gửi voice/audio khi các flow đó chạy.

Các định danh như chat id, file id và Telegram file path được hash trong transcript entry. Dù vậy, vẫn hãy xem transcript là dữ liệu chẩn đoán local: chúng có thể tiết lộ timing, message flow, kích thước file và chi tiết vận hành.

Slash commands

/start - phản hồi readiness cho owner.
/help - danh sách lệnh.
/status - tóm tắt trạng thái local, không lộ secrets.
/doctor - tóm tắt Doctor.
/memory hoặc /memory list - trạng thái hoặc tóm tắt memory gần đây.
/memory pending - hàng chờ memory cần duyệt.
/memory pending inspect <id> - xem chi tiết một pending memory.
/memory pause và /memory resume - tạm dừng hoặc bật lại memory.
/approvals - xem action approvals đang chờ.
/approve <id> và /deny <id> - ghi nhận quyết định owner. Nền tảng hiện tại ghi nhận quyết định nhưng chưa thực thi action đã được approve.

Slash command không được hỗ trợ sẽ trả về fallback ngắn thay vì chuyển vào LLM.

Attachments

Telegram có thể tải file vào .bestie/workspace/telegram/..., kèm caption, metadata và preview giới hạn cho file text-like.

Mặc định quan trọng:

downloadPolicy: allow
maxBytes: 20971520
parseMaxBytes: 5242880
visionPolicy: deny
transcriptionPolicy: deny

Nội dung upload luôn là untrusted. Bestie chỉ đọc sâu hơn qua local read tools khi policy cho phép.

Tool progress

Khi một lượt Telegram dùng tools, Bestie nên chỉnh sửa một progress message thay vì spam chat. Final answer sẽ thay thế progress message khi có thể.

Progress text nên hướng tới người dùng, ví dụ:

Miu đang xem danh sách tệp trong src/cli
Miu đang tìm tệp khớp *.md trong docs
Miu đang gom tài liệu Markdown từ src

Tên tool nội bộ không nên lộ ra chat Telegram.

Verification checklist

npm run build
npm run smoke
npm run smoke:doctor:exit-code
bestie channels telegram whoami
bestie channels telegram --once
bestie channels telegram

Sau đó gửi /start, /help, /status, /doctor, /memory, /memory pending, approval commands khi có pending approvals, và một tin nhắn bình thường từ owner.

Tin nhắn từ Telegram user khác phải bị bỏ qua.

Voice không còn chỉ thuộc Telegram

Telegram vẫn là channel adapter cho chat và bot interactions. Tuy nhiên voice hiện là capability riêng của Bestie. Nếu Telegram bot hỗ trợ voice messages, hãy xem đó là Telegram chuyển audio vào voice pipeline, không phải Telegram sở hữu toàn bộ voice system.

Docs Telegram nên tập trung vào bot setup, webhook/polling, commands và quyền riêng của channel. Behavior voice dùng lại nên nằm trong voice guide.