Connect your Bot to Discord
Section titled “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
Section titled “1. Create the Discord application”- Open the Discord Developer Portal and choose New Application. Give it a name.
- Open Bot. Choose Reset Token and copy the token. Treat it like a password.
- 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
Section titled “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.
- In the Hub, open Bots, select your Bot and open Chat apps.
- Choose Add a chat app, select Discord and choose Next.
- Paste the token into Bot token. A Name in this Hub under Options is optional. Choose Connect.
- Under Become its owner, choose Owner code to show the code. Go to step 3 below.
- Open the Bots tab, select your Bot and open ⇄ Connect.
- Under Chat apps, choose [ + Add chat app ], then Discord.
- Paste the token into Bot token (a Name is optional) and choose ✓ Add. The agent checks it (“Checking the token…”).
- The owner code appears on screen. Go to step 3 below.
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.
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);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": "<discord bot token>" }'If your computer’s proxy permissions protect the agent, add the credential its group requires to the cURL example; see 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
Section titled “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_urlof 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
Section titled “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:
7KQ4M9TXpair 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).
5. Add other people (optional)
Section titled “5. Add other people (optional)”- With a code: set
dm_policytopairing, 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_policytoallowlistorpairing, 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)
Section titled “6. Use it in a server channel (optional)”- A paired person with the
controlright sends!bindin the server channel, mentioning the bot. - 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’sidin the chat app’schatslist (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
Section titled “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
degradedwith reasongateway_refused.