Discord 开发者平台调用手册

使用 Webhook 向频道发通知

无需创建 Bot 用户,通过指定频道的 Incoming Webhook 发布通知并拿到消息 ID。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 有权在目标频道管理 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。

调用步骤

  1. 01

    服务器设置/频道设置 → Integrations → Webhooks 创建并复制 Webhook。

  2. 02

    从 /webhooks/{id}/{token} 取得两段值,分别保存到环境变量。

  3. 03

    执行 wait=true 的推送,返回真实消息对象后再记录成功;默认 wait=false 常返回 204。

调用 01

执行 Incoming Webhook

显式使用 wait=true 取得服务端确认及消息对象。

POSThttps://discord.com/api/v10/webhooks/${DISCORD_WEBHOOK_ID}/${DISCORD_WEBHOOK_TOKEN}?wait=true

请求头

Content-Type
application/json

参数说明

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

字段 / 位置类型 / 必填说明
webhook_id / webhook_tokenPathstring必填复制自 Webhook URL;不用 Authorization。
waitQueryboolean可选默认 false;本例 true,等待服务端确认并返回消息。
content请求体string必填本例文本通知,最多 2000 字符;使用其他消息类型时可省略但至少提供一种内容。
allowed_mentions请求体object可选parse=[] 禁止自动触发 @everyone/角色/用户提醒,适合系统通知。

调用代码

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

cURL
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
Python 3
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
// 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 外层。 以下为结构示意,非本站实测结果。

JSON
{
  "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 失效。

核验来源

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

  1. 01
    Webhook Resource核验日期 2026-10-15
  2. 02
    Rate Limits核验日期 2026-10-15

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

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