forked from Selig/openclaw-skill
Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
27 lines
2.3 KiB
Markdown
27 lines
2.3 KiB
Markdown
# grammY
|
|
|
|
## grammY Integration (Telegram Bot API)
|
|
|
|
## Why grammY
|
|
|
|
- TS-first Bot API client with built-in long-poll + webhook helpers, middleware, error handling, rate limiter
|
|
- Cleaner media helpers than hand-rolling fetch + FormData; supports all Bot API methods
|
|
- Extensible: proxy support via custom fetch, session middleware (optional), type-safe context
|
|
|
|
## What We Shipped
|
|
|
|
- **Single client path:** fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default
|
|
- **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`
|
|
- **Proxy:** optional `channels.telegram.proxy` uses `undici.ProxyAgent` through grammY's `client.baseFetch`
|
|
- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` are set (otherwise it long-polls)
|
|
- **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same 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:** optional `channels.telegram.streamMode` uses `sendMessageDraft` in private topic chats (Bot API 9.3+). This is separate from channel block streaming
|
|
- **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome
|
|
|
|
## Open Questions
|
|
|
|
- Optional grammY plugins (throttler) if we hit Bot API 429s
|
|
- Add more structured media tests (stickers, voice notes)
|
|
- Make webhook listen port configurable (currently fixed to 8787 unless wired through the gateway)
|