# Discord Channel for OptimClaw

WASM channel for Discord integration - handle slash commands and button interactions via webhooks.

## Features

- **Slash Commands** - Process Discord slash commands
- **Button Interactions** - Handle button clicks
- **Thread Support** - Respond in threads
- **DM Support** - Handle direct messages

## Setup

1. Create a Discord Application at <https://discord.com/developers/applications>
2. Create a Bot and get the token
3. Set up Interactions URL to point to your OptimClaw instance
4. Copy the Application ID and Public Key
5. Store in OptimClaw secrets:

   ```bash
   optimclaw secret set discord_bot_token YOUR_BOT_TOKEN
   ```

   **Note:** The `discord_bot_token` secret is used for Discord REST API calls.
   Interaction signature verification is performed inside the Discord channel
   module and uses the channel config field `webhook_secret` (set this to your
   Discord app public key hex).

## Discord Configuration

### Register Slash Commands

```bash
curl -X POST \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  https://discord.com/api/v10/applications/YOUR_APP_ID/commands \
  -d '{
    "name": "ask",
    "description": "Ask the AI agent",
    "options": [{
      "name": "question",
      "description": "Your question",
      "type": 3,
      "required": true
    }]
  }'
```

### Set Interactions Endpoint

In your Discord app settings, set:

- Interactions Endpoint URL: `https://your-optimclaw.com/webhook/discord`

## Usage Examples

### Slash Command

User types: `/ask question: What is the weather?`

The agent receives:

```text
User: @username
Content: /ask question: What is the weather?
```

### Button Click

When a user clicks a button in a message, the agent receives:

```text
User: @username
Content: [Button clicked] Original message content
```

## Error Handling

If an internal error occurs (e.g., metadata serialization failure), the tool attempts to send an ephemeral message to the user:

```text
❌ Internal Error: Failed to process command metadata.
```

Check the host logs for detailed error information.

## Advanced Usage
### Gateway Mode

The Discord channel now defaults to Discord Gateway transport for inbound message intake.
The bundled identify payload requests intents `4609`, which expands to:

- `GUILDS` (`1`)
- `GUILD_MESSAGES` (`512`)
- `DIRECT_MESSAGES` (`4096`)

Gateway DMs now follow the same pairing policy as webhook DMs. Unpaired users receive a pairing
instruction reply in the DM channel before the message is allowed through to the agent. If you
want stricter access control than pairing, set `owner_id`; that lock still applies to both
webhook and Gateway traffic.

Gateway presence simply reflects a successful authenticated Gateway connection and advertises
`online`. Pairing still controls whether DMs are allowed through to the agent, but it no longer
changes the visible Discord status.

### Mention Polling

The Discord channel can also poll configured channels for `@bot` mentions.

Example channel config:

```json
{
  "require_signature_verification": true,
  "webhook_secret": "YOUR_DISCORD_PUBLIC_KEY_HEX",
  "polling_enabled": true,
  "poll_interval_ms": 30000,
  "mention_channel_ids": ["123456789012345678"],
  "owner_id": null,
  "dm_policy": "pairing",
  "allow_from": []
}
```

### Access Control

- `owner_id`: when set, only that Discord user can interact with the bot.
- `dm_policy`: `open` allows all DMs; `pairing` requires approval.
- `allow_from`: allowlist entries for DM pairing checks (`*`, user id, or username).
- Gateway DMs respect `dm_policy` and pairing just like webhook DMs.

### Embeds

To send embeds, include an `embeds` array in the `metadata_json` field of the agent's response. The structure should match the Discord API `embed` object.

## Troubleshooting

### "Invalid Signature"

- Check that `webhook_secret` is set to your Discord app public key hex in the
  Discord channel config.
- Validation happens inside the Discord WASM channel.
- If `require_signature_verification` is `true` and `webhook_secret` is empty,
  the channel returns HTTP `500` with a configuration error.

### "401 Unauthorized"

- Check that `discord_bot_token` is set correctly in OptimClaw secrets.
- Ensure the bot is added to the server.

### "Interaction Failed"

- The interaction might have timed out (Discord requires a response within 3 seconds).
- The `interactions_endpoint_url` might be unreachable.

## Building

```bash
cd channels-src/discord
cargo build --target wasm32-wasi --release
```

## License

MIT/Apache-2.0