One conversation everywhere
A chat app is one more way into the same Bot. What you say in Telegram, the app or the API all lands in the Bot’s one conversation.
Your Bot already works on your computers. Now it can answer you in the chat app you have open all day.
A Bot is a long-running assistant inside the Hoody Agent. It talks with you and hands real work to agents it starts on your computers. Until now you reached it through the agent’s app, its API or a terminal. That means you had to be at a screen with Hoody open.
A chat app connects a Bot to a bot account on Telegram, Slack or Discord. You write to that bot account like to a person. Your message reaches your Bot. Its answer comes back in the same chat. When one of its agents needs your approval, you get a card with buttons.
One conversation everywhere
A chat app is one more way into the same Bot. What you say in Telegram, the app or the API all lands in the Bot’s one conversation.
Approvals on your phone
A pending approval shows as a card with Approve and Deny buttons. You decide who may press them.
Updates without asking
Pick a home chat and the updates to send it (push_events). The Bot then sends it what it does on its own: finished work, requests for approval, errors.
You decide who talks to it
By default only you, the owner, can talk to the Bot. Others need a pairing code from you, or you add them by their user id.
Pick your platform. Each page walks you from creating the bot account to your first message.
Every setup has the same four steps:
A Bot can have up to 8 chat apps (max_channels). One bot account can serve one chat app at a time.
Choose Manage on a chat app to open its Setup, People, Chats and Settings.
Open the Bots tab and select your Bot. Open ⇄ Connect (the chip in the Bot’s title row, or press c). The Chat apps section lists the Bot’s chat apps. [ + Add chat app ] starts a new one.
Select a chat app to see its state, the people paired with it and its chats. Choose Settings to change its settings. Switches and choices apply at once. A typed value, such as a number, applies when you choose ✓ Save.
hoody agent bots channels list -c $COMPUTER_ID --id chiefEvery chat app command lives under hoody agent bots channels. Each takes the computer (-c) and the Bot (--id); commands on one chat app also take --channel-id. The commands: list, setup get, create, get, update, delete, credentials set, pairing create|cancel, principals add|update|remove, chats update|delete and settings get|update.
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.list('chief');for (const app of data.items) console.log(app.id, app.kind, app.state);Every chat app method lives under box.agent.bots.channels, where box is the client of the computer that runs the agent.
curl "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels"In the API, a chat app is a channel. Its routes live under /api/v1/agent/bots/{id}/channels. The Bot chat channels API reference lists every field. If your computer’s proxy permissions protect the agent, add the credential its group requires to the cURL examples; see proxy permissions.
Deleting a chat app disconnects it and deletes its stored tokens, paired people and chats. The Bot and its sessions stay. In the Hub, open the chat app’s Settings and choose Remove under Remove this chat app, then confirm. Or use delete in the CLI, or DELETE …/channels/{cid} in the API.
GET …/channels/{cid}) to see which case it is. Still there: nothing was deleted (the Bot’s chat apps were being handed over, or their store was not available); send the delete again, after the seconds in Retry-After when it is set. Gone (404): the chat app is deleted, but its files on this computer, its stored tokens included, could not be removed, and a delete sent again does not remove them. To make the leftover token useless, reset it on the platform (BotFather, the Slack app settings, or the Discord developer portal).Every person a chat app knows has rights:
| Right | What it allows |
|---|---|
chat | Talk to the Bot. |
control | Run chat commands such as stop, and add the Bot to a group. |
gates | Decide approvals, when the chat app’s gate_deciders setting is named. |
One person is the owner. The owner has every right. A chat app keeps up to 8 people by default (max_principals, at most 32).
The first owner always proves it with an owner code. This shows the agent that the chat account is really yours.
enrolment. The TUI shows it on screen.7KQ4M9TX, or pair 7KQ4M9TX. On Telegram, /start 7KQ4M9TX and /pair 7KQ4M9TX work too. Case, spaces and dashes do not matter.By default the code stops working after 15 minutes (pairing_ttl_minutes). Lost it, or it expired? Make a new one:
In the Hub, open Bots, select the Bot, open Chat apps and choose Manage on the chat app. Under Setup, choose Owner code.
hoody agent bots channels pairing create -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --ownerconst { data } = await box.agent.bots.channels.createPairing('chief', 'ch_1a2b3c4d', { owner: true });console.log(data.code, data.expires_at);curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels/ch_1a2b3c4d/pairing" \ -H "Content-Type: application/json" \ -d '{"owner": true}'{ "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."}An owner code is refused once the chat app has an owner. After that, ownership can be handed over to another paired person: PATCH …/principals/{pid} with "owner": true (in the TUI: ♛ Make owner). Or add a new person as the owner: POST …/principals with their platform_user and "owner": true, without rights. There is one owner at a time. The new owner gets every right. The previous owner keeps their rights but is no longer the owner, so with dm_policy set to owner (the default) they can no longer talk to the Bot.
There are two ways:
dm_policy to pairing. Make a code without owner, and give it to the person. They send it to the bot account in a direct message. A new code replaces the previous one. You can cancel it at any time (DELETE …/pairing).POST …/principals). No code is needed. This works with dm_policy set to allowlist or pairing.In the Hub, open the chat app’s People section. Under Invite someone, tick the rights and choose Create invite code. Direct messages must be set to Anyone with an invite code from me. Or choose Add a person, enter their user ID for the app, pick Rights and choose Add person.
Choose the rights they get with rights. Without it, a pairing code grants the chat app’s pairing_rights (by default: chat only).
The chat app’s dm_policy decides who may talk in a direct message:
dm_policy | Who may talk |
|---|---|
owner (default) | Owners only. Only an owner code can be redeemed. |
allowlist | People you added by user id, or paired earlier, whose rights include chat. Pairing codes are not taken. |
pairing | People you added, plus anyone who sends a valid pairing code, if their rights include chat. |
open | Anyone. A person not paired is a guest; people already paired keep their rights. A guest can talk and request help, but cannot use control commands or decide approvals. |
Wrong codes are counted. By default, after 5 wrong codes a person is refused for 60 minutes (pairing_user_burn_tries, pairing_user_burn_minutes). After 20 wrong codes in total, the current code stops working (pairing_code_burn_tries). See Chat app settings. A message that holds a live code is never passed to the Bot.
Someone who may not talk to the Bot gets one line per hour asking them to get a code from the owner (unpaired_reply). Set it to silent to say nothing.
By default a group must be approved by the owner (group_mode: owner_approves):
control right sends the bind command in the group, addressed to the Bot. On Telegram that is /bind. On Slack and Discord it is !bind.requested. The bot says it asked the owner and reads nothing there until then.In the Hub, open Bots, select the Bot, open Chat apps and choose Manage on the chat app. Under Chats, choose Approve on the group, then Approve group.
The group shows as Approve group in the chat app, with a warning sign. Tick I understand that every member of the group can read the Bot’s answers, then [ ✓ Approve ].
hoody agent bots channels chats update -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --chat-id chat_5f3a9c21d0e4b7a8 --state approved --acknowledge-group-readersawait box.agent.bots.channels.updateChat('chief', 'ch_1a2b3c4d', 'chat_5f3a9c21d0e4b7a8', { state: 'approved', acknowledge_group_readers: true,});The route names the chat by its id in the chat app’s chats list (GET …/channels/{cid}), for example chat_5f3a9c21d0e4b7a8. It is not the platform’s own chat id, which is in platform_chat.
curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels/ch_1a2b3c4d/chats/chat_5f3a9c21d0e4b7a8" \ -H "Content-Type: application/json" \ -d '{"state": "approved", "acknowledge_group_readers": true}'Without acknowledge_group_readers: true the approval is refused with acknowledgement_required, and nothing changes.
In an approved group, the Bot reads only messages addressed to it: a mention, a reply to the Bot, or a command (mention_only: true). Set mention_only: false to read every message. That needs the platform’s permission to read message content. On Discord without it, the Bot reads only messages that @mention it (see Discord).
Other group modes: off ignores groups, allowlist serves only the groups listed in allowed_chats, and only once the owner has approved them, and open serves any group without approval. In an open group the Bot reads only messages addressed to it while mention_only is true (the default), and every message when it is false. Its unpaired members are guests; people already paired keep their rights.
unbind in the group, removing the bot from the group, or forgetting the chat (DELETE …/chats/{chat}) ends it. Under group_mode: open a forgotten group is served again the next time someone mentions the Bot there, or at its next message when mention_only is false. Add it to blocked_chats to keep it out.
status, stop, bind and unbind need the control right. help is open to anyone the Bot talks to.
| Command | What it does |
|---|---|
status | Shows Bot followed by the Bot’s name. |
stop | Stops what the Bot is doing now. |
bind | In a group: asks the owner to approve this group. |
unbind | In a group: ends the group’s link to the Bot. |
help | Lists the commands. |
The prefix is / on Telegram and ! on Slack and Discord (command_prefix). Turn single commands off with chat_commands. A command a chat app does not know is ordinary text.
The home chat is the chat that gets the Bot’s own updates: work it finished on its own, approvals it waits for, errors. It is one direct message or one approved group of the chat app.
make_home: true on the owner code makes your direct message the home chat.home_chat on the chat app to the id of one of its chats (PATCH …/channels/{cid} with home_chat).push_events, and how long each is with push_detail.! prefix there.Your Bot is one message away, wherever you already chat.