# Discord

URL: https://cogitator.app/docs/channels/discord

> Connect your AI agent to Discord servers and DMs.

## Setup

Install the Discord SDK as a peer dependency:

```bash
pnpm add discord.js
```

## Create Your Bot

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click **New Application**, give it a name
3. Go to **Bot** tab in the sidebar
4. Click **Reset Token** -- copy the token and save it:
   ```bash
   DISCORD_TOKEN=your-token-here
   ```
5. Scroll down to **Privileged Gateway Intents** and enable **Message Content Intent** -- this is required to read message text
6. Go to **OAuth2** > **URL Generator**
7. Select scopes: `bot`
8. Select bot permissions: `Send Messages`, `Read Message History`, `Add Reactions`, `Manage Messages`
9. Copy the generated URL and open it to invite the bot to your server

## Usage

```typescript
import { discordChannel } from '@cogitator-ai/channels';

const discord = discordChannel({
  token: process.env.DISCORD_TOKEN!,
  mentionOnly: true,
});
```

## Configuration

```typescript
interface DiscordConfig {
  token: string;
  intents?: number[];
  mentionOnly?: boolean;
}
```

| Option        | Default                                                 | Description                             |
| ------------- | ------------------------------------------------------- | --------------------------------------- |
| `token`       | --                                                      | Bot token from the Developer Portal     |
| `intents`     | `Guilds, GuildMessages, DirectMessages, MessageContent` | Gateway intents array                   |
| `mentionOnly` | `false`                                                 | Only respond when @mentioned in servers |

## Features

| Feature           | Support                                                                     |
| ----------------- | --------------------------------------------------------------------------- |
| Server messages   | Supported                                                                   |
| Direct messages   | Supported (`Partials.Channel` is enabled automatically)                     |
| Attachments       | Images → vision, audio → STT (downloaded from the CDN URL), files announced |
| Mention-only mode | Supported (respond only when @mentioned)                                    |
| Streaming (edit)  | Supported                                                                   |
| Reactions         | Supported (status reactions)                                                |
| Replies           | `replyTo` is set from the message reference                                 |
| Typing indicator  | Supported                                                                   |
| Auto-chunking     | Supported (2000 char limit, code-block aware)                               |
| Markdown          | Supported (native Discord markdown)                                         |

## Mention-Only Mode

When `mentionOnly: true`, the bot only responds to messages that @mention it in server channels. DMs always get a response regardless of this setting.

Both `<@BOT_ID>` and nickname mentions `<@!BOT_ID>` are recognized. The mention is automatically stripped from the message text before it reaches your agent, so instructions like `@MyBot what is 2+2?` arrive as `what is 2+2?`. Mentions are stripped in every mode, and a message that is empty after stripping (and has no attachments) is ignored. Messages from bots, including this one, are always ignored.

## Message Chunking

Discord enforces a 2000-character limit per message. Long responses are automatically split by the built-in chunker with:

* **Code block integrity** -- fenced blocks are properly closed and reopened across chunks
* **Line-count splitting** -- \~17 lines max per message to keep things readable
* **Word-boundary awareness** -- splits at whitespace when possible, never mid-word

`sendText` returns the id of the **first** message. When a streamed answer grows past one Discord message, the extra chunks are tracked as continuation messages: later edits update them in place (no duplicate posts) and `deleteMessage` removes them together with the first one.

## Tips

* You **must** enable **Message Content Intent** in the Developer Portal or the bot receives empty messages
* For DM-only bots, you don't need to add the bot to any server
* Discord rate limits message edits to \~5/sec per channel -- keep `stream.flushInterval` at 500ms or more
* With `RuntimeBuilder` (`cogitator.yml`), the token comes from `DISCORD_TOKEN`