Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt

Use this file to discover all available pages before exploring further.

Heypi connects to Discord through the Discord Gateway using discord.js. The adapter listens for MessageCreate and InteractionCreate events, handles approval button clicks, and supports streaming responses. Message Content Intent must be explicitly enabled in the Developer Portal for the bot to read non-mention message text.

​
Create a Bot Application

1

Open the Discord Developer Portal

Go to https://discord.com/developers/applications and click New Application.
2

Add a bot

Navigate to the Bot tab and click Add Bot. Confirm when prompted.
3

Enable Message Content Intent

On the Bot page, scroll to Privileged Gateway Intents and enable Message Content Intent. Without this, the bot will not receive the text of messages that do not mention it directly.
4

Copy the bot token

Click Reset Token (or Copy if already generated) to get your bot token:
DISCORD_BOT_TOKEN=MTI3...
Treat this token like a password. Never commit it to version control or share it publicly.

​
Required Gateway Intents

The heypi Discord adapter is initialized with the following intents via discord.js:
IntentPurpose
GuildsRead server and channel metadata
GuildMessagesReceive messages in server channels
DirectMessagesReceive direct messages from users
MessageContentRead the full text of messages (requires privileged intent)

​
Invite the Bot to a Server

Generate an invite URL with the required permissions: 
pnpm exec heypi discord invite --client-id <application-id>
Your application ID is on the General Information page of the Developer Portal. The heypi discord check command also prints an invite URL once it connects.

​
Configure the Adapter

import { createHeypi, discord, runHeypi } from "@hunvreus/heypi";

const app = createHeypi({
  state: { root: "./state" },
  adapters: [
    discord({
      token: process.env.DISCORD_BOT_TOKEN!,
      allow: {
        guilds: ["123456789012345678"],    // Server (guild) IDs
        channels: ["234567890123456789"],  // Channel IDs
        users: ["345678901234567890"],     // Restrict to specific users
        dms: true,                        // Allow direct messages
      },
      trigger: "mention",                 // Only respond when @mentioned
      threadTrigger: "message",           // Respond to any message in thread channels
      streaming: true,
    }),
  ],
  // agent: ...
});

await runHeypi(app);
Discord decides which events heypi receives through bot invite, gateway intents, channel permissions, and DM availability. Heypi’s allow config filters those events after Discord delivers them — it does not replace Discord’s permission system.

​
Discover Guild and Channel IDs

The discovery commands connect directly to Discord using DISCORD_BOT_TOKEN. They do not start the full heypi agent — they are lightweight tools for copying stable IDs into your configuration.
1

List visible channels

pnpm exec heypi discord channels --env .env
Output format — one row per visible text or announcement channel:
<guild-id>  <channel-id>  <guild-name> #<channel-name>
2

Observe a delivered message

pnpm exec heypi discord observe --env .env
Then send a DM to the bot or post in a channel it can read. The CLI prints:
guild:   123456789012345678 (Example Server)
channel: 234567890123456789 (ops)
user:    345678901234567890 (alice)
targets: { discord: { channels: ["234567890123456789"] } }
Use the targets snippet directly in your scheduled job config.

​
Conversation Model

Discord’s thread model is slightly different from other platforms:
ContextConversation key
Thread channel (a channel that is itself a thread)The thread’s own channelId
Normal text/announcement channelThe channel’s channelId
Direct messageThe DM channel’s channelId
Thread channels get their own unique channel ID in Discord, so heypi treats them as independent conversations. The threadTrigger option lets you control whether the bot responds to every message in a thread channel, or only when mentioned.
The Discord server (guild) ID is stored as the provider team value in heypi’s thread records. You can use it in allow.guilds to restrict the bot to specific servers.

​
Full Example

The following is the complete examples/discord-project entry point — a project management bot with streaming, core tools, and an approval-gated status update: 
import { agentFrom, coreTools, createHeypi, discord, runHeypi, tool, workspace } from "@hunvreus/heypi";
import { Type } from "@sinclair/typebox";

const app = createHeypi({
  state: { root: "./state" },
  adapters: [
    discord({
      token: process.env.DISCORD_BOT_TOKEN!,
      allow: {
        guilds: (process.env.HEYPI_DISCORD_GUILDS ?? "").split(",").map((s) => s.trim()).filter(Boolean),
        channels: (process.env.HEYPI_DISCORD_CHANNELS ?? "").split(",").map((s) => s.trim()).filter(Boolean),
        users: (process.env.HEYPI_DISCORD_USERS ?? "").split(",").map((s) => s.trim()).filter(Boolean),
      },
      trigger: "mention",
      streaming: true,
    }),
  ],
  agent: agentFrom("./agent", {
    model: "openai/gpt-5-mini",
    tools: [...coreTools(), projectNote, setProjectStatus, readProjectNotes],
  }),
  approval: {
    approvers: (process.env.HEYPI_APPROVERS ?? "").split(",").map((s) => s.trim()).filter(Boolean),
    expiresInMs: 10 * 60 * 1000,
  },
  runtime: { root: workspace("./workspace") },
});

await runHeypi(app);

​
CLI Commands

heypi discord check

Validates DISCORD_BOT_TOKEN, prints the bot’s identity, and outputs an invite URL.
pnpm exec heypi discord check --env .env

heypi discord channels

Lists all text and announcement channels the bot can see, grouped by guild.
pnpm exec heypi discord channels --env .env

heypi discord invite

Generates an OAuth2 invite URL with the necessary bot permissions.
pnpm exec heypi discord invite \
  --client-id <application-id>

​
Common Failures

Message Content Intent is not enabled in the Discord Developer Portal. Go to your application’s Bot page, scroll to Privileged Gateway Intents, and enable Message Content Intent. You do not need to regenerate the token.
Verify that:
  • Message Content Intent is enabled.
  • The bot has been invited to the server with the correct permissions (use heypi discord invite to generate the URL).
  • trigger is "mention" and the message actually @mentions the bot.
  • allow.guilds and allow.channels include the correct IDs (use heypi discord channels to confirm).
allow.dms must be true to accept direct messages. Also confirm the bot has not blocked DMs in its Privacy Settings, and that the user sending the DM has a mutual server with the bot.
The approval.approvers list in your heypi config must include the Discord user ID of the intended approver. An empty or omitted approvers list means any user in the chat scope can approve. Use heypi discord observe to find user IDs.
The bot token is incorrect or has been reset. Re-copy the token from the Bot tab in the Developer Portal and update DISCORD_BOT_TOKEN.

Build docs developers (and LLMs) love

Get started for freeTalk to us