Cloudflare Workers Telegram Bot Platform

A Cloudflare Worker + Telegram bot that serves a dynamic, hierarchical (multi-level) reply keyboard to users and allows admins to manage buttons, send media, and broadcast messages. It persists user / button state in a Cloudflare KV namespace and serves a small static frontend that can call the management API.

Features

Dynamic nested reply keyboard (top-level + sub-buttons)
Markdown-like authoring converted to Telegram-safe HTML
Media attachments (photo, document, sticker) with captions
Broadcast endpoint for messages or media
Admin authentication through chat ID allowlist
Automatic refresh of keyboards on CRUD operations
Per-user data commands: /save, /get, /update, /delete
Webhook-based (no polling) for responsiveness
Vitest test setup scaffold

Architecture Overview

Cloudflare Worker (src/index.js)
  ├─ /webhook (Telegram updates)
  ├─ /api/auth (admin auth)
  ├─ /api/buttons (CRUD nested buttons)
  ├─ /api/broadcast (push to all users)
  ├─ Static assets (served via ASSETS binding)
  └─ KV (USER_DATA) for buttons + user state

Data Model (KV)

buttons → recursive tree of button objects. user_<chatId>_started marks onboarding. user_<chatId> arbitrary saved data. user_<chatId>_last_keyboard_msg cleanup metadata.

API Reference

Endpoint	Method	Purpose
/api/auth	POST	Validate admin chat ID
/api/buttons	GET/POST	List / create buttons
/api/buttons/:id	GET/PUT/DELETE	CRUD single button
/api/broadcast	POST	Broadcast message/media
/webhook	POST	Telegram update handler

Environment

TELEGRAM_BOT_TOKEN (secret)
ADMIN_IDS (comma separated chat IDs)
KV Namespace: USER_DATA

Extensibility Ideas

Reordering buttons
Nested deletion recursion
Richer formatting / sanitizer
Rate limiting & metrics
Additional media types (audio/video)

License

MIT