---
name: bijection-telegram
description: "Evaluate and integrate the Telegram component with Bijection."
---

# Telegram

Telegram bot integration

- Package: @bijectionhq/telegram
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/telegram/tree/1337ee1addde1af50e535abe94baf5a0af0bd9f7
- Upstream: https://github.com/Re11oy/convex-telegram/tree/9935b4cc115ee8e8199d699fd562e2d34fb0b7a4
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/telegram

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/telegram.git
cd telegram
git checkout 1337ee1addde1af50e535abe94baf5a0af0bd9f7
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-telegram. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Telegram Bot. Follow the installation and configuration steps exactly.

# Telegram Bot

## Instructions

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.

### Installation

```bash
npm install convex-telegram
```

Current npm version: `convex-telegram@0.1.2`

## Use cases

- 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

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Telegram Bot is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-telegram)
- [GitHub repository](https://github.com/Re11oy/convex-telegram)
- [Live demo](https://convex-telegram.vercel.app/)
- [Convex Components Directory](https://www.convex.dev/components/convex-telegram)
- [Convex documentation](https://docs.convex.dev)