Tích hợp grammY (Telegram Bot API)

Tại sao dùng grammY

  • Client Bot API ưu tiên TypeScript với các helper tích hợp sẵn cho long-poll + webhook, middleware, xử lý lỗi, rate limiter.
  • Các helper xử lý media gọn gàng hơn so với việc tự viết fetch + FormData; hỗ trợ tất cả các method của Bot API.
  • Dễ mở rộng: hỗ trợ proxy qua custom fetch, session middleware (tùy chọn), context type-safe.

Những gì đã triển khai

  • Single client path: Đã loại bỏ implementation dựa trên fetch; giờ grammY là client Telegram duy nhất (send + gateway) với grammY throttler được bật mặc định.
  • Gateway: monitorTelegramProvider tạo một grammY Bot, kết nối mention/allowlist gating, tải media xuống qua getFile/download, và gửi reply bằng sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument. Hỗ trợ long-poll hoặc webhook qua webhookCallback.
  • Proxy: tùy chọn channels.telegram.proxy sử dụng undici.ProxyAgent thông qua client.baseFetch của grammY.
  • Hỗ trợ Webhook: webhook-set.ts bao bọc setWebhook/deleteWebhook; webhook.ts host callback với health check + graceful shutdown. Gateway bật chế độ webhook khi channels.telegram.webhookUrl + channels.telegram.webhookSecret được thiết lập (nếu không thì dùng long-poll).
  • Sessions: Chat trực tiếp được gộp vào agent main session (agent:<agentId>:<mainKey>); nhóm dùng agent:<agentId>:telegram:group:<chatId>; reply được route về cùng channel.
  • Config knobs: channels.telegram.botToken, channels.telegram.dmPolicy, channels.telegram.groups (allowlist + mention defaults), channels.telegram.allowFrom, channels.telegram.groupAllowFrom, channels.telegram.groupPolicy, channels.telegram.mediaMaxMb, channels.telegram.linkPreview, channels.telegram.proxy, channels.telegram.webhookSecret, channels.telegram.webhookUrl.
  • Draft streaming: tùy chọn channels.telegram.streamMode sử dụng sendMessageDraft trong private topic chats (Bot API 9.3+). Cái này tách biệt với channel block streaming.
  • Tests: grammy mocks bao gồm DM + group mention gating và outbound send; vẫn cần thêm các fixture cho media/webhook.

Các câu hỏi còn mở

  • Các plugin grammY tùy chọn (throttler) nếu gặp Bot API 429s.
  • Thêm các test có cấu trúc cho media (stickers, voice notes).
  • Làm cho webhook listen port có thể cấu hình được (hiện tại cố định ở 8787 trừ khi được kết nối qua gateway).