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

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	Exposes plugin to Kaneo's loader with name and validator
Config validation	apps/api/src/plugins/telegram/config.ts	Validates botToken and chatId before enabling
Event dispatch	apps/api/src/plugins/telegram/events.ts	Listens for Kaneo events and forwards to Telegram
Telegram client	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	CRUD endpoints for integration management
Controller logic	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, 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:

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.

Step 4: Update or Delete Your Integration

Updating Configuration

Use updateTelegramIntegration from apps/web/src/fetchers/telegram-integration/update-telegram-integration.ts to modify settings:

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:

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:

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.

How Event Notifications Work

Once configured, the system in 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
4. The client POSTs to Telegram's Bot API
5. Errors are logged via console.error on line 185 of 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 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 → client.ts → Telegram Bot API

The Telegram plugin leverages Kaneo's existing plugin framework for consistent validation in config.ts, reliable HTTP calls in 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, 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. 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}