Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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.

  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.

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.

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 withWhyWhat to do
channel_credentials_invalid, reason unauthorizedThe token is wrong or was revokedCopy it again, whole, from @BotFather
channel_credentials_invalid, reason unreachableTelegram could not be reachedTry again
channel_conflict, reason webhook_setThe bot already sends its updates to a webhook. Nothing is removed unless you askSend 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

Open a direct message with your bot (search its username in Telegram). Send the owner code as the only 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).

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 on the overview page, and rights in People and rights.

  1. Turn privacy off at @BotFather (see Step 1), 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.

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.