# Documentation Page **Page:** kit/agent/chat-apps/discord [Download Raw Markdown](./kit/agent/chat-apps/discord.md) --- # Connect your Bot to Discord **Create an application, copy its bot token, send one code. Your Bot then answers you in Discord.** You need a Discord account and a Bot. The examples use the Bot `chief`. ## 1. Create the Discord application 1. Open the [Discord Developer Portal](https://discord.com/developers/applications) and choose **New Application**. Give it a name. 2. Open **Bot**. Choose **Reset Token** and copy the token. Treat it like a password. 3. Turn on **Message Content Intent** if the Bot should read replies and `!` commands in server channels without an @mention. Direct messages and @mentions work without it. ## 2. Connect it The agent checks the token with Discord before it saves anything: that the bot exists and the token belongs to it. The token is never shown again. 1. In the Hub, open **Bots**, select your Bot and open **Chat apps**. 2. Choose **Add a chat app**, select **Discord** and choose **Next**. 3. Paste the token into **Bot token**. A **Name in this Hub** under **Options** is optional. Choose **Connect**. 4. Under **Become its owner**, choose **Owner code** to show the code. Go to step 3 below. 1. Open the **Bots** tab, select your Bot and open **⇄ Connect**. 2. Under **Chat apps**, choose **[ + Add chat app ]**, then **Discord**. 3. Paste the token into **Bot token** (a **Name** is optional) and choose **✓ Add**. The agent checks it ("Checking the token…"). 4. The owner code appears on screen. Go to step 3 below. ```bash hoody agent bots channels create -c $COMPUTER_ID --id chief --kind discord --label "My Discord" --bot-token "$DISCORD_BOT_TOKEN" ``` Pass the bot token with `--bot-token`. The `credentials set` command also requires `--bot-token` when replacing a channel's token. ```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.create('chief', { kind: 'discord', label: 'My Discord', token: process.env.DISCORD_BOT_TOKEN!, }); console.log(data.id, data.enrolment?.code); ``` ```bash curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/bots/chief/channels" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: discord-chief-1" \ -d '{ "kind": "discord", "label": "My Discord", "token": "" }' ``` If your computer's proxy permissions protect the agent, add the credential its group requires to the cURL example; see [proxy permissions](/foundation/proxy/permissions/). The answer carries the chat app's `id`, its current `state` and, once, the owner code in `enrolment.code`. The state may initially be `connecting`; it can show `awaiting_owner` once connected and until you pair. If the token is refused, the answer is `channel_credentials_invalid` with a `reason`: | `reason` | What to do | |---|---| | `unauthorized` | The token is wrong, was reset, or is not a bot token. Copy the bot token again, whole. | | `missing_access` | Discord refused the check (HTTP 403). Check the application and its bot in the Discord Developer Portal, then try again. | | `unreachable` | Discord could not be reached. Try again. | | `binding_changed` | Discord answered for a different bot or application during the check. Try again; if it repeats, copy the bot token again, whole. | ## 3. Invite it to a server For this setup, invite the bot to a server you own, then open its direct message from that server: - In the Hub, open the Bot's **Chat apps** tab, choose **Manage** on the Discord app, open **Chats** and then **Add the Bot to a group**, and choose **Invite link**. The agent's TUI shows the same **Invite link** in the chat app's details. Over the API it is `identity.invite_url` of the chat app. - Or build one in the Developer Portal: **OAuth2** → **URL Generator**, scope `bot`, with the permissions **View Channels**, **Send Messages**, **Send Messages in Threads**, **Embed Links** and **Read Message History**. With the default `group_mode: owner_approves`, inviting the bot does not let it read a server channel until the owner approves that channel (step 6). With `group_mode: open`, server channels are served without approval: by default only text messages addressed to the Bot, and unaddressed text messages too once `mention_only` is `false`. The Bot does not read attachments; media-only messages do not reach it. ## 4. Become the owner In the server, click the bot's name and send it a direct message. Send the owner code as the only text: ```text 7KQ4M9TX ``` `pair 7KQ4M9TX` works too. The bot answers that you are paired. Now write to it. Your Bot answers in the same direct message. If you cannot message the bot, check your own Discord privacy settings for direct messages from server members. By default the code works for 15 minutes (`pairing_ttl_minutes`). If it expired, make a new owner code (see [Become the owner](/kit/agent/chat-apps/#become-the-owner)). ## 5. Add other people (optional) Anyone you pair can read the Bot's answers in their conversation with it. Pair only people you would let read it. - **With a code:** set `dm_policy` to `pairing`, make a pairing code, and give it to the person. They send it to the bot in a direct message. - **By user id:** set `dm_policy` to `allowlist` or `pairing`, and add them with their Discord user id (`POST …/channels/{cid}/principals`). Turn on Developer Mode in Discord to copy a user id. ## 6. Use it in a server channel (optional) On Discord, a group is a server channel. Every member who can read that channel can read what the Bot answers there. 1. A paired person with the `control` right sends `!bind` in the server channel, mentioning the bot. 2. The owner can approve the channel using **Approve** on the card sent to their direct message, in the TUI's **Chat apps** screen, in the Hub (the Bot's **Chat apps** tab, **Manage** on the Discord app, **Chats**, then **Approve** on the channel and **Approve group**), or with `PATCH …/chats/{chat}` and `{"state": "approved", "acknowledge_group_readers": true}`. Approval confirms that everyone in the channel can read the Bot's answers. `{chat}` is the chat's `id` in the chat app's `chats` list (`chat_…`), not the Discord channel id. By default the Bot reads only messages that mention it, reply to it, or start with `!` (`mention_only`). Without **Message Content Intent**, the Bot reads only server messages that @mention it. A reply counts only when the @ ping is left on, and a `!` command needs a mention too. Discord blanks the text of every other server message. The chat app's state then shows reason `message_content_missing`, and the bot says: "In groups I can only read messages that mention me." Direct messages are not affected. Waiting does not pick up an intent you turn on later: a running chat app keeps the Discord session it started without the intent. After you turn the intent on, turn the chat app off and on again, pause and resume the Bot's chat apps, or enter its token again. The next connection then asks Discord for the intent. If it is still off, the chat app connects without it again, as before. Each of these steps starts a new Discord session, so messages sent while the chat app reconnects may not reach the Bot. ## Discord details - By default, commands use `!` (`command_prefix`): `!status`, `!stop`, `!bind`, `!unbind`, `!help`. The bot does not register Discord slash commands. - One answer part holds at most 2000 characters (`part_chars`). A longer answer is sent in up to 8 parts by default (`max_parts`, 1 to 20). - Approval cards use Discord buttons: **Approve** green, **Deny** red, **Allow for this session** blue, question choices grey. A single question with up to 8 options has choice buttons; other questions require a typed answer. A label is cut at 40 UTF-16 code units. - A card's text follows `part_chars`, up to 2000 UTF-16 code units, just like a normal answer part. - These text and label limits count UTF-16 code units: a character outside the Basic Multilingual Plane counts as two, and a displayed glyph made from several characters can count as more. - A button press is acknowledged at once. A note about it (you may not decide, or the press could not be sent) is shown only to the person who pressed. - If Discord says the interaction failed, the press was not applied. Press again. - The Bot's messages never ping anyone: no `@everyone`, no user pings. - By default, the chat app logs in to Discord at most 20 times per hour and 100 times per day (`identify_per_hour`, `identify_per_day`). Discord limits logins per bot. Without **Message Content Intent**, the first fresh login after the chat app starts is refused once and then retried without it, so it counts twice. - A bot in very many servers needs sharding, which is not supported. The state then shows `degraded` with reason `gateway_refused`. **Next:** [decide approvals from Discord](/kit/agent/chat-apps/approvals/).