---
name: discord-get-messages
description: Retrieve messages from Discord channels via the Discord API. Use this skill when the user wants to read, search, or analyze messages from a Discord channel.
---

# Discord Get Messages

Retrieve messages from Discord channels using the Discord API v10. This skill supports pagination, filtering by message count, and retrieving message history.

## When to Use This Skill

Use this skill when the user wants to:
- Read recent messages from a Discord channel
- Get message history for analysis
- Search for specific messages in a channel
- Retrieve messages before or after a specific message ID
- Export channel conversation history

## Prerequisites

- `DISCORD_BOT_TOKEN` environment variable must be set
- Bot must be a member of the target server
- Bot must have "Read Message History" permission in the target channel
- Valid Discord channel ID (18-19 digit snowflake ID)

## Instructions

When the user requests to retrieve Discord messages:

1. **Validate Requirements**
   - Confirm `DISCORD_BOT_TOKEN` is set in environment
   - Verify channel ID is provided (18-19 digit number)
   - Validate limit parameter (1-100 messages)

2. **Prepare Query Parameters**
   - `limit`: Number of messages to retrieve (default: 50, max: 100)
   - `before`: Get messages before this message ID (for pagination)
   - `after`: Get messages after this message ID
   - `around`: Get messages around this message ID

3. **Make the API Request**
   Use the following curl command structure:

   ```bash
   curl -X GET "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages?limit=50" \
     -H "Authorization: Bot ${DISCORD_BOT_TOKEN}"
   ```

   Replace:
   - `{CHANNEL_ID}` with the actual channel ID
   - `limit=50` with desired message count (1-100)

4. **Process Response**
   - Messages are returned in reverse chronological order (newest first)
   - Each message contains: id, content, author, timestamp, attachments, embeds
   - Filter or format messages as requested by user

5. **Handle Response Codes**
   - 200 Success: Messages retrieved successfully
   - 401 Unauthorized: Invalid bot token
   - 403 Forbidden: Missing "Read Message History" permission
   - 404 Not Found: Channel doesn't exist or bot can't see it

6. **Present Results**
   - Format messages in a readable way
   - Show author, timestamp, and content
   - Include attachment URLs if present
   - Summarize if many messages retrieved

## Query Parameters

### Limit
```bash
?limit=10  # Get 10 most recent messages (default: 50, max: 100)
```

### Before (Pagination)
```bash
?before=1234567890123456789&limit=50  # Get 50 messages before this message ID
```

### After
```bash
?after=1234567890123456789&limit=50  # Get 50 messages after this message ID
```

### Around
```bash
?around=1234567890123456789&limit=50  # Get 50 messages around this message ID
```

## Message Object Structure

Each message returned contains:
```json
{
  "id": "1234567890123456789",
  "channel_id": "123456789012345678",
  "author": {
    "id": "987654321098765432",
    "username": "Username",
    "discriminator": "0000",
    "avatar": "avatar_hash"
  },
  "content": "Message text content",
  "timestamp": "2025-10-20T12:00:00.000000+00:00",
  "edited_timestamp": null,
  "tts": false,
  "mention_everyone": false,
  "mentions": [],
  "mention_roles": [],
  "attachments": [],
  "embeds": [],
  "reactions": [],
  "pinned": false,
  "type": 0
}
```

## Formatting Output

### Simple Format
```
[2025-10-20 12:00] Username: Message content here
[2025-10-20 11:55] OtherUser: Another message
```

### Detailed Format
```
Message ID: 1234567890123456789
Author: Username#0000 (987654321098765432)
Timestamp: 2025-10-20T12:00:00.000000+00:00
Content: Message text content here
Attachments: image.png (https://cdn.discordapp.com/...)
```

## Filtering and Processing

### Filter by Author
After retrieving messages, filter by author ID or username:
```bash
# Get messages then filter in output
curl ... | jq '.[] | select(.author.username == "TargetUser")'
```

### Filter by Content
Search for specific keywords in message content:
```bash
# Get messages then search content
curl ... | jq '.[] | select(.content | contains("keyword"))'
```

### Get Only Text Messages
Exclude system messages and embeds:
```bash
# Filter message type 0 (default text messages)
curl ... | jq '.[] | select(.type == 0)'
```

## Pagination Strategy

To retrieve more than 100 messages:

1. Get first batch: `?limit=100`
2. Get oldest message ID from response
3. Get next batch: `?before={oldest_id}&limit=100`
4. Repeat until all messages retrieved or desired count reached

**Example:**
```bash
# First batch
curl "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages?limit=100" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}"

# Get oldest message ID from response (e.g., 1234567890123456789)

# Next batch
curl "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages?before=1234567890123456789&limit=100" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}"
```

## Error Handling

### Common Errors

**401 Unauthorized**
- Check that `DISCORD_BOT_TOKEN` is set correctly
- Verify token hasn't expired

**403 Forbidden**
- Bot needs "Read Message History" permission
- Bot needs "View Channel" permission
- Check channel permission overrides

**404 Not Found**
- Channel ID is incorrect
- Channel was deleted
- Bot doesn't have access to channel

**400 Bad Request**
- Invalid limit parameter (must be 1-100)
- Invalid message ID format for before/after/around

## Rate Limiting

- Discord allows 5 requests per 5 seconds per channel
- Implement delays between requests when paginating
- Wait 1 second between pagination requests

## Security Notes

- Never expose the bot token in messages or logs
- Respect user privacy when handling message content
- Don't store messages longer than necessary
- Follow Discord's Terms of Service regarding data retention

## Performance Tips

- Use `limit` parameter to reduce response size
- Retrieve only the messages you need
- Cache results if querying the same channel multiple times
- Use pagination for large history retrieval

## Examples

See `examples.md` for detailed usage scenarios.

## API Reference

- Endpoint: `GET /channels/{channel.id}/messages`
- Discord API Version: v10
- Documentation: https://discord.com/developers/docs/resources/channel#get-channel-messages


---
Source attribution: Nice-Wolf-Studio
Original project: https://github.com/Nice-Wolf-Studio/agent-discord-skills/blob/07f7cc9119a766fc06b871115e945a8965936251/skills/discord-get-messages/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Nice-Wolf-Studio

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: Nice-Wolf-Studio
Original project: https://github.com/Nice-Wolf-Studio/agent-discord-skills/blob/07f7cc9119a766fc06b871115e945a8965936251/skills/discord-get-messages/SKILL.md
Attribution basis: Recovered original package and original project license at a pinned revision

Fields of work: Marketing, Customer Support
Roles: Community Manager, Customer Experience, Social Media Manager
Specialties: API
Tools: Discord
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 2348699127e43100e6106fe85684cf645c2f681d7c470a78262c283f47913b2d
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.