Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

docs(integrations): add telegram setup guide

Tin9c03e8d9037e
diff --git a/apps/docs/core/integrations/outgoing-webhooks.mdx b/apps/docs/core/integrations/outgoing-webhooks.mdx
index 6c0392fa1..ff624201e 100644
--- a/apps/docs/core/integrations/outgoing-webhooks.mdx
+++ b/apps/docs/core/integrations/outgoing-webhooks.mdx
@@ -1,9 +1,9 @@
---
title: Outgoing webhooks
-description: Send task activity from a Kaneo project to Slack, Discord, or any HTTP endpoint. Configure per-project notifications and optional signing.
+description: Send task activity from a Kaneo project to Slack, Discord, Telegram, or any HTTP endpoint. Configure per-project notifications and optional signing.
---
-Kaneo can notify external systems when tasks change in a project. Each integration is per project and uses an incoming webhook URL from the service you connect (Slack, Discord) or your own HTTP listener (generic webhook).
+Kaneo can notify external systems when tasks change in a project. Each integration is per project and uses either an incoming webhook URL from the service you connect (Slack, Discord), a bot token plus chat ID (Telegram), or your own HTTP listener (generic webhook).
<Info>
These integrations are outgoing only: Kaneo posts to your URL when events occur. They are separate from [GitHub integration](/core/integrations/github/setup), which syncs issues and repositories.
@@ -15,15 +15,13 @@ These integrations are outgoing only: Kaneo posts to your URL when events occur.
2. Under **Projects**, select the project.
3. Open the **Integrations** tab.
-You will see sections for **GitHub**, **Discord**, **Generic webhook**, and **Slack**. Configure Slack, Discord, or generic webhooks in their respective sections.
-
## Task links in notifications
Notification messages and generic webhook payloads include links to the task in the web app. Set [`KANEO_CLIENT_URL`](/core/installation/environment-variables) to your public Kaneo web URL so those links point to your instance (for example `https://kaneo.example.com`).
## Events you can subscribe to
-For Slack, Discord, and generic webhooks you can toggle the same event types:
+For Slack, Discord, Telegram, and generic webhooks you can toggle the same event types:
| Event | Default on | Description |
| --- | --- | --- |
@@ -54,6 +52,22 @@ Create an incoming webhook for a Discord channel (Channel settings → Integrati
(or the `discordapp.com` hostname). Paste it into the Discord section, optionally add a channel name label, select events, and save.
+## Telegram
+
+Create a Telegram bot with [`@BotFather`](https://t.me/BotFather), then add that bot to the destination chat, group, channel, or topic. Telegram requires:
+
+- A bot token
+- A chat ID
+- Optionally a topic thread ID for forum-style group topics
+
+To find the chat ID, send a message in the destination and open:
+
+`https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
+
+Look for `message.chat.id` or `channel_post.chat.id`. If you are posting into a forum topic, also copy `message.message_thread_id`.
+
+Paste those values into the Telegram section, optionally add a chat label, choose events, and save.
+
## Generic HTTP webhook
Use a generic webhook when you want a JSON POST to your own service, automation, or middleware.
diff --git a/apps/docs/core/integrations/telegram.mdx b/apps/docs/core/integrations/telegram.mdx
new file mode 100644
index 000000000..c6fa92056
--- /dev/null
+++ b/apps/docs/core/integrations/telegram.mdx
@@ -0,0 +1,110 @@
+---
+title: Telegram
+description: Send task notifications from Kaneo to a Telegram chat or topic using a bot token and chat ID.
+---
+
+Kaneo can post task activity to Telegram whenever events occur in a project. Unlike Slack and Discord, Telegram uses a bot token plus a chat ID instead of an incoming webhook URL.
+
+## Create a Telegram bot
+
+1. Open Telegram and start a chat with [`@BotFather`](https://t.me/BotFather).
+2. Send `/newbot` and follow the prompts.
+3. Copy the bot token that BotFather returns. It will look like:
+
+```
+123456789:AAExampleBotToken1234567890
+```
+
+<Warning>
+Treat the bot token like a password. Anyone with the token can send messages as your bot.
+</Warning>
+
+## Add the bot to your destination
+
+Add the bot to the private chat, group, supergroup, or channel where you want notifications.
+
+- For a personal chat: start a conversation with the bot and send any message.
+- For a group or supergroup: add the bot, then send a message in that chat.
+- For a channel: add the bot as an administrator if needed so it can post updates.
+- For forum-style supergroups: add the bot to the group and note the topic you want to post into.
+
+## Find the chat ID
+
+1. After adding the bot, send at least one message in the destination chat.
+2. Open this URL in your browser, replacing `BOT_TOKEN` with your real token:
+
+```
+https://api.telegram.org/botBOT_TOKEN/getUpdates
+```
+
+3. Look for one of these fields in the JSON response:
+
+- Private chat or group: `message.chat.id`
+- Channel: `channel_post.chat.id`
+- Topic/thread in a forum group: use the same chat ID, and also copy `message.message_thread_id`
+
+Typical values look like:
+
+```json
+{
+ "message": {
+ "chat": {
+ "id": -1001234567890
+ },
+ "message_thread_id": 42
+ }
+}
+```
+
+<Info>
+If `getUpdates` returns an empty result, send a fresh message in Telegram and reload the URL. If you see a `404`, double-check that the URL format is exactly `https://api.telegram.org/bot&lt;token&gt;/getUpdates`.
+</Info>
+
+## Connect Telegram in Kaneo
+
+1. Open **Settings** in the sidebar.
+2. Under **Projects**, select the project you want to connect.
+3. Open the **Integrations** tab.
+4. Expand the **Telegram** section.
+5. Paste your bot token.
+6. Enter the chat ID.
+7. Optionally enter a topic thread ID if you want messages posted into a specific Telegram forum topic.
+8. Optionally add a chat label for your own reference.
+9. Choose which events to subscribe to.
+10. Click **Connect Telegram**.
+
+Once connected you can enable or disable the integration with the toggle, update event subscriptions, rotate the bot token, or disconnect entirely.
+
+## Supported events
+
+| Event | Default | Description |
+| --- | --- | --- |
+| Task created | On | A new task is created in the project |
+| Task status changed | On | A task moves to a different status column |
+| Task priority changed | Off | A task's priority is changed |
+| Task title changed | Off | A task's title is edited |
+| Task description changed | Off | A task's description is edited |
+| Task comment created | On | A new comment is added to a task |
+
+You can change these toggles at any time in the integration settings.
+
+## Message format
+
+Kaneo sends formatted Telegram messages with:
+
+- The event title
+- A direct link to the task in Kaneo
+- Project, status, and priority details
+- The name of the user who triggered the event when available
+
+Make sure [`KANEO_CLIENT_URL`](/core/installation/environment-variables) is set to your public Kaneo URL so task links work correctly.
+
+## Updating credentials
+
+To rotate the bot token after connecting, paste a new token in the bot token field and click **Save Changes**. If you leave the token field empty, Kaneo keeps the currently stored token.
+
+You can also update the chat ID, thread ID, label, and event subscriptions at any time.
+
+## Disconnecting
+
+Click Disconnect to remove the integration. This deletes the stored Telegram configuration for that project. You can reconnect at any time with a new bot token and chat ID.
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 116386f78..044353fb2 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -84,6 +84,7 @@
"pages": [
"core/integrations/discord",
"core/integrations/slack",
+ "core/integrations/telegram",
"core/integrations/outgoing-webhooks"
]
},