convex-telegram adds a typed Telegram Bot API client and webhook handling to Convex, so you can send messages and receive updates without separate webhook infra
npm install convex-telegramThis Telegram component integrates Telegram bots into your Convex app. It gives you a fully typed Telegram Bot API client for sending messages and calling any Bot API method directly from your Convex functions, plus webhook handling for receiving incoming updates. The component registers your bot's webhook and verifies the secret token on every incoming update before handing it to your handler — so you can build Telegram bots without standing up separate webhook infrastructure.
## Use cases
- Send Telegram notifications from Convex actions when events happen, such as new signups, completed jobs, or alerts
- Build two-way bots that reply to incoming messages and callback queries with typed handlers
- Handle slash commands and inline keyboard buttons directly inside Convex functions
- Call any Telegram Bot API method, such as sendPhoto, editMessageText, or answerCallbackQuery, with full TypeScript types
- Add Telegram-based notification or verification flows without hosting a separate webhook server
## How it works
The component requires a Telegram bot token and a webhook secret. You instantiate a bot client in your Convex functions and call methods through a typed `bot.api.*` proxy (e.g. `bot.api.sendMessage(...)`), which issues the request straight to the Telegram Bot API. To receive updates, you register the bot's webhook — the component stores the bot's settings along with a hashed secret — and it exposes an HTTP route that checks each incoming update's secret token against that hash before dispatching it to your handler.
With convex-telegram, you instantiate a TelegramBot client using your Convex component reference and call bot.api.sendMessage or any other Bot API method directly from a Convex action. The client is fully typed via @gramio/types, so you get autocomplete and compile-time checks on all parameters. No external server or HTTP client setup is required.
convex-telegram exposes a registerRoutes function that adds a webhook HTTP route to your Convex HTTP router. You pass typed handlers for update types like message and callback_query, and the component verifies the X-Telegram-Bot-Api-Secret-Token header on every incoming request before dispatching to your handler. Run the setupWebhook action once after deployment to point Telegram at your Convex site URL.
registerRoutes accepts a handlers object whose keys match Telegram update object fields, including message and callback_query. Each handler receives a typed update, so you can inspect the message text for slash commands or read callback_query.data for inline button payloads and respond using bot.api methods like answerCallbackQuery or editMessageText.
convex-telegram integrates as a Convex component, meaning the webhook endpoint runs on your existing Convex deployment under convex.site. You add the component in convex.config.ts, set TELEGRAM_BOT_TOKEN as a Convex environment variable, register routes in your HTTP router, and call setupWebhook once. There is no separate process or server to maintain.
convex-telegram checks the X-Telegram-Bot-Api-Secret-Token header on every incoming update against a stored hash of the webhook secret. If you set TELEGRAM_WEBHOOK_SECRET, that value is used. If you do not, setupWebhook generates a secret automatically and stores its hash. Requests that fail verification are rejected before reaching your handler.
No. convex-telegram registers the webhook endpoint directly in your Convex HTTP router via registerRoutes. The endpoint runs on your Convex deployment's convex.site domain. You run the setupWebhook action once to register that URL with Telegram, and the component handles everything from there.
convex-telegram exposes the full Telegram Bot API through the bot.api proxy, typed via the @gramio/types package. Any method listed in the Telegram Bot API reference, such as sendMessage, sendPhoto, editMessageText, or answerCallbackQuery, can be called through bot.api with TypeScript types for all parameters and return values.
By default, setupWebhook builds the webhook URL from the CONVEX_SITE_URL environment variable, producing a URL like https://<deployment>.convex.site/telegram/webhook. If your public webhook URL differs from CONVEX_SITE_URL, you can pass a url option directly to the setupWebhook call to override it.
Yes. convex-telegram ships a test helper that integrates with the convex-test package. You import telegram from convex-telegram/test and call telegram.register(t) in your test setup to register the component, allowing you to run and assert on bot logic in the convex-test environment without making real Telegram API calls.