Discord Gateway / Interactions 对话

Discord 对话有两条主路径：Gateway 的 MESSAGE_CREATE 适合连续频道聊天，Interactions 适合 Slash Command 和结构化交互。本文依据 Discord 官方开发文档整理，核验日期为 2026-09-08；未连接真实服务器。

能力边界

普通频道 Webhook 不能接收消息；双向对话需要 Bot Gateway 或 Interactions Endpoint。
Gateway 是有状态 WebSocket，需要心跳、断线恢复、Intent 和会话管理，生产中应优先使用成熟 SDK。
Slash Command 可不读取任意频道消息，隐私和权限边界更清晰，适合 AI 问答的默认入口。
读取非特定条件下的消息内容可能需要启用 MESSAGE CONTENT privileged intent；达到官方验证门槛的 App 还需审批。

准备条件

能在 Discord Developer Portal 创建 Application 和 Bot。
有权将 App 安装到测试服务器，并配置最小频道权限。
Gateway 路径准备可靠常驻进程；Interactions 路径准备公网 HTTPS Endpoint。
保存 Bot Token；Interactions HTTP 验签另需 Application Public Key。

配置步骤

在 Developer Portal 创建 Application，在 Bot 页面创建 Bot 并安全保存 Token。
在 Installation/OAuth2 配置 bot 和/或 applications.commands，只选查看频道、发送消息等必要权限。
Gateway 路径在 Bot 设置中按需启用 Message Content Intent，并订阅 GUILDS、GUILD_MESSAGES 等必要 Intent。
Interactions 路径注册 Slash Command，配置 Interactions Endpoint URL；端点必须通过 Discord 的签名验证。
把 App 安装到测试服务器，先用 /ping 或显式提及完成最小验证。

接收消息

Gateway 在 MESSAGE_CREATE 中给出消息 id、channel_id、guild_id、author、content 和引用信息。用消息 ID 做事件去重，忽略 author.bot === true，否则很容易形成回复循环。

Interactions HTTP 请求使用 X-Signature-Ed25519、X-Signature-Timestamp、原始请求体和 Application Public Key 验签。收到 PING 时返回 PONG；命令处理必须在官方规定的 3 秒窗口内初始响应或 defer。

会话键建议：频道聊天用 discord:{guild_id}:{channel_id}:{thread_id-or-channel}；Slash Command 可使用 guild_id + channel_id + user.id，是否共享群上下文应由产品规则明确决定。

最小频道回复验证

curl -X POST 'https://discord.com/api/v10/channels/CHANNEL_ID/messages' \
  -H 'Authorization: Bot DISCORD_BOT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content":"pong","message_reference":{"message_id":"MESSAGE_ID"}}'

const response = await fetch(`https://discord.com/api/v10/channels/${process.env.CHANNEL_ID}/messages`, {
  method: 'POST',
  headers: { Authorization: `Bot ${process.env.DISCORD_BOT_TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'pong', message_reference: { message_id: process.env.MESSAGE_ID } }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);

import os
import requests

response = requests.post(
    f"https://discord.com/api/v10/channels/{os.environ['CHANNEL_ID']}/messages",
    headers={"Authorization": f"Bot {os.environ['DISCORD_BOT_TOKEN']}"},
    json={"content": "pong", "message_reference": {"message_id": os.environ["MESSAGE_ID"]}},
    timeout=15,
)
response.raise_for_status()

普通 API 双向回复

Gateway 收到 /ping 或提及后，通过 Create Message 回复同一 channel_id。Interactions 则在初始响应中直接返回，或先返回 deferred response，再使用 Interaction Token 对应的 Webhook 编辑原响应/发送 follow-up。

interaction_token 有时效且属于敏感上下文，不应落入长期聊天记录。普通 Bot Token 不能替代 Interaction Webhook 的回复语义。

AI 对话扩展

const conversationKey = `discord:${message.guild_id}:${message.channel_id}`;
const answer = await generateReply({
  messages: await history.withUserMessage(conversationKey, message.content),
  signal: AbortSignal.timeout(20_000),
});
await createMessage(message.channel_id, { content: answer, message_reference: { message_id: message.id } });

AI 调用通常超过 Interaction 首次响应窗口，因此 Slash Command 路径应先 defer，再更新响应。长答案按 Discord 当前消息限制切分；工具执行结果要在服务端鉴权后再展示。

安全与可靠性

Gateway 使用成熟 SDK 管理 heartbeat、identify 限制、resume 和重连，不要手写不完整协议实现。
Interactions 必须用原始请求体验证 Ed25519 签名，并响应 Discord 的安全探测。
使用消息 ID 或 interaction ID 做事件去重；忽略所有 Bot 消息和自己的 Webhook 消息。
不授予 Administrator，结合服务器角色与频道覆盖权限做最小授权。
遵循响应中的 Rate Limit Headers 和 429 retry_after，不要硬编码统一速率。
对模型做提示词注入、越权工具、敏感内容和成本控制。

常见问题

能收到事件但 content 为空：检查 Message Content Intent、App 验证状态和该消息是否属于官方允许的例外场景。

Slash Command 显示“应用未响应”：必须在 3 秒内初始响应或 defer，模型调用放到后续处理。

Gateway 频繁断线：检查 heartbeat ACK、Intent、identify 速率和恢复逻辑，优先升级官方生态 SDK。

Missing Permissions：同时检查 Bot 角色与频道级覆盖权限，不要直接授予 Administrator。