Connect your Bot to Telegram
Section titled “Connect your Bot to Telegram”Talk to your Bot from Telegram, as one of its 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
Section titled “Step 1: Create the Telegram bot”- In Telegram, open a chat with @BotFather and send
/newbot. - Pick a display name, then a username that ends in
bot. - BotFather answers with a token like
123456789:AAE…. Copy it. Treat it like a password.
Step 2: Connect it to your Bot
Section titled “Step 2: Connect it to your Bot”The agent checks the token with Telegram before it saves anything. The token is never shown again.
- In the Hub, open Bots, select your Bot and open the Chat apps tab.
- Choose Add a chat app, pick Telegram and choose Next. Paste the token into Bot token and press Connect.
- The app opens on its setup. Under Become its owner, press Owner code to make the code, then go to Step 3.
- Open the Bots tab, select your Bot and open ⇄ Connect.
- Under Chat apps, choose [ + Add chat app ], then Telegram.
- Paste the token into Bot token (a Name is optional) and choose ✓ Add. The agent checks it (“Checking the token…”).
- The owner code appears on screen. Go to Step 3.
hoody agent bots channels create -c "$COMPUTER_ID" --id chief --kind telegram --label "My Telegram" --bot-token "$TELEGRAM_BOT_TOKEN" --idempotency-key telegram-chief-1Pass the bot token with --bot-token.
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);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):
{ "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
Section titled “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:
/start 7KQ4M9TX7KQ4M9TX 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).
Let other people talk to the Bot
Section titled “Let other people talk to the Bot”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, orhoody agent bots channels pairing create) and give it to the person. They send it to the bot in a direct message. - By user id (
allowlistis enough): add them with their numeric Telegram user id (POST …/channels/ch_1a2b3c4d/principals, orhoody 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 on the overview page, and rights in People and rights.
Use the Bot in a group
Section titled “Use the Bot in a group”- Turn privacy off at @BotFather (see Step 1), or make the bot an admin of the group.
- Add the bot to the group. If it was in the group before you turned privacy off, remove it and add it again.
- A paired person with the
controlright sends/bind@your_botin the group. - 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’sidin the chat app’schatslist (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
Section titled “Telegram commands, formatting and limits”- Commands use
/:/status,/stop,/bind,/unbind,/help. Running/status,/stop,/bindand/unbindtakes thecontrolright;/helpanswers anyone. What each does is in Chat commands. - Rich answers use Telegram’s HTML formatting (
parse_mode). Setformat: plainfor 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
Section titled “Advanced”- Replace the bot token. After you revoke the old token at @BotFather, the chat app shows
auth_failed. Give it the new token withhoody 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. - Read the setup steps from the agent.
GET …/channels/setup?kind=telegramreturns the steps for creating the bot at @BotFather and names the credentials the create needs. See setup on the Bot chat channels API page. - 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.
What’s next
Section titled “What’s next”- Decide approvals from Telegram: the Bot stops before a risky step and asks in the chat
- Fix a chat app that does not answer
- Every chat channel operation on the API page