openhands/discord

Discord

Use this skill when implementing or automating Discord integrations.

Pick the right approach

1. Incoming webhooks (best for one-way posting)

   • Good for CI notifications, alerts, build status, etc.
   • No bot user needed.
   • See: https://discord.com/developers/docs/resources/webhook#execute-webhook

2. Bot token + REST API (two-way / richer automation)

   • Use when you need to post as a bot, manage channels, read history, moderate, etc.
   • REST API base: https://discord.com/api/v10
   • Most REST calls use Authorization: Bot <token>.

3. Interactions / slash commands (user-invoked commands)

   • Use application commands and interaction webhooks.
   • Typically requires running a web server to receive interactions and respond quickly.

Secrets & safety

• Never hard-code tokens. Use environment variables:
  • DISCORD_WEBHOOK_URL for incoming webhooks
  • DISCORD_BOT_TOKEN for bot REST API calls
• Treat webhook URLs as secrets (they include a token).
• Do not automate normal user accounts (“self-bots”). Use official bot/OAuth flows.

Footguns / safety notes (read this)

• Webhook URLs are secrets (the token is embedded in the URL). Don’t paste them into issues, logs, CI output, or chat.
• Mentions are dangerous by default: always set allowed_mentions to something strict (these examples use {"parse": []}) to avoid accidentally pinging @everyone / roles.
• Watch for accidental secret logging:
  • If you build your own scripts, avoid including full webhook URLs in exception messages.
  • The bundled scripts sanitize webhook URLs in error output, but you should still avoid printing the URL yourself.
• Rate limits: handle HTTP 429 with retry_after/Retry-After, and don’t retry forever.

Quick recipes

The shell snippets below use POSIX-style environment variables and line continuations. On Windows PowerShell, use curl.exe for the shown flags and $env:DISCORD_WEBHOOK_URL / $env:DISCORD_BOT_TOKEN for environment variables, or translate the request to Invoke-RestMethod.

Post a message via an incoming webhook (recommended)

Discord requires at least one of content, embeds, components, file, or poll.

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from OpenHands","allowed_mentions":{"parse":[]}}' \
  "$DISCORD_WEBHOOK_URL"

Post a message to a channel with a bot token

Endpoint: POST /channels/{channel_id}/messages (Create Message)

CHANNEL_ID="..."

curl -sS -X POST "https://discord.com/api/v10/channels/${CHANNEL_ID}/messages" \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from my bot","allowed_mentions":{"parse":[]}}'

Docs: https://discord.com/developers/docs/resources/channel#create-message

Automation scripts (bundled)

These scripts are self-contained and only use the Python standard library.

• Post to a webhook:

  python3 -m skills.discord.scripts.post_webhook --content "Build finished" --wait
  

• Post to a channel using a bot token:

  python3 -m skills.discord.scripts.send_message --channel-id "$CHANNEL_ID" --content "Hello"
  

Rate limits

• Don’t hard-code limits. Use Discord’s Retry-After / retry_after and rate-limit headers when present.
• On HTTP 429, wait for the provided delay (clamp to a sane maximum, add small jitter), then retry.

Docs: https://discord.com/developers/docs/topics/rate-limits

Slash commands / application commands

• Use guild commands for fast iteration (instant updates).
• Use global commands when ready; propagation can take longer.

Docs: https://discord.com/developers/docs/interactions/application-commands

Reference

For more details (OAuth2 flows, command registration endpoints, troubleshooting), see:

• references/REFERENCE.md