机器人发送并读取频道消息

使用 Bot Token 发送一条文字，并分页读取机器人有权查看的频道消息。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

应用以 Guild Install 安装到测试服务器；频道允许 VIEW_CHANNEL、SEND_MESSAGES。
读取历史另需 READ_MESSAGE_HISTORY；message content 特权 intent 影响返回的文本等字段，不能用空 content 判断无消息。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

DISCORD_BOT_TOKEN: Developer Portal → Bot 中生成的 Token；Authorization 前缀是 Bot，不是 Bearer。
DISCORD_CHANNEL_ID: 目标文本频道 ID，按字符串处理，避免 JavaScript 精度丢失。

export DISCORD_BOT_TOKEN='replace_with_bot_token'
export DISCORD_CHANNEL_ID='333333333333333333'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
Developer Portal → Bot 生成 Token，并通过带 bot scope 的安装链接安装。
02
Discord 用户设置 → Advanced 开启 Developer Mode，右键目标频道复制 ID，保存为 DISCORD_CHANNEL_ID。
03
先发送一条测试消息，再读取最近 20 条；用返回的 message id 继续向前分页。

调用 01

创建频道消息

Bot Token 前缀为 Bot；allowed_mentions 禁止意外提醒。

POSThttps://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages

请求头

Authorization: Bot ${DISCORD_BOT_TOKEN}
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`channel_id`Path	snowflake必填	目标频道 ID。
`content`请求体	string必填	本例最多 2000 字符的普通文本。
`allowed_mentions.parse`请求体	string[]可选	空数组表示不自动解析提醒。
`nonce / enforce_nonce`请求体	string / boolean可选	nonce 最多 25 字符；如需近期重复检查，传 nonce 并将 enforce_nonce=true，勿把它当永久幂等存储。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cat > request-body.json <<'JSON'
{
  "content": "接入测试：机器人服务正常",
  "allowed_mentions": {
    "parse": []
  }
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages" \
  --header "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages")
headers = {
    "Authorization": expand("Bot ${DISCORD_BOT_TOKEN}"),
    "Content-Type": expand("application/json"),
}
body = {
    "content": "接入测试：机器人服务正常",
    "allowed_mentions": {
        "parse": [],
    },
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bot ${DISCORD_BOT_TOKEN}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "content": "接入测试：机器人服务正常",
  "allowed_mentions": {
    "parse": []
  }
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。保存返回的 id，可用于后续更新或回复。以下为结构示意，非本站实测结果。

{
  "id": "444444444444444444",
  "channel_id": "333333333333333333",
  "content": "接入测试：机器人服务正常",
  "author": {
    "id": "555555555555555555",
    "bot": true,
    "username": "ExampleBot"
  }
}

常见错误与排查

HTTP 401凭证无效或认证格式错误: 核对 Bot Token 与 Bot 前缀，或 Webhook ID/Token。
HTTP 403权限不足: 检查服务器安装权限及频道覆盖规则。
HTTP 404资源不存在或不可访问: 核对 ID 和机器人可见范围，不要反复请求已删除资源。
HTTP 429请求限流: 按 retry_after 或 Retry-After 等待，并遵守响应中的 rate limit bucket。

调用注意

Bot 应获得频道权限；不需要申请 Administrator 作为便利方案。

Message Resource

调用 02

读取最近频道消息

响应是消息数组，没有 cursor 外层。

GEThttps://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages?limit=20

请求头

Authorization: Bot ${DISCORD_BOT_TOKEN}
Content-Type: application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`limit`Query	integer可选	1–100，默认 50；本例 20。
`before`Query	snowflake可选	向旧消息翻页时填上一页最旧消息 ID。
`after / around`Query	snowflake可选	分别查询某 ID 之后或附近；before、after、around 互斥。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages?limit=20" \
  --header "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  --header "Content-Type: application/json"

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages?limit=20")
headers = {
    "Authorization": expand("Bot ${DISCORD_BOT_TOKEN}"),
    "Content-Type": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://discord.com/api/v10/channels/${DISCORD_CHANNEL_ID}/messages?limit=20");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bot ${DISCORD_BOT_TOKEN}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。数组长度为 0 时当前方向无结果；不要把 ID 转成浮点数。以下为结构示意，非本站实测结果。

[
  {
    "id": "444444444444444444",
    "channel_id": "333333333333333333",
    "content": "接入测试：机器人服务正常",
    "author": {
      "id": "555555555555555555",
      "bot": true
    }
  }
]

常见错误与排查

HTTP 401凭证无效或认证格式错误: 核对 Bot Token 与 Bot 前缀，或 Webhook ID/Token。
HTTP 403权限不足: 检查服务器安装权限及频道覆盖规则。
HTTP 404资源不存在或不可访问: 核对 ID 和机器人可见范围，不要反复请求已删除资源。
HTTP 429请求限流: 按 retry_after 或 Retry-After 等待，并遵守响应中的 rate limit bucket。

调用注意

需要 VIEW_CHANNEL 与 READ_MESSAGE_HISTORY；没有历史权限时无法取得所需历史。
MESSAGE_CONTENT intent 未配置或未经适用审核时，content、embeds、attachments 等可能为空；仅持 Bot Token 不自动获得消息全文。

Message Resource

注意事项

此 REST 场景不建立 Gateway 连接；实时监听事件需单独实现心跳、会话恢复与 intents。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
Building your first Discord Bot核验日期 2026-10-15
02
Message Resource核验日期 2026-10-15
03
Rate Limits核验日期 2026-10-15

Discord 开发者平台的其他调用手册

使用 Webhook 向频道发通知注册测试命令并处理签名回调

← 返回Discord 开发者平台的全部功能