Discord 开发者平台调用手册
使用 Webhook 向频道发通知
无需创建 Bot 用户,通过指定频道的 Incoming Webhook 发布通知并拿到消息 ID。
← 返回平台功能接入准备
- 有权在目标频道管理 Webhook,或由频道管理员提供已创建的 Incoming Webhook。
- Webhook URL 中 ID 和 Token 都需要保密;本例选择普通文本频道。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
DISCORD_WEBHOOK_ID- Webhook 的 snowflake ID,按字符串处理。
DISCORD_WEBHOOK_TOKEN- Webhook Token,不是 Bot Token。
export DISCORD_WEBHOOK_ID='111111111111111111'
export DISCORD_WEBHOOK_TOKEN='replace_with_webhook_token'以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。
调用步骤
- 01
服务器设置/频道设置 → Integrations → Webhooks 创建并复制 Webhook。
- 02
从 /webhooks/{id}/{token} 取得两段值,分别保存到环境变量。
- 03
执行 wait=true 的推送,返回真实消息对象后再记录成功;默认 wait=false 常返回 204。
调用 01
执行 Incoming Webhook
显式使用 wait=true 取得服务端确认及消息对象。
POST
https://discord.com/api/v10/webhooks/${DISCORD_WEBHOOK_ID}/${DISCORD_WEBHOOK_TOKEN}?wait=true请求头
Content-Typeapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
webhook_id / webhook_tokenPath | string必填 | 复制自 Webhook URL;不用 Authorization。 |
waitQuery | boolean可选 | 默认 false;本例 true,等待服务端确认并返回消息。 |
content请求体 | string必填 | 本例文本通知,最多 2000 字符;使用其他消息类型时可省略但至少提供一种内容。 |
allowed_mentions请求体 | object可选 | parse=[] 禁止自动触发 @everyone/角色/用户提醒,适合系统通知。 |
调用代码
替换示例 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/webhooks/${DISCORD_WEBHOOK_ID}/${DISCORD_WEBHOOK_TOKEN}?wait=true" \
--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/webhooks/${DISCORD_WEBHOOK_ID}/${DISCORD_WEBHOOK_TOKEN}?wait=true")
headers = {
"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/webhooks/${DISCORD_WEBHOOK_ID}/${DISCORD_WEBHOOK_TOKEN}?wait=true");
const headers = Object.fromEntries(
Object.entries({
"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 与 channel_id;响应体本身是 Message,不带 data 外层。 以下为结构示意,非本站实测结果。
{
"id": "222222222222222222",
"channel_id": "333333333333333333",
"content": "接入测试:通知服务已启动",
"webhook_id": "111111111111111111"
}常见错误与排查
HTTP 401凭证无效或认证格式错误- 核对 Bot Token 与 Bot 前缀,或 Webhook ID/Token。
HTTP 403权限不足- 检查服务器安装权限及频道覆盖规则。
HTTP 404资源不存在或不可访问- 核对 ID 和机器人可见范围,不要反复请求已删除资源。
HTTP 429请求限流- 按 retry_after 或 Retry-After 等待,并遵守响应中的 rate limit bucket。
调用注意
- 论坛或媒体频道必须额外指定 thread_id 或 thread_name;本例普通文本频道不需要。
- 按 rate limit 响应头和 429 退避,不硬编码统一速率。
注意事项
- Webhook 发消息不赋予读取任意频道历史的权限;撤销 Token 后旧 URL 失效。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01Webhook Resource核验日期 2026-10-15
- 02Rate Limits核验日期 2026-10-15