Discord History Reader

intent

fetch message history from any discord channel or thread using direct api calls instead of relying on openclaw's session-based message visibility. use this when you need context from threads you weren't mentioned in, channels outside your active sessions, or historical conversations you need to reference. common triggers: "read that thread", "what did they say in #channel", "fetch discord messages", "get thread history", "i can't see that thread".

inputs

discord bot token

• location: ~/.openclaw/.discord-bot-token (user-managed file outside workspace)
• setup: run once as the user: echo 'YOUR_DISCORD_BOT_TOKEN' > ~/.openclaw/.discord-bot-token && chmod 600 ~/.openclaw/.discord-bot-token
• permissions required: bot must have "View Channel" + "Read Message History" in target guild
• rotation: if token is rotated in discord developer portal, update both openclaw config and the token file

channel or thread id

• obtain by enabling developer mode in discord (user settings → advanced → developer mode)
• right-click channel/thread → copy channel id
• note: threads and channels use the same id structure in the api

pagination parameters (optional)

• limit: number of messages to fetch (1-100, default 50)
• before: message id to fetch messages older than this one
• after: message id to fetch messages newer than this one

procedure

1. load the discord bot token from the token file.

   • input: file path ~/.openclaw/.discord-bot-token
   • output: DISCORD_TOKEN environment variable set in shell
   • command: DISCORD_TOKEN=$(cat ~/.openclaw/.discord-bot-token)

2. construct the discord api endpoint url for the target channel or thread.

   • input: channel_or_thread_id, optional limit, optional before/after message id
   • output: full api url string
   • example url for recent messages: https://discord.com/api/v10/channels/{channel_id}/messages?limit=50
   • example url with pagination: https://discord.com/api/v10/channels/{channel_id}/messages?limit=50&before={message_id}

3. execute the curl request with bot authorization header.

   • input: DISCORD_TOKEN, api url
   • output: raw json response from discord
   • command: curl -s -H "Authorization: Bot $DISCORD_TOKEN" "https://discord.com/api/v10/channels/{channel_id}/messages?limit=50"

4. parse the json response and extract message fields.

   • input: raw json from discord api
   • output: formatted message objects with content, author, timestamp, id, referenced_message
   • command: pipe to python3 -m json.tool for pretty-printing or parse programmatically

5. (optional) paginate backwards for older messages if needed.

   • input: oldest message id from previous response, channel_id, DISCORD_TOKEN
   • output: next batch of older messages
   • repeat step 3 with before={oldest_message_id} parameter appended to url

decision points

if listing active threads in a guild channel (not reading messages)

• use endpoint: https://discord.com/api/v10/channels/{parent_channel_id}/threads/active
• else: use the /messages endpoint to read message history

if you receive a 429 rate limit response

• check the Retry-After header in the response (in seconds)
• wait that duration before retrying
• else: proceed immediately

if you receive a 401 unauthorized response

• the bot token is invalid, expired, or incorrect
• else: the token is valid; check other error codes (403 forbidden, 404 not found)

if the api returns an empty message array

• the channel exists but has no messages, or pagination bounds are exhausted
• else: messages were successfully retrieved

if the bot is not a member of the guild

• request will return 403 forbidden; bot must be invited to the guild first
• else: bot has access and request will succeed

if network timeout or connection error occurs

• retry after a brief delay (e.g., 2-5 seconds), up to 3 times total
• else: assume the request succeeded

output contract

discord api returns a json array of message objects. each object contains:

• id (string): unique message identifier
• channel_id (string): id of the channel message is in
• author (object): username, global_name, id, avatar
• content (string): message text
• timestamp (iso 8601 string): when the message was sent
• edited_timestamp (iso 8601 string or null): when last edited
• referenced_message (object or null): if this is a reply, the original message object
• embeds (array): rich embeds (links, images, etc.)
• attachments (array): file attachments with urls

messages are returned newest-first by default. response includes headers with rate limit info:

• X-RateLimit-Limit: requests allowed per minute
• X-RateLimit-Remaining: requests left in current window
• X-RateLimit-Reset: unix timestamp when limit resets
• Retry-After: (on 429) seconds to wait before retry

outcome signal

you have successfully read discord message history when:

• curl command returns http 200 with a valid json array
• you can extract and display author.username, content, and timestamp from at least one message object
• if you paginate, subsequent requests include older messages (sorted by timestamp descending)
• you see actual channel/thread content that was not visible in your openclaw session before

failure signals:

• http 401: token is invalid or expired; regenerate and store new token
• http 403: bot lacks "View Channel" or "Read Message History" permission; check guild role settings
• http 404: channel_id does not exist; verify id is correct and enable developer mode to re-copy
• http 429: rate limit exceeded; respect the Retry-After header and wait before retrying
• empty json array: channel exists but has no messages in the requested range; adjust before/after bounds or confirm channel has history