Back to Details

discordbot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
We drive the Discord API with 
curl + jq
using the user's bot token in 
$DISCORDBOT_TOKEN
. The auth header is 
Authorization: Bot $DISCORDBOT_TOKEN
— note the literal 
Bot
prefix (NOT 
Bearer
). Base URL is 
https://discord.com/api/v10
.
This acts as the user's registered bot, so it can only see and act in servers (guilds) the bot has been invited to and only where it has the relevant permission (View Channels / Send Messages / Read Message History). A 
403 Forbidden
(code 50001 "Missing Access" / 50013 "Missing Permissions") almost always means the bot isn't in that server or lacks the permission — tell the user to invite the bot or grant the permission rather than retrying.
Errors are JSON 
{"code": <n>, "message": "<reason>"}
. A 
401
means the bot token is wrong/reset — ask the user to re-paste it at 
auth.acedata.cloud/user/connections
. A 
429
carries 
retry_after
(seconds) — sleep that long, then retry; never parallelize.
Before sending a message, confirm the exact channel and content with the user. Sending is irreversible and public to that channel.
我们借助用户存储在
$DISCORDBOT_TOKEN
中的bot令牌，通过
curl + jq
调用Discord API 请求头的认证信息为
Authorization: Bot $DISCORDBOT_TOKEN
——注意这里需要字面的
Bot
前缀（不是
Bearer
）。基础URL为
https://discord.com/api/v10
。
此操作代表用户已注册的bot执行，因此它只能查看和操作已受邀加入的服务器（guilds），且仅在拥有相关权限（查看频道/发送消息/读取消息历史）的范围内进行。若返回
403 Forbidden
错误（错误码50001“缺少访问权限”/50013“缺少权限”），几乎总是意味着Bot未加入该服务器或缺少对应权限——此时应告知用户邀请Bot或授予相应权限，而非重试请求。
错误信息为JSON格式
{"code": <n>, "message": "<reason>"}
。若返回
401
错误，说明Bot令牌错误或已重置——请用户前往
auth.acedata.cloud/user/connections
重新粘贴令牌。若返回
429
错误，响应中会包含
retry_after
（秒数）——需等待对应时长后重试，切勿并行请求。
**发送消息前，请与用户确认准确的频道和消息内容。**消息一旦发送便不可撤回，且对该频道内所有成员可见。

Recipes

操作示例

Verify the bot (always run first)

验证Bot身份（务必先执行此步骤）

sh
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me" \
  | jq '{id, username, bot}'
sh
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me" \
  | jq '{id, username, bot}'

List servers (guilds) the bot is in

列出Bot已加入的服务器（guilds）

sh
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me/guilds" \
  | jq 'map({id, name})'
sh
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me/guilds" \
  | jq 'map({id, name})'

List text channels in a server

列出服务器内的文本频道

Channel 
type
0 = text, 5 = announcement; 2 = voice, 4 = category (skip those for messaging). You need a guild id from the call above.
sh
GUILD_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/guilds/$GUILD_ID/channels" \
  | jq 'map(select(.type==0 or .type==5) | {id, name, type})'
频道
type
值为0代表文本频道，5代表公告频道；2为语音频道，4为分类频道（发送消息时可跳过这些类型）。你需要从上述调用中获取服务器ID（guild id）。
sh
GUILD_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/guilds/$GUILD_ID/channels" \
  | jq 'map(select(.type==0 or .type==5) | {id, name, type})'

Read recent messages in a channel

读取频道内的最新消息

Reading message content requires the Message Content Intent to be enabled on the bot (Developer Portal → Bot → Privileged Gateway Intents). Without it, 
content
comes back empty for messages that don't mention the bot. Needs the Read Message History permission in that channel.
sh
CHANNEL_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages?limit=20" \
  | jq 'map({author: .author.username, ts: .timestamp, content})'
读取消息内容需要在Bot设置中启用Message Content Intent（开发者门户→Bot→特权网关意图）。若未启用，对于未提及Bot的消息，
content
字段会返回空值。此外，Bot需要拥有该频道的读取消息历史权限。
sh
CHANNEL_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages?limit=20" \
  | jq 'map({author: .author.username, ts: .timestamp, content})'

Send a message to a channel

向频道发送消息

sh
CHANNEL_ID="123456789012345678"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "Hello from the bot." '{content: $c}')"
sh
CHANNEL_ID="123456789012345678"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "Hello from the bot." '{content: $c}')"

Reply to a specific message

回复特定消息

sh
CHANNEL_ID="123456789012345678"; MESSAGE_ID="987654321098765432"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "On it!" --arg m "$MESSAGE_ID" \
        '{content: $c, message_reference: {message_id: $m}}')"
sh
CHANNEL_ID="123456789012345678"; MESSAGE_ID="987654321098765432"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "On it!" --arg m "$MESSAGE_ID" \
        '{content: $c, message_reference: {message_id: $m}}')"

Notes

注意事项

  • A "server" in the UI is a "guild" in the API; messages live in channels inside guilds. Always: list guilds → list that guild's channels → act on a channel id. Don't invent ids.
  • The bot only sees servers it was invited to. To add it: Developer Portal → OAuth2 → URL Generator → scope 
    bot
    + the permissions you need → open the URL → pick a server (the user needs Manage Server there).
  • This is a bot, not the user's account — it cannot read the user's DMs or the user's full server list, only what the bot itself can access.
  • Mentions: 
    <@USER_ID>
    pings a user, 
    <#CHANNEL_ID>
    links a channel. Plain text is fine for normal messages.
  • UI中的“server”对应API中的“guild”；消息存储在guild内的频道中。操作流程应为：列出guilds→列出该guild的频道→通过频道ID执行操作。请勿自行编造ID。
  • Bot仅能查看已受邀加入的服务器。添加Bot的步骤：开发者门户→OAuth2→URL生成器→选择
    bot
    权限范围+所需权限→打开生成的URL→选择服务器（用户需拥有该服务器的管理服务器权限）。
  • 这是Bot账号，而非用户个人账号——它无法读取用户的私信或用户的完整服务器列表，仅能访问Bot自身有权限的内容。
  • 提及格式：
    <@USER_ID>
    用于@用户，
    <#CHANNEL_ID>
    用于链接频道。普通消息使用纯文本即可。