Discord & iMessage Setup

+15 Mana ✨
OpenClaw Discord Channel(DOCUMENTATION)OpenClaw iMessage Channel(DOCUMENTATION)

Introduction

Discord is the dominant platform for developer and gaming communities, while iMessage is the default messaging system for Apple devices. Setting up OpenClaw on Discord requires navigating the Developer Portal, configuring intents, and generating an OAuth invite link. iMessage integration uses BlueBubbles, a macOS application that exposes iMessage through a REST API bridge. This lesson covers both platforms in detail.

Key Concepts

  • Discord Developer Portal: The web interface at discord.com/developers where you create bot applications, configure permissions, and generate tokens.
  • Intents: Discord's permission flags that control what data your bot can access. Message Content intent is required for reading message text, and Server Members intent is recommended for user-related features.
  • OAuth Invite URL: A specially crafted URL that server administrators use to add your bot to their Discord server, specifying the bot and applications.commands scopes.
  • Guild: Discord's internal term for a server. OpenClaw uses workspace configuration at the guild level.
  • Slash Commands: Discord's native command system (e.g., /ask) that OpenClaw can register and respond to.
  • Components v2: Discord's interactive UI elements (buttons, select menus, modals) that OpenClaw supports for richer bot interactions.
  • BlueBubbles: A macOS application that runs as a local server and exposes iMessage functionality through a REST API, allowing OpenClaw to send and receive iMessages programmatically.

Real World Context

A gaming studio runs their community on Discord with tens of thousands of members across multiple channels. They want an AI assistant that answers gameplay questions, helps with bug reports, and provides patch note summaries. They also have a small internal team using iMessage for quick coordination on their Macs. With OpenClaw, the Discord bot handles the public community with slash commands and interactive components, while the iMessage bridge keeps the internal team connected to the same assistant privately.

Deep Dive

Discord Setup

Discord bot setup involves several steps in the Developer Portal before any configuration in OpenClaw.

First, go to the Discord Developer Portal (discord.com/developers/applications) and create a new application. Give it a name and navigate to the Bot section. Click "Add Bot" to create a bot user, then copy the bot token.

Next, you must enable the required intents. Under the Bot section, scroll to Privileged Gateway Intents. Enable Message Content Intent, which is required for your bot to read the actual text content of messages. Without this intent, your bot will receive message events but the content field will be empty. Also enable Server Members Intent if you want your bot to access member information, which is recommended for features like user identification and role-based access.

Now generate an invite URL. Go to the OAuth2 section, select the URL Generator, and check the bot and applications.commands scopes. Under Bot Permissions, select the permissions your bot needs (at minimum: Send Messages, Read Message History, Add Reactions). Copy the generated URL and open it in a browser to invite the bot to your server.

Configure the Discord channel in OpenClaw:

json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.G1a2b3.xYz789AbCdEfGhIjKlMnOpQrStUvWx",
      "workspace": {
        "guildId": "1234567890123456789"
      }
    }
  }
}

The token field is your bot token from the Developer Portal. The workspace.guildId field specifies which Discord server (guild) this assistant operates in. You can find the guild ID by enabling Developer Mode in Discord settings, then right-clicking the server name and selecting "Copy Server ID".

Discord supports slash commands out of the box. When your bot starts, OpenClaw can register slash commands that appear in Discord's command menu when users type /. This provides discoverability and a clean interface for interacting with the assistant.

OpenClaw also supports Discord's Components v2, which includes buttons, select menus, and modals. These allow your assistant to present interactive responses, such as buttons for follow-up actions or dropdown menus for selecting options.

iMessage Setup

iMessage integration requires a Mac running BlueBubbles, which acts as a bridge between iMessage and OpenClaw.

First, install BlueBubbles on a Mac that is signed into the Apple ID you want to use for iMessage. BlueBubbles runs as a server on that Mac and exposes iMessage functionality through a REST API.

Once BlueBubbles is running and configured, point OpenClaw to its API:

json
{
  "channels": {
    "imessage": {
      "enabled": true,
      "blueBubblesUrl": "http://localhost:1234",
      "blueBubblesPassword": "your-bluebubbles-password"
    }
  }
}

The blueBubblesUrl field points to the BlueBubbles REST API, typically running on localhost. The blueBubblesPassword field is the password you set during BlueBubbles configuration, which secures access to the API.

Because BlueBubbles requires a running macOS instance with an active iMessage session, this channel is best suited for personal or small-team deployments rather than large-scale public bots. The Mac must remain on and logged in for the bridge to function.

Common Pitfalls

  • Forgetting the Message Content intent on Discord: This is the most common Discord setup issue. Without the Message Content privileged intent enabled in the Developer Portal, your bot receives message events but cannot read what users typed. The bot will appear to ignore all messages.
  • Using the wrong token type for Discord: Discord has multiple token types (bot token, OAuth2 token, user token). OpenClaw requires the bot token from the Bot section of the Developer Portal, not the client secret from the OAuth2 section.
  • BlueBubbles Mac going to sleep: If the Mac running BlueBubbles enters sleep mode or the screen saver activates the lock screen, the iMessage bridge may stop functioning. Configure the Mac to never sleep and disable the screen lock.

Best Practices

  • Request only the permissions you need on Discord: Over-requesting permissions makes server administrators hesitant to add your bot. Start with minimal permissions and add more as needed.
  • Use slash commands on Discord: Slash commands provide a discoverable, structured way for users to interact with your bot. They also work in servers where the bot might not have permission to read regular messages.
  • Keep BlueBubbles on a dedicated Mac: If iMessage is critical to your workflow, dedicate a Mac Mini or similar device to running BlueBubbles full-time rather than relying on a personal laptop that may be closed or taken offline.

Summary

  • Discord bots are created in the Developer Portal, where you generate a token and enable the Message Content intent (required) and Server Members intent (recommended).
  • The OAuth invite URL must include both bot and applications.commands scopes.
  • Discord supports slash commands and Components v2 for interactive bot experiences.
  • iMessage integration uses BlueBubbles on macOS, which exposes iMessage through a REST API bridge.
  • The Mac running BlueBubbles must remain on and logged in for the iMessage channel to function.
✓ Completed