Telegram
Telegram bot integration
git clone https://github.com/bijectionhq/telegram.git
cd telegram
git checkout 1337ee1addde1af50e535abe94baf5a0af0bd9f7Bijection repository access is required. Request access.
Description
Telegram bot integration
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/telegram. Based on Re11oy/convex-telegram. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
A Telegram bot component for Convex: send messages via the typed Bot API and receive updates through a verified webhook.
Explore the demo ↗Upstream overview
From the upstream package documentation.
convex-telegram is a Convex component that wraps the Telegram Bot API with a fully typed client built on @gramio/types. It provides both outbound messaging via bot.api.* from Convex actions and inbound update handling via a registered HTTP webhook route. The component manages webhook registration, secret verification, and typed update dispatching so you can focus on bot logic rather than API plumbing.
Use cases
From the upstream package documentation.
- Building a Telegram bot that sends notifications or alerts to users from Convex actions triggered by database changes or scheduled functions
- Receiving and processing user messages or callback queries in a Convex backend without managing webhook infrastructure manually
- Echoing, logging, or storing incoming Telegram messages in a Convex database with typed update payloads
- Creating interactive bots that respond to inline keyboard callback queries with full type safety across the Telegram update object
- Adding Telegram as a communication channel to an existing Convex application without standing up a separate bot service
How it works
From the upstream package documentation.
The component exposes a TelegramBot class that you instantiate with a reference to the mounted component and optionally a token, webhook secret, and webhook path. The bot token is read from the TELEGRAM_BOT_TOKEN environment variable by default. Once instantiated, bot.api gives you a typed proxy over every method in the Telegram Bot API, callable from any Convex action.
To receive updates, you call registerRoutes in your convex/http.ts file. This registers an HTTP route (defaulting to /telegram/webhook) that the component uses to accept and verify incoming Telegram updates. The component checks the X-Telegram-Bot-Api-Secret-Token header against a stored hash, using either your TELEGRAM_WEBHOOK_SECRET env var or a generated secret if unset.
Update routing is handler-based. You pass a handlers object to registerRoutes where keys correspond to fields on the Telegram update object such as message or callback_query. An optional onUpdate handler runs before any specific handler. After deploying the HTTP route, you call bot.setupWebhook() once from a Convex action to register your CONVEX_SITE_URL-based webhook URL with Telegram, along with the allowed update types.
The package also ships a test helper compatible with convex-test so you can register the component in unit tests without a real deployment.
Upstream package FAQ
How does convex-telegram verify incoming webhook requests from Telegram?
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.
Do I need to host a separate server to use Telegram webhooks with Convex?
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.
Which Telegram Bot API methods does convex-telegram support?
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.
How do I configure the webhook URL if my deployment uses a custom domain?
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.
Can I test convex-telegram bot logic without a live Telegram connection?
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Telegram with Bijection.
Read: https://bijection.com/components/telegram/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from Re11oy/convex-telegram, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
convex-telegram
A Convex component for integrating Telegram Bot API through typed API client based on @gramio/types.
What you can do
- Send messages (and call any Bot API method) with the typed
bot.api.*client. - Receive updates (messages, callback queries, …) by registering a webhook route and handling typed updates.
Installation
pnpm add convex-telegram
# or: npm install convex-telegram
Setup
1. Create a bot and set the token
Create a bot with @BotFather (docs) to get a token, then set it on your deployment:
npx convex env set TELEGRAM_BOT_TOKEN <your-bot-token>
2. Add the component
convex/convex.config.ts:
import { defineApp } from "convex/server";
import telegram from "convex-telegram/convex.config";
const app = defineApp();
app.use(telegram);
export default app;
3. Create the bot client
convex/telegram.ts:
import { TelegramBot } from "convex-telegram";
import { components } from "./_generated/api";
export const bot = new TelegramBot(components.telegram);
You can now send messages. To also receive messages, register a webhook.
Sending messages
Call any Bot API method
through bot.api from a Convex action or webhook handler:
import { action } from "./_generated/server";
import { v } from "convex/values";
import { bot } from "./telegram";
export const sendMessage = action({
args: { chatId: v.union(v.string(), v.float64()), text: v.string() },
returns: v.null(),
handler: async (_ctx, args) => {
await bot.api.sendMessage({ chat_id: args.chatId, text: args.text });
return null;
},
});
Receiving messages
To receive updates you register an HTTP route and point Telegram at it.
1. Configure a webhook secret (optional)
npx convex env set TELEGRAM_WEBHOOK_SECRET <random-string>
The component always verifies the X-Telegram-Bot-Api-Secret-Token header. Set
this to control the secret yourself; when unset, setupWebhook generates one and
incoming requests are verified against its stored hash.
2. Register the webhook route
convex/http.ts:
import { httpRouter } from "convex/server";
import { registerRoutes } from "convex-telegram";
import { components } from "./_generated/api";
import { bot } from "./telegram";
const http = httpRouter();
registerRoutes(http, components.telegram, {
handlers: {
message: async (_ctx, update) => {
await bot.api.sendMessage({
chat_id: update.message.chat.id,
text: "Thanks for the message.",
});
},
},
});
export default http;
The route defaults to /telegram/webhook.
3. Point Telegram at your deployment
Run setupWebhook once after deploying the HTTP route:
import { action } from "./_generated/server";
import { v } from "convex/values";
import { bot } from "./telegram";
export const setupWebhook = action({
args: {},
returns: v.object({ botUsername: v.string(), webhookUrl: v.string() }),
handler: async () => {
return await bot.setupWebhook({
allowedUpdates: ["message", "callback_query"],
});
},
});
setupWebhook uses CONVEX_SITE_URL to build the webhook URL:
https://<deployment>.convex.site/telegram/webhook
Pass url to setupWebhook if your public webhook URL is not based on
CONVEX_SITE_URL.
Handler keys match fields on the
Telegram update object (message,
callback_query, …). onUpdate runs for every update before specific handlers.
API Reference
TelegramBot
const bot = new TelegramBot(components.telegram, {
token: "...", // optional, defaults to TELEGRAM_BOT_TOKEN
webhookSecret: "...", // optional, defaults to TELEGRAM_WEBHOOK_SECRET
webhookPath: "/telegram/webhook",
});
| Method | Description |
|---|---|
bot.api | Typed Bot API client |
bot.setupWebhook() | Calls Telegram setWebhook, returns { botUsername, webhookUrl } |
bot.deleteWebhook() | Calls Telegram deleteWebhook |
registerRoutes
registerRoutes(http, components.telegram, {
webhookPath: "/telegram/webhook",
onUpdate: async (ctx, update) => { ... },
handlers: { message: async (ctx, update) => { ... } },
});
Example
A runnable, backend-only example lives in example/. It installs
the component, echoes incoming messages, and stores them in a messages table.
See example/README.md to run it against a Convex
deployment.
Testing
Use the package test helper to register the component in
convex-test:
import telegram from "convex-telegram/test";
telegram.register(t);
Development
This repo runs the example app against an anonymous local Convex backend (no account required), which also regenerates component types on change.
pnpm install
pnpm dev # run the example app and rebuild the component on change
Run the same checks as CI:
pnpm build
pnpm test
pnpm typecheck
pnpm lint
See CONTRIBUTING.md for details.