nice-wolf-studio/agent-discord-skills/discord-get-messages

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)

1. 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

1. 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)

1. 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

1. 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

1. 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

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

Before (Pagination)

?before=1234567890123456789&limit=50  # Get 50 messages before this message ID

After

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

Around

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

Message Object Structure

Each message returned contains:

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

# Get messages then filter in output
curl ... | jq '.[] | select(.author.username == "TargetUser")'

Filter by Content

Search for specific keywords in message content:

# Get messages then search content
curl ... | jq '.[] | select(.content | contains("keyword"))'

Get Only Text Messages

Exclude system messages and embeds:

# 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:

# 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