Discord

The Discord adapter lets a heypi agent receive Discord messages, stream replies, upload generated files, and render approval buttons.

Discord decides what the bot receives before heypi sees a message. Configure the bot invite, gateway intents, server permissions, channel permissions, and DM availability first; then use heypi's allow config to filter delivered events.

For a runnable example, see examples/discord-gondolin.

Options

discord() accepts the shared options documented in Adapters, plus Discord-specific options below.

Actor access is users OR groups. Channel access is separate. With:

allow: { channels: ["C1"], users: ["U1"], groups: ["R1"] }

U1 or members of role R1 can use the bot in C1. DMs require allow.dms and do not carry server role context.

Bot messages are rejected by default. To accept fixture or integration messages from another Discord bot, configure allow.bots:

allow: { channels: ["C1"], bots: ["B1"] }

Use bots: true to accept messages from all other Discord bots. This adapter's own Discord bot messages are always dropped, even when allow.bots is true or includes its own bot user ID. Allowed bot messages still have to pass the channel, DM, and trigger rules.

allow.bots only grants input access. Bot actors cannot list, approve, deny, or revoke approvals through the zero-config fallback. To let a trusted bot resolve approvals, list its bot user ID in permissions.approvers or permissions.admins.

Setup

Manual setup

1. Create an application at https://discord.com/developers/applications.
2. Add a bot.
3. Enable Message Content Intent.
4. Invite the bot to the server with message permissions.
5. Copy the bot token into your environment.

Required gateway intents:

Guilds
Guild Messages
Direct Messages
Message Content

Required OAuth scopes: bot and applications.commands.

Required bot permissions: View Channel, Send Messages, Send Messages in Threads, Read Message History, Add Reactions, and Attach Files.

Native controls use flat application commands:

/approvals
/bypasses
/approve approval-id
/deny approval-id
/status run-or-call-id
/cancel turn-id-or-trace
/revoke bypass-id
/bash command

Discord interaction tokens are short-lived callback credentials. heypi uses Discord interaction ids for dedupe and routing metadata, not interaction tokens.

CLI-assisted setup

Generate an invite URL and verify the token:

heypi discord invite --client-id <application-id>
heypi discord check --env .env

discord invite prints an OAuth install URL with the bot and applications.commands scopes plus heypi's required bot permissions. Discord application IDs are snowflakes; keep them as strings in config, environment variables, and CLI usage.

Use heypi discord channels [query] to list visible channel IDs. Use heypi discord observe to capture exact guild, channel, and user IDs from a delivered message.

Config

createHeypi({
  state: { root: "./state" },
  adapters: [
    discord({
      allow: {
        channels: ["234567890123456789"],
        users: ["345678901234567890"],
        groups: ["456789012345678901"],
        bots: ["567890123456789012"],
        dms: true,
      },
      trigger: "mention",
      threadTrigger: "message",
      response: {
        placement: "auto",
        continueRecentMs: 300_000,
      },
    }),
  ],
});

Common environment variables:

For app-wide config such as state, runtime, and agent, see Configuration.

CLI