# How to Set Up the Telegram Plugin for Notifications in Kaneo: A Complete Guide

> Easily set up Telegram notifications in Kaneo. Follow our complete guide to integrate your bot, get your token and chat ID, and configure alerts for seamless project updates.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-06

---

**To set up Telegram notifications in Kaneo, create a Telegram bot via @BotFather, obtain your bot token and chat ID, then configure the integration through the project's Integrations page or API endpoints.**

Kaneo's **Telegram plugin** provides native, project-level notification capabilities fully integrated into its plugin architecture. This guide walks through the complete configuration process, from bot creation to API implementation, with direct references to the source code in `usekaneo/kaneo`.

## Understanding the Telegram Plugin Architecture

The Telegram notification system spans four layers: plugin registration, configuration validation, event dispatch, and API routes. Each layer has dedicated source files that handle specific responsibilities.

| Layer | Key File | Purpose |
|-------|----------|---------|
| Plugin registration | [`apps/api/src/plugins/telegram/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/index.ts) | Exposes plugin to Kaneo's loader with name and validator |
| Config validation | [`apps/api/src/plugins/telegram/config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/config.ts) | Validates `botToken` and `chatId` before enabling |
| Event dispatch | [`apps/api/src/plugins/telegram/events.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/events.ts) | Listens for Kaneo events and forwards to Telegram |
| Telegram client | [`apps/api/src/plugins/telegram/client.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/client.ts) | Calls `POST https://api.telegram.org/bot<token>/sendMessage` |
| API routes | [`apps/api/src/telegram-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/telegram-integration/index.ts) | CRUD endpoints for integration management |
| Controller logic | [`apps/api/src/telegram-integration/controllers/telegram-controller.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/telegram-integration/controllers/telegram-controller.ts) | Business logic for each endpoint |

The data flow works as follows: when a user creates an integration via the UI, `useCreateTelegramIntegration` calls `createTelegramIntegration`, which POSTs to `/api/projects/:projectId/telegram-integration`. The route validates with `validateTelegramConfig` from [`config.ts`](https://github.com/usekaneo/kaneo/blob/main/config.ts), stores the record, and the event dispatcher later reads this config to send messages via `postToTelegram` in the client.

## Step 1: Create Your Telegram Bot

Before configuring Kaneo, you need a Telegram bot:

1. Open Telegram and message **@BotFather**
2. Send `/newbot` and follow prompts to name your bot
3. Copy the **bot token** (format: `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)

Keep this token secure—it grants full access to your bot.

## Step 2: Obtain Your Chat ID

You need a destination chat for notifications:

1. Add your bot to a group or channel
2. Send a test message in that chat
3. Visit `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates` in your browser
4. Look for `"chat":{"id":-1001234567890` — the negative number is your **chat ID**

For channels, the ID typically starts with `-100`. For groups, it may be a smaller negative number.

## Step 3: Configure the Telegram Integration in Kaneo

### Via the Web UI

1. Navigate to your project's **Integrations** page in Kaneo
2. Select **Telegram**
3. Enter your **Bot Token** and **Chat ID**
4. Optionally enable/disable specific events (e.g., task created, comment added)
5. Save — the UI uses `useCreateTelegramIntegration` which triggers the POST endpoint

### Via the API

For programmatic setup, use the fetcher pattern implemented in [`apps/web/src/fetchers/telegram-integration/create-telegram-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/fetchers/telegram-integration/create-telegram-integration.ts):

```typescript
import createTelegramIntegration, {
  type CreateTelegramIntegrationRequest,
} from "@/fetchers/telegram-integration/create-telegram-integration";

const requestBody: CreateTelegramIntegrationRequest = {
  botToken: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
  chatId: "-1001234567890",
  enabledEvents: ["taskCreated", "commentAdded"],
};

await createTelegramIntegration("project-abc123", requestBody);

```

The implementation posts to `/api/projects/:projectId/telegram-integration` with validation handled by `validateTelegramConfig` in [`apps/api/src/plugins/telegram/config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/config.ts).

## Step 4: Update or Delete Your Integration

### Updating Configuration

Use `updateTelegramIntegration` from [`apps/web/src/fetchers/telegram-integration/update-telegram-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/fetchers/telegram-integration/update-telegram-integration.ts) to modify settings:

```typescript
import updateTelegramIntegration, {
  type UpdateTelegramIntegrationRequest,
} from "@/fetchers/telegram-integration/update-telegram-integration.ts";

const updateBody: UpdateTelegramIntegrationRequest = {
  botToken: "new-token-if-changed",
  chatId: "-1009876543210",
  enabledEvents: ["taskCreated"], // disabling other events
};

await updateTelegramIntegration("project-abc123", updateBody);

```

### Removing the Integration

Delete via [`apps/web/src/fetchers/telegram-integration/delete-telegram-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/fetchers/telegram-integration/delete-telegram-integration.ts):

```typescript
import deleteTelegramIntegration from "@/fetchers/telegram-integration/delete-telegram-integration";

await deleteTelegramIntegration("project-abc123");

```

## Using React Hooks for Telegram Integration

Kaneo provides TanStack Query hooks for convenient UI integration. The query hook lives in [`apps/web/src/hooks/queries/telegram-integration/use-get-telegram-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/hooks/queries/telegram-integration/use-get-telegram-integration.ts):

```tsx
import { useGetTelegramIntegration } from "@/hooks/queries/telegram-integration/use-get-telegram-integration";
import { useCreateTelegramIntegration } from "@/hooks/mutations/telegram-integration/use-telegram-integration";

function TelegramSettings({ projectId }: { projectId: string }) {
  const { data: integration, isLoading } = useGetTelegramIntegration(projectId);
  const { mutate: create } = useCreateTelegramIntegration();

  const handleSave = (token: string, chatId: string) => {
    create({ botToken: token, chatId, enabledEvents: ["taskCreated"] });
  };

  // Render UI based on integration state
}

```

Mutations (create, update, delete) are consolidated in [`apps/web/src/hooks/mutations/telegram-integration/use-telegram-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/hooks/mutations/telegram-integration/use-telegram-integration.ts).

## How Event Notifications Work

Once configured, the system in [`apps/api/src/plugins/telegram/events.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/events.ts) listens for internal Kaneo events. When a supported event fires:

1. The dispatcher checks if the integration has that event enabled in `enabledEvents`
2. It constructs a message payload
3. Calls `postToTelegram` from [`apps/api/src/plugins/telegram/client.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/client.ts)
4. The client POSTs to Telegram's Bot API
5. Errors are logged via `console.error` on line 185 of [`events.ts`](https://github.com/usekaneo/kaneo/blob/main/events.ts)

## Verifying Your Setup

After saving your integration, Kaneo performs a verification read (`GET`) as implemented in [`apps/api/src/telegram-integration/controllers/telegram-controller.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/telegram-integration/controllers/telegram-controller.ts) at line 136. If the bot can successfully post, you'll receive a test message in the configured chat.

## Summary

- **Create a bot** via @BotFather and secure your token
- **Get your chat ID** through the Bot API or helper bots
- **Configure via UI** using the Integrations page or **programmatically** via the fetcher APIs
- **Manage integrations** through standard CRUD operations in `apps/web/src/fetchers/telegram-integration/`
- **Event notifications** flow through [`events.ts`](https://github.com/usekaneo/kaneo/blob/main/events.ts) → [`client.ts`](https://github.com/usekaneo/kaneo/blob/main/client.ts) → Telegram Bot API

The Telegram plugin leverages Kaneo's existing plugin framework for consistent validation in [`config.ts`](https://github.com/usekaneo/kaneo/blob/main/config.ts), reliable HTTP calls in [`client.ts`](https://github.com/usekaneo/kaneo/blob/main/client.ts), and proper error handling throughout the stack.

## Frequently Asked Questions

### What events can trigger Telegram notifications in Kaneo?

According to [`apps/api/src/plugins/telegram/config.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/config.ts), the Telegram plugin supports events including `taskCreated`, `taskUpdated`, `taskDeleted`, `commentAdded`, and `commentUpdated`. You can selectively enable these through the `enabledEvents` array when creating or updating your integration.

### Where is the Telegram Bot API call implemented in Kaneo's source code?

The actual HTTP call to Telegram is in [`apps/api/src/plugins/telegram/client.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/client.ts). The `postToTelegram` function constructs a POST request to `https://api.telegram.org/bot<token>/sendMessage` with the message payload and returns the parsed response.

### Can I use the same Telegram bot for multiple Kaneo projects?

Yes. Each project maintains its own Telegram integration record in the database. You can reuse the same `botToken` across different projects with different `chatId` values, or even the same chat if desired. The controller in [`apps/api/src/telegram-integration/controllers/telegram-controller.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/telegram-integration/controllers/telegram-controller.ts) scopes all operations by `projectId`.

### How do I troubleshoot failed Telegram notifications?

Check the server logs for errors from `console.error` on line 185 of [`apps/api/src/plugins/telegram/events.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/telegram/events.ts). Common issues include invalid bot tokens (401 from Telegram), incorrect chat IDs (400 bad request), or the bot lacking permissions in a channel. Verify your configuration via `useGetTelegramIntegration` and test with a direct API call to Telegram's `getUpdates` endpoint.