> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Telegram integration

A **Telegram integration** connects a workspace to a Telegram bot. Once connected, messages sent to the bot are answered by the workspace's assistant. A workspace has at most one Telegram integration.

## What the API exposes

`GET /v1/workspaces/{workspaceId}/integrations/telegram` returns a redacted status:

| Field         | Meaning                                                      |
| ------------- | ------------------------------------------------------------ |
| `connected`   | Whether Telegram is set up. `{ connected: false }` when not. |
| `botUsername` | The bot's public username.                                   |
| `botUserId`   | The bot's Telegram user id.                                  |
| `botUrl`      | The public deep link to the bot (`https://t.me/<username>`). |

> **Warning**
>
> The **bot token and webhook secret are never returned** by the API — only the bot's public identity above.

## Connecting

1. Create a bot with Telegram's [BotFather](https://t.me/BotFather) and copy its **bot token**.
2. Connect it to the workspace, passing the token in the `botToken` field:

   ```
   PUT /v1/workspaces/{workspaceId}/integrations/telegram
   ```

   ```json
   { "botToken": "123456789:AAExampleBotTokenFromBotFather" }
   ```

   The body has a single required field, **`botToken`** (string) — the bot token from BotFather. The token is validated during connection and is never returned.

Connecting is **idempotent**: because a workspace has at most one Telegram integration, calling this again **replaces** the existing one and re-registers the webhook — useful for rotating a bot token.

## Disconnecting

`DELETE /v1/workspaces/{workspaceId}/integrations/telegram` disconnects the bot from the workspace.