discord-chat

Original source / Raw SKILL.md

---
name: discord-chat
description: Send messages, reply to messages, and search message history in Discord channels using the message tool. Use when the user wants to communicate with Discord (send/reply/search messages), check Discord activity, or interact with Discord channels.
---

# Discord Chat

Interact with Discord channels using Clawdbot's `message` tool.

## Core Actions

### Send Messages

Send a message to a Discord channel:

```bash
message action=send channel=discord target="#channel-name" message="Your message here"
```

Or by channel ID:

```bash
message action=send channel=discord target="1234567890" message="Your message here"
```

**Tips:**
- Use channel names with `#` prefix or channel IDs
- For multiple links, wrap in `<>` to suppress embeds: `<https://example.com>`
- No markdown tables! Use bullet lists instead
- Support effects with `effect=balloons` or `effectId=invisible-ink`

### Reply to Messages

Reply to a specific message:

```bash
message action=send channel=discord target="#channel-name" message="Reply text" replyTo="message-id"
```

The `replyTo` parameter creates a threaded reply to the specified message ID.

### Search Messages

Search for messages in a channel:

```bash
message action=search channel=discord channelId="1234567890" query="search terms" limit=50
```

**Search options:**
- `query`: Search terms
- `authorId`: Filter by author
- `before`/`after`/`around`: Message ID for pagination
- `limit`: Max results (default 25)

See [SEARCH.md](references/SEARCH.md) for advanced search patterns.

### Other Actions

**Read messages:**
```bash
message action=read channel=discord target="#channel-name" limit=20
```

**React to messages:**
```bash
message action=react channel=discord messageId="1234567890" emoji="👍"
```

**Edit messages:**
```bash
message action=edit channel=discord messageId="1234567890" message="Updated text"
```

**Delete messages:**
```bash
message action=delete channel=discord messageId="1234567890"
```

## Quick Reference

Common patterns:

- **Announce to channel**: `action=send target="#announcements"`
- **Reply in thread**: `action=send replyTo="msg-id"`
- **Recent activity**: `action=read limit=10`
- **Find mentions**: `action=search query="@username"`
- **Acknowledge**: `action=react emoji="✅"`

## Channel Management

**List channels:**
```bash
message action=channel-list channel=discord guildId="server-id"
```

**Get channel info:**
```bash
message action=channel-info channel=discord channelId="1234567890"
```

For creating/editing channels, see [CHANNELS.md](references/CHANNELS.md).

## Best Practices

1. **Use target names when possible** - `target="#general"` is clearer than IDs
2. **Batch reactions** - One emoji per message, pick the best fit
3. **Format for Discord** - Bullets not tables, `<link>` to suppress embeds
4. **Search before asking** - Check history before requesting info
5. **React > Reply** - Use reactions for simple acknowledgments

## Configuration

Your Discord bot configuration should be in the gateway config. The `message` tool routes to the configured Discord plugin automatically when `channel=discord` is specified.

For setup help, see [CONFIG.md](references/CONFIG.md).


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/SEARCH.md

```markdown
# Discord Search Patterns

Advanced search patterns and examples for finding messages in Discord.

## Basic Search

```bash
message action=search channel=discord channelId="1234567890" query="keyword" limit=25
```

## Search Filters

### By Author

Find messages from a specific user:

```bash
message action=search channel=discord channelId="1234567890" authorId="user-id"
```

Or multiple authors:

```bash
message action=search channel=discord channelId="1234567890" authorIds='["user-id-1", "user-id-2"]'
```

### By Time Range

**Messages before a specific message:**
```bash
message action=search channel=discord channelId="1234567890" before="message-id"
```

**Messages after a specific message:**
```bash
message action=search channel=discord channelId="1234567890" after="message-id"
```

**Messages around a specific message:**
```bash
message action=search channel=discord channelId="1234567890" around="message-id"
```

### Combined Filters

Search with multiple criteria:

```bash
message action=search channel=discord channelId="1234567890" query="bug report" authorId="user-id" limit=10
```

## Pagination

Discord returns results in batches. Use message IDs for pagination:

1. First batch: `action=search query="keyword" limit=50`
2. Next batch: Use last message ID from results as `before` parameter
3. Continue: `action=search query="keyword" before="last-msg-id" limit=50`

## Common Search Patterns

### Find Recent Mentions

```bash
message action=search channel=discord channelId="1234567890" query="@me" limit=20
```

### Find Links

```bash
message action=search channel=discord channelId="1234567890" query="https://" limit=25
```

### Find User's Recent Messages

```bash
message action=search channel=discord channelId="1234567890" authorId="user-id" limit=30
```

### Search Across Multiple Channels

Run separate searches for each channel:

```bash
message action=search channel=discord channelId="channel-1" query="keyword"
message action=search channel=discord channelId="channel-2" query="keyword"
```

## Tips

- **Use specific queries** - "error in production" beats "error"
- **Limit wisely** - Start small (10-25), increase if needed
- **Combine filters** - Author + query + time range narrows results
- **Channel IDs required** - Search needs numeric channel ID, not name
- **Case insensitive** - Discord search ignores case by default

## Getting Channel IDs

If you only have channel names:

```bash
message action=channel-list channel=discord guildId="server-id"
```

This returns all channels with their IDs. Then use the ID in search.

```

### references/CHANNELS.md

```markdown
# Discord Channel Management

Create, edit, and manage Discord channels.

## List Channels

Get all channels in a server:

```bash
message action=channel-list channel=discord guildId="server-id"
```

Returns channel names, IDs, types, and hierarchy.

## Get Channel Info

Detailed info for a specific channel:

```bash
message action=channel-info channel=discord channelId="1234567890"
```

Returns name, topic, permissions, member count, etc.

## Create Channels

**Create text channel:**
```bash
message action=channel-create channel=discord guildId="server-id" name="new-channel" type=0
```

**Create voice channel:**
```bash
message action=channel-create channel=discord guildId="server-id" name="voice-room" type=2
```

**Create with topic:**
```bash
message action=channel-create channel=discord guildId="server-id" name="discussions" type=0 topic="General discussions"
```

**Create in category:**
```bash
message action=channel-create channel=discord guildId="server-id" name="support" type=0 parentId="category-id"
```

## Channel Types

- `0` - Text channel
- `2` - Voice channel
- `4` - Category
- `5` - Announcement channel
- `10` - Announcement thread
- `11` - Public thread
- `12` - Private thread
- `13` - Stage channel
- `15` - Forum channel

## Edit Channels

Update channel properties:

```bash
message action=channel-edit channel=discord channelId="1234567890" name="renamed-channel"
```

**Change topic:**
```bash
message action=channel-edit channel=discord channelId="1234567890" topic="New topic"
```

**Change position:**
```bash
message action=channel-edit channel=discord channelId="1234567890" position=5
```

**Toggle NSFW:**
```bash
message action=channel-edit channel=discord channelId="1234567890" nsfw=true
```

**Slow mode:**
```bash
message action=channel-edit channel=discord channelId="1234567890" rateLimitPerUser=10
```

Rate limit is in seconds (0-21600). 0 disables slow mode.

## Move Channels

Move channel to different category:

```bash
message action=channel-move channel=discord channelId="1234567890" parentId="new-category-id"
```

Remove from category:

```bash
message action=channel-move channel=discord channelId="1234567890" clearParent=true
```

## Delete Channels

**Delete a channel:**
```bash
message action=channel-delete channel=discord channelId="1234567890"
```

**With reason (audit log):**
```bash
message action=channel-delete channel=discord channelId="1234567890" reason="No longer needed"
```

⚠️ **Warning**: Deletion is permanent. Cannot be undone.

## Categories

**Create category:**
```bash
message action=category-create channel=discord guildId="server-id" name="HELP DESK"
```

**Edit category:**
```bash
message action=category-edit channel=discord categoryId="1234567890" name="SUPPORT"
```

**Delete category:**
```bash
message action=category-delete channel=discord categoryId="1234567890"
```

Note: Deleting a category doesn't delete channels inside it. They become uncategorized.

## Threads

**Create thread from message:**
```bash
message action=thread-create channel=discord channelId="1234567890" messageId="msg-id" threadName="Discussion"
```

**Create standalone thread:**
```bash
message action=thread-create channel=discord channelId="1234567890" threadName="New Topic"
```

**List threads:**
```bash
message action=thread-list channel=discord channelId="1234567890"
```

**Reply in thread:**
```bash
message action=thread-reply channel=discord threadId="thread-id" message="Reply text"
```

## Permissions

Check user/role permissions in a channel:

```bash
message action=permissions channel=discord channelId="1234567890" userId="user-id"
```

Or for a role:

```bash
message action=permissions channel=discord channelId="1234567890" roleId="role-id"
```

## Pins

**Pin message:**
```bash
message action=pin channel=discord messageId="1234567890"
```

**Unpin message:**
```bash
message action=unpin channel=discord messageId="1234567890"
```

**List pinned messages:**
```bash
message action=list-pins channel=discord channelId="1234567890"
```

## Best Practices

1. **Name channels clearly** - Use descriptive, lowercase-with-hyphens names
2. **Set topics** - Help users understand channel purpose
3. **Use categories** - Organize related channels together
4. **Check before deleting** - Deletion is permanent
5. **Document reasons** - Use `reason` parameter for audit logs
6. **Test permissions** - Verify bot has needed permissions before operations

```

### references/CONFIG.md

```markdown
# Discord Bot Configuration

Guide to configuring Discord integration in Clawdbot gateway.

## Overview

Discord integration uses the `message` tool with `channel=discord`. Your bot token and guild info should be configured in the gateway config.

## Configuration Structure

Your gateway config should have a Discord channel plugin entry:

```yaml
channels:
  discord:
    plugin: discord
    token: "YOUR_BOT_TOKEN"
    guildId: "YOUR_GUILD_ID"  # Default guild/server
    # Optional settings:
    logMessages: true
    defaultChannel: "1234567890"  # Default channel ID
```

## Getting Bot Token

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create new application or select existing
3. Go to "Bot" section
4. Click "Reset Token" to get your token
5. **Important**: Keep token secret! Don't commit to git

## Bot Permissions

Your bot needs these permissions (integer: 2147485696):

- Read Messages/View Channels
- Send Messages
- Embed Links
- Attach Files
- Read Message History
- Add Reactions
- Use Slash Commands (optional)

**Permission calculator**: https://discord.com/developers/docs/topics/permissions

## Invite Bot to Server

Generate invite URL with correct permissions:

```
https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=2147485696&scope=bot
```

Replace `YOUR_CLIENT_ID` with your application's client ID from the developer portal.

## Getting Guild/Channel IDs

### Enable Developer Mode

1. Discord Settings → Advanced → Enable Developer Mode
2. Now you can right-click servers/channels to copy IDs

### Get Guild ID

Right-click your server name → Copy Server ID

### Get Channel ID

Right-click channel name → Copy Channel ID

## Testing Configuration

Once configured, test with:

```bash
message action=channel-list channel=discord guildId="YOUR_GUILD_ID"
```

Should return list of channels in your server.

## Multiple Guilds

To interact with multiple Discord servers, specify `guildId` in each command:

```bash
message action=send channel=discord guildId="server-1-id" target="#general" message="Hi"
message action=send channel=discord guildId="server-2-id" target="#general" message="Hello"
```

## Webhook Inbound

For receiving Discord events (messages, reactions), configure webhook:

```yaml
channels:
  discord:
    plugin: discord
    token: "YOUR_BOT_TOKEN"
    webhook:
      enabled: true
      path: /webhook/discord
      secret: "random-secret-string"
```

Then configure Discord webhook in your guild:
1. Server Settings → Integrations → Webhooks
2. Create webhook pointing to `https://your-gateway.com/webhook/discord`
3. Include secret in webhook headers or query params

## Troubleshooting

**"Missing Permissions" error:**
- Check bot has correct permissions in Discord server
- Verify role hierarchy (bot role must be high enough)

**"Unknown Channel" error:**
- Verify channel ID is correct
- Check bot can see the channel

**No response:**
- Verify bot is online in Discord
- Check token is valid
- Review gateway logs for errors

**Messages not sending:**
- Check bot has "Send Messages" permission
- Verify channel isn't locked/archived
- Test with `action=channel-info` first

## Security

1. **Never commit tokens** - Use environment variables
2. **Rotate tokens** - If exposed, regenerate immediately
3. **Limit permissions** - Only grant what's needed
4. **Use secrets** - For webhook verification
5. **Monitor usage** - Watch for unexpected activity

## Environment Variables

Recommended: Store sensitive data in environment:

```yaml
channels:
  discord:
    plugin: discord
    token: ${DISCORD_BOT_TOKEN}
    guildId: ${DISCORD_GUILD_ID}
```

Then set in shell:
```bash
export DISCORD_BOT_TOKEN="your-token"
export DISCORD_GUILD_ID="your-guild-id"
```

## Updating Config

After editing gateway config, restart:

```bash
clawdbot gateway restart
```

Or use the gateway tool:

```bash
gateway action=config.patch raw='{"channels":{"discord":{"token":"new-token"}}}'
```

## Resources

- [Discord Developer Portal](https://discord.com/developers/applications)
- [Discord API Docs](https://discord.com/developers/docs)
- [Permissions Calculator](https://discord.com/developers/docs/topics/permissions)
- [Discord.js Guide](https://discordjs.guide) (for reference)

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "bowenqt",
  "slug": "discord-chat",
  "displayName": "Discord Chat",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1769502876749,
    "commit": "https://github.com/clawdbot/skills/commit/810065e8d1c091df4fa918dc2823648b6df58c8b"
  },
  "history": []
}

```