> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lukan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Connect Lukan to Telegram via the Bot API for messaging and pipeline approvals.

The Telegram plugin connects Lukan to Telegram using the Bot API with long polling. No public URL or webhook setup needed.

## Setup

```bash theme={null}
# Install the plugin
lukan plugin install telegram

# Set your bot token (from @BotFather)
lukan tg config set botToken "YOUR_BOT_TOKEN"

# Start the plugin
lukan plugin start telegram
```

### Getting a Bot Token

1. Open Telegram and message [@BotFather](https://t.me/BotFather)
2. Send `/newbot` and follow the prompts
3. Copy the bot token

## Configuration

| Field           | Description                            |
| --------------- | -------------------------------------- |
| `botToken`      | Telegram Bot API token from @BotFather |
| `whitelist`     | Allowed user IDs (empty = allow all)   |
| `allowedGroups` | Allowed group/chat IDs                 |
| `prefix`        | Command prefix filter (e.g. `/ai`)     |

## Commands

| Command                         | Description                    |
| ------------------------------- | ------------------------------ |
| `lukan tg config`               | View/edit plugin configuration |
| `lukan plugin start telegram`   | Start the plugin               |
| `lukan plugin stop telegram`    | Stop the plugin                |
| `lukan plugin restart telegram` | Restart the plugin             |

## Tools

The agent has access to these Telegram-specific tools when running via the plugin:

* **TelegramSend** — Send text messages
* **TelegramSendMedia** — Send photos, documents, audio, video
* **TelegramGetChats** — List chats with message history
* **TelegramReadMessages** — Read message history from a chat
* **TelegramGetChatInfo** — Get chat metadata

## Pipeline Approvals

Telegram works as a notification channel for pipeline approval gates. Set `telegram` as the notification plugin and use the numeric chat ID as the channel.

Chat IDs are negative for groups (e.g. `-1001234567890`) and positive for private chats.