# Documentation Page **Page:** kit/agent/chat-apps [Download Raw Markdown](./kit/agent/chat-apps.md) --- # Chat apps for your Bot **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. --- ## What you get 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. A pending approval shows as a card with Approve and Deny buttons. You decide who may press them. 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. 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. ## Set up a chat app 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. ## Where to manage chat apps 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**. 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**. ```bash hoody agent bots channels list -c $COMPUTER_ID --id chief ``` Every 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`. ```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.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. ```bash 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](/api/agent/bots/channels/) 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](/foundation/proxy/permissions/). ### Delete a chat app 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). --- ## People and rights 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). ### Become the owner 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**. ```bash hoody agent bots channels pairing create -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --owner ``` ```ts const { data } = await box.agent.bots.channels.createPairing('chief', 'ch_1a2b3c4d', { owner: true }); console.log(data.code, data.expires_at); ``` ```bash 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}' ``` ```json { "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. ### Let someone else in Anyone you pair with the `chat` right can talk to the same Bot you do, when the chat app's `dm_policy` admits them (in a group, its `group_mode`). The Bot's conversation is shared. What you told it earlier may show up in what it answers them. 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_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](/kit/agent/chat-apps/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. ## Groups When you approve a group, every member of it can read what the Bot answers there. The Bot's conversation is shared: something said in a direct message earlier may colour what it says in the group. 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**. 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 ]**. ```bash hoody agent bots channels chats update -c $COMPUTER_ID --id chief --channel-id ch_1a2b3c4d --chat-id chat_5f3a9c21d0e4b7a8 --state approved --acknowledge-group-readers ``` ```ts await 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`. ```bash 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](/kit/agent/chat-apps/discord/#6-use-it-in-a-server-channel-optional)). 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. ## Chat commands `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. ## Home chat and updates 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`. ## What the Bot cannot do in a chat app - 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. ## Next steps **Your Bot is one message away, wherever you already chat.**