> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord Channel

> WebSocket gateway integration for Discord

The Discord channel connects NullClaw to Discord using the WebSocket gateway for real-time message delivery and the REST API for sending messages.

## Features

* WebSocket gateway for real-time events
* Guild (server) and DM support
* Configurable intents
* Bot mention detection
* Allow/deny lists for user access
* Typing indicators
* Automatic message splitting at 2000 character limit
* Session resumption on disconnect

## Configuration

Add Discord to your `config.json`:

```json theme={null}
{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "YOUR_DISCORD_BOT_TOKEN",
          "guild_id": "YOUR_GUILD_ID",
          "allow_from": ["USER_ID_1", "USER_ID_2"],
          "allow_bots": false,
          "require_mention": false,
          "intents": 37377
        }
      }
    }
  }
}
```

### Configuration Options

<ParamField path="token" type="string" required>
  Discord bot token from the [Discord Developer Portal](https://discord.com/developers/applications)
</ParamField>

<ParamField path="guild_id" type="string" default="null">
  Guild (server) ID to restrict the bot to a specific server. If `null`, bot works in all servers it's added to.

  **Finding guild ID**: Enable Developer Mode in Discord settings, then right-click your server and select "Copy ID"
</ParamField>

<ParamField path="allow_from" type="string[]" default="[]">
  List of allowed Discord user IDs. Empty list means allow all users. Use `"*"` for explicit allow-all.

  **Finding user ID**: Enable Developer Mode, right-click a user, select "Copy ID"
</ParamField>

<ParamField path="allow_bots" type="boolean" default="false">
  Whether to respond to messages from other bots
</ParamField>

<ParamField path="require_mention" type="boolean" default="false">
  When `true`, bot only responds to messages that mention it (using @botname)
</ParamField>

<ParamField path="intents" type="integer" default="37377">
  Gateway intents bitmask. Default includes:

  * `GUILDS` (1 \<\< 0)
  * `GUILD_MESSAGES` (1 \<\< 9)
  * `MESSAGE_CONTENT` (1 \<\< 15)
  * `DIRECT_MESSAGES` (1 \<\< 12)

  See [Discord Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents) for details.
</ParamField>

<ParamField path="account_id" type="string" default="default">
  Account identifier for multi-account setups
</ParamField>

## Setup Guide

<Steps>
  <Step title="Create a Discord Application">
    1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
    2. Click "New Application"
    3. Give your application a name
    4. Navigate to the "Bot" section in the left sidebar
    5. Click "Add Bot" and confirm
  </Step>

  <Step title="Configure Bot Settings">
    1. Under "Privileged Gateway Intents", enable:
       * Message Content Intent (required)
       * Server Members Intent (optional)
    2. Copy the bot token (click "Reset Token" if needed)
    3. Under "OAuth2 > URL Generator":
       * Select scope: `bot`
       * Select permissions: `Send Messages`, `Read Message History`, `View Channels`
    4. Copy the generated URL
  </Step>

  <Step title="Invite Bot to Your Server">
    1. Paste the OAuth2 URL in your browser
    2. Select your server from the dropdown
    3. Click "Authorize"
    4. Complete the captcha
  </Step>

  <Step title="Get Guild and User IDs">
    1. Enable Developer Mode in Discord:
       * User Settings > Advanced > Developer Mode
    2. Right-click your server name → "Copy ID" (guild\_id)
    3. Right-click your username → "Copy ID" (for allow\_from)
  </Step>

  <Step title="Configure NullClaw">
    Add the bot token and IDs to `~/.nullclaw/config.json`:

    ```json theme={null}
    {
      "channels": {
        "discord": {
          "accounts": {
            "main": {
              "token": "YOUR_BOT_TOKEN",
              "guild_id": "YOUR_GUILD_ID",
              "allow_from": ["YOUR_USER_ID"]
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Start NullClaw">
    Run `nullclaw` and send a message in a channel where the bot has access. You should receive a response.
  </Step>
</Steps>

## Gateway Intents

Discord requires you to specify which events your bot wants to receive. The default intent value (`37377`) includes:

```
GUILDS (1) + GUILD_MESSAGES (512) + DIRECT_MESSAGES (4096) + MESSAGE_CONTENT (32768) = 37377
```

### Required Intents

* **MESSAGE\_CONTENT (32768)**: Required to read message content. Must be enabled in the Developer Portal under "Privileged Gateway Intents".

### Common Intent Combinations

**Guild messages only**:

```json theme={null}
{
  "intents": 33281
}
```

(GUILDS + GUILD\_MESSAGES + MESSAGE\_CONTENT)

**DMs only**:

```json theme={null}
{
  "intents": 36864
}
```

(DIRECT\_MESSAGES + MESSAGE\_CONTENT)

**Everything**:

```json theme={null}
{
  "intents": 37377
}
```

(Default: guilds, guild messages, DMs, message content)

## Mention-Only Mode

For bots in busy servers, enable mention-only mode:

```json theme={null}
{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "require_mention": true
        }
      }
    }
  }
}
```

The bot will only respond when mentioned with `@BotName`.

## Message Limits

Discord enforces a 2000 character limit per message. NullClaw automatically splits longer messages while respecting UTF-8 character boundaries.

## Session Resumption

The Discord channel implements automatic session resumption:

* Maintains session ID and sequence number
* Reconnects and resumes on disconnect
* Falls back to fresh IDENTIFY if resume fails
* Stores resume gateway URL for optimal reconnection

## Typing Indicators

When the agent is processing a message, the bot shows a typing indicator in the channel. This provides real-time feedback to users.

## Multiple Accounts

Run multiple Discord bots simultaneously:

```json theme={null}
{
  "channels": {
    "discord": {
      "accounts": {
        "server1": {
          "token": "TOKEN_1",
          "guild_id": "GUILD_1",
          "allow_from": ["USER_1"]
        },
        "server2": {
          "token": "TOKEN_2",
          "guild_id": "GUILD_2",
          "require_mention": true
        },
        "dm_bot": {
          "token": "TOKEN_3",
          "intents": 36864
        }
      }
    }
  }
}
```

## Troubleshooting

### Bot Not Connecting

1. Verify bot token is correct and not expired
2. Check that Message Content Intent is enabled in Developer Portal
3. Ensure intents value matches enabled intents
4. Check logs for gateway errors: `nullclaw --log-level debug`

### Bot Not Responding

1. Verify user ID is in `allow_from` (or list is empty)
2. Check that bot has permission to read messages in the channel
3. If `require_mention` is true, ensure you're mentioning the bot
4. Check that `allow_bots` is true if testing with another bot

### Missing Message Content

1. Enable Message Content Intent in Developer Portal:
   * Go to Bot settings > Privileged Gateway Intents
   * Enable "Message Content Intent"
2. Ensure `MESSAGE_CONTENT` bit is set in intents (32768)
3. Restart NullClaw after changing intents

### Frequent Disconnects

1. Check network stability
2. Verify heartbeat interval is being respected
3. Review gateway logs for disconnect reasons
4. Consider rate limiting if sending many messages

## Source Code

Implementation: `src/channels/discord.zig`