Skip to main content

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.

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: 
{
  "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

​
token
string
required
Discord bot token from the Discord Developer Portal
​
guild_id
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”
​
allow_from
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”
​
allow_bots
boolean
default:"false"
Whether to respond to messages from other bots
​
require_mention
boolean
default:"false"
When true, bot only responds to messages that mention it (using @botname)
​
intents
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 for details.
​
account_id
string
default:"default"
Account identifier for multi-account setups

​
Setup Guide

1

Create a Discord Application

  1. Go to Discord Developer Portal
  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
2

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
3

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
4

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)
5

Configure NullClaw

Add the bot token and IDs to ~/.nullclaw/config.json:
{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "YOUR_BOT_TOKEN",
          "guild_id": "YOUR_GUILD_ID",
          "allow_from": ["YOUR_USER_ID"]
        }
      }
    }
  }
}
6

Start NullClaw

Run nullclaw and send a message in a channel where the bot has access. You should receive a response.

​
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: 
{
  "intents": 33281
}
(GUILDS + GUILD_MESSAGES + MESSAGE_CONTENT) DMs only: 
{
  "intents": 36864
}
(DIRECT_MESSAGES + MESSAGE_CONTENT) Everything: 
{
  "intents": 37377
}
(Default: guilds, guild messages, DMs, message content)

​
Mention-Only Mode

For bots in busy servers, enable mention-only mode: 
{
  "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: 
{
  "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