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

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:

  1. Create a bot account on the platform and copy its token.
  2. Connect it to your Bot: in the Hub, in the agent’s TUI (Bots tab) or over HTTP. The agent checks the token with the platform before it saves anything.
  3. Become the owner. The connect answer shows an owner code once. Send it to your new bot account in a direct message.
  4. Talk. Write to the bot account in a direct message. Your Bot answers.

A Bot can have up to 8 chat apps (max_channels). One bot account can serve one chat app at a time.

  1. In the Hub, open Bots, select the Bot and open Chat apps.
  2. Choose Add a chat app, pick Telegram, Slack or Discord, and choose Next. Paste the Bot token (Slack also needs the App token) and choose Connect.
  3. Under Become its owner, choose Owner code, copy the code and send it to the bot in a direct message.

Choose Manage on a chat app to open its Setup, People, Chats and Settings.

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.

  • 200: the chat app is deleted. When its connection was still closing, the call first waits up to about 10 seconds for it.
  • 202: the connection is still closing after that wait. Nothing is deleted yet; the chat app is deleted as soon as its connection closes. A delete sent again waits again, and answers 404 once the chat app is gone.
  • 503: read the chat app (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:

RightWhat it allows
chatTalk to the Bot.
controlRun chat commands such as stop, and add the Bot to a group.
gatesDecide 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.

  • The connect answer carries the owner code once, in enrolment. The TUI shows it on screen.
  • Send the code to your bot account in a direct message. Send only the code: 7KQ4M9TX, or pair 7KQ4M9TX. On Telegram, /start 7KQ4M9TX and /pair 7KQ4M9TX work too. Case, spaces and dashes do not matter.
  • The bot answers “You are paired.” From then on, your direct messages reach your Bot.

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.

{
"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:

  • A pairing code. Set 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).
  • Their user id. Add the person directly with their platform user id (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_policyWho may talk
owner (default)Owners only. Only an owner code can be redeemed.
allowlistPeople you added by user id, or paired earlier, whose rights include chat. Pairing codes are not taken.
pairingPeople you added, plus anyone who sends a valid pairing code, if their rights include chat.
openAnyone. 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):

  1. Add the bot account to the group.
  2. A paired person with the 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.
  3. The group shows up in the chat app’s chats with the state requested. The bot says it asked the owner and reads nothing there until then.
  4. The owner can approve the group using Approve on the card sent to their direct message, in the Hub or the TUI’s Chat apps screen, or through the API. Approval confirms that everyone in the group can read the Bot’s answers.

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.

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.

CommandWhat it does
statusShows Bot followed by the Bot’s name.
stopStops what the Bot is doing now.
bindIn a group: asks the owner to approve this group.
unbindIn a group: ends the group’s link to the Bot.
helpLists 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.

  • Set it when you pair: make_home: true on the owner code makes your direct message the home chat.
  • Or set home_chat on the chat app to the id of one of its chats (PATCH …/channels/{cid} with home_chat).
  • Choose which updates it gets with push_events, and how long each is with push_detail.
  • It reads text only. A file, image or voice message is not passed to the Bot, only the text sent with it (a photo’s caption, for example). The Bot is also told which kinds of file came with the message and how many, never their contents. A message with no text does not reach the Bot.
  • It does not use the platform’s own slash commands on Slack or Discord. Commands use the ! prefix there.
  • A question that needs a typed answer cannot be answered with a button. The card says to answer it in the session.

Your Bot is one message away, wherever you already chat.