# Documentation Page **Page:** kit/agent/chat-apps/telegram [Download Raw Markdown](./kit/agent/chat-apps/telegram.md) --- # Connect your Bot to Telegram Talk to your Bot from Telegram, as one of its [chat apps](/kit/agent/chat-apps/). It takes one token from @BotFather and one code in a direct message. You need a Telegram account and a Bot. The examples use the Bot `chief`. ## Step 1: Create the Telegram bot 1. In Telegram, open a chat with **@BotFather** and send `/newbot`. 2. Pick a display name, then a username that ends in `bot`. 3. BotFather answers with a token like `123456789:AAE…`. Copy it. Treat it like a password. Turn privacy off: send `/setprivacy` to @BotFather, pick your bot, then **Disable**. With privacy on, Telegram passes the bot only commands and replies to its own messages in a group, not mentions. Telegram applies the change only when the bot joins a group: if the bot is already in a group, remove it from that group and add it again. ## Step 2: Connect it to your Bot The agent checks the token with Telegram before it saves anything. The token is never shown again. 1. In the Hub, open **Bots**, select your Bot and open the **Chat apps** tab. 2. Choose **Add a chat app**, pick **Telegram** and choose **Next**. Paste the token into **Bot token** and press **Connect**. 3. The app opens on its setup. Under **Become its owner**, press **Owner code** to make the code, then go to [Step 3](#step-3-become-the-owner). 1. Open the **Bots** tab, select your Bot and open **⇄ Connect**. 2. Under **Chat apps**, choose **[ + Add chat app ]**, then **Telegram**. 3. Paste the token into **Bot token** (a **Name** is optional) and choose **✓ Add**. The agent checks it ("Checking the token…"). 4. The owner code appears on screen. Go to [Step 3](#step-3-become-the-owner). ```bash hoody agent bots channels create -c "$COMPUTER_ID" --id chief --kind telegram --label "My Telegram" --bot-token "$TELEGRAM_BOT_TOKEN" --idempotency-key telegram-chief-1 ``` Pass the bot token with `--bot-token`. ```ts import { HoodyClient } from 'hoody-sdk'; const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const box = await hoody.withComputer(process.env.COMPUTER_ID!); const { data } = await box.agent.bots.channels.create( 'chief', { kind: 'telegram', label: 'My Telegram', token: process.env.TELEGRAM_BOT_TOKEN! }, { idempotencyKey: 'telegram-chief-1' }, ); console.log(data.id, data.enrolment?.code); ``` ```bash curl -X POST "https://$PROJECT_ID-$COMPUTER_ID-agent-1.$SERVER.computers.hoody.com/api/v1/agent/bots/chief/channels" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: telegram-chief-1" \ -d "{\"kind\": \"telegram\", \"label\": \"My Telegram\", \"token\": \"$TELEGRAM_BOT_TOKEN\"}" ``` The answer (shortened): ```json { "id": "ch_1a2b3c4d", "kind": "telegram", "label": "My Telegram", "state": "awaiting_owner", "needs_owner": true, "identity": { "platform_id": "123456789", "name": "Chief", "username": "chief_hoody_bot" }, "enrolment": { "code": "7KQ4M9TX", "expires_at": "2026-10-15T10:15:00Z", "instructions": "Send 7KQ4M9TX to @chief_hoody_bot in a direct message before 2026-10-15T10:15:00Z." } } ``` The `enrolment` block is in this answer only. Send the same create again with the same `Idempotency-Key` and you get the same chat app back, not a second one. | Refused with | Why | What to do | |---|---|---| | `channel_credentials_invalid`, `reason` `unauthorized` | The token is wrong or was revoked | Copy it again, whole, from @BotFather | | `channel_credentials_invalid`, `reason` `unreachable` | Telegram could not be reached | Try again | | `channel_conflict`, reason `webhook_set` | The bot already sends its updates to a webhook. Nothing is removed unless you ask | Send the create again with `"delete_webhook": true` (CLI `--delete-webhook`), or in the agent's TUI, paste the bot token again, then choose **Remove the webhook and continue**. In the Hub, tick **Remove the bot's webhook if it has one** under **Options** when adding the app, or use **Remove the webhook** in its setup | ## Step 3: Become the owner Open a direct message with your bot (search its username in Telegram). Send the owner code as the only text: ```text /start 7KQ4M9TX ``` `7KQ4M9TX` alone, `pair 7KQ4M9TX` or `/pair 7KQ4M9TX` work too. The bot answers that you are paired. The chat app's state turns to `connected`. Now write to it. Your message reaches your Bot, and its answer comes back here. The code works for 15 minutes by default. If it expired, make a new owner code (see [Become the owner](/kit/agent/chat-apps/#become-the-owner)). ## Let other people talk to the Bot Anyone you pair can read the Bot's answers in their conversation with it. Pair only people you would let read it. With the default `dm_policy: owner`, only owners can talk to the Bot. To add someone by user ID, change it to `allowlist` or `pairing`; to use a pairing code, change it to `pairing`. Update it with `hoody agent bots channels update -c "$COMPUTER_ID" --id chief --channel-id ch_1a2b3c4d --settings-dm-policy POLICY`, replacing `POLICY` with your choice, or use `PATCH …/channels/ch_1a2b3c4d` with `{"settings": {"dm_policy": "POLICY"}}`. Then add people one of two ways: - **With a code** (`dm_policy: pairing`): make a pairing code (`POST …/channels/ch_1a2b3c4d/pairing`, or `hoody agent bots channels pairing create`) and give it to the person. They send it to the bot in a direct message. - **By user id** (`allowlist` is enough): add them with their numeric Telegram user id (`POST …/channels/ch_1a2b3c4d/principals`, or `hoody agent bots channels principals add --platform-user`). In the Hub, open **Bots**, select your Bot, open **Chat apps** and choose **Manage** on the Telegram app. Under **Settings**, set **Who can talk in direct messages** to **People I add** or **Anyone with an invite code from me**, then choose **Save settings**. Under **People**, choose **Add a person** to add someone by their **User ID in Telegram**. To make an invite code, first save **Anyone with an invite code from me**, then open **People** and use **Invite someone** and **Create invite code**. Every policy and both ways in are explained in [Let someone else in](/kit/agent/chat-apps/#let-someone-else-in) on the overview page, and rights in [People and rights](/kit/agent/chat-apps/#people-and-rights). ## Use the Bot in a group Every member of an approved group can read what the Bot answers there. 1. Turn privacy off at @BotFather (see [Step 1](#step-1-create-the-telegram-bot)), or make the bot an admin of the group. 2. Add the bot to the group. If it was in the group before you turned privacy off, remove it and add it again. 3. A paired person with the `control` right sends `/bind@your_bot` in the group. 4. Approve the group one of four ways: in the TUI; with the **Approve** button in the direct message the bot sends each owner when a group asks; in the Hub under **Bots**, your Bot, **Chat apps**, **Manage**, then **Chats**, using **Approve** and **Approve group**; or with `PATCH …/chats/{chat}` and `{"state": "approved", "acknowledge_group_readers": true}`. `{chat}` is the chat's `id` in the chat app's `chats` list (`chat_…`). Telegram's own id of the group is in the chat's `platform_chat`. For a group it is a negative number, such as `-100123456789`. ## Telegram commands, formatting and limits - Commands use `/`: `/status`, `/stop`, `/bind`, `/unbind`, `/help`. Running `/status`, `/stop`, `/bind` and `/unbind` takes the `control` right; `/help` answers anyone. What each does is in [Chat commands](/kit/agent/chat-apps/#chat-commands). - Rich answers use Telegram's HTML formatting (`parse_mode`). Set `format: plain` for plain text. - One answer part holds at most 4096 UTF-16 code units, including formatting markup (`part_chars`); some characters count as two units. A longer answer is sent in up to 8 parts by default (`max_parts`, 1 to 20); past that it is cut. - Run one Telegram bot from one place. If another program reads the same bot, both fail and the state shows `conflict`. ## Advanced - **Replace the bot token.** After you revoke the old token at @BotFather, the chat app shows `auth_failed`. Give it the new token with `hoody agent bots channels credentials set -c "$COMPUTER_ID" --id chief --channel-id ch_1a2b3c4d --bot-token "$TELEGRAM_BOT_TOKEN"`. The command requires `--bot-token`. HTTP: [credentials on the Bot chat channels API page](/api/agent/bots/channels/#credentials). - **Read the setup steps from the agent.** `GET …/channels/setup?kind=telegram` returns the steps for creating the bot at @BotFather and names the credentials the create needs. See [setup on the Bot chat channels API page](/api/agent/bots/channels/#channels). - **Change how the chat app behaves.** Rate limits, reply style, language, approval cards and every other setting, with defaults and ranges, are in the [chat app settings reference](/kit/agent/chat-apps/settings/). ## What's next - [Decide approvals from Telegram](/kit/agent/chat-apps/approvals/): the Bot stops before a risky step and asks in the chat - [Fix a chat app that does not answer](/kit/agent/chat-apps/troubleshooting/) - [Every chat channel operation on the API page](/api/agent/bots/channels/)