Serve 事件

使用 discli serve 時，事件會以 JSONL（每行一個 JSON 物件）輸出到 stdout。每個事件都包含 event 欄位，用於識別事件類型。

ready

在機器人連線到 Discord gateway 時只會發送一次。這個事件會在 slash 指令同步前先觸發。

{
  "event": "ready",
  "bot_id": "123456789",
  "bot_name": "MyBot#1234"
}
欄位型別說明
bot_idstringBot 的使用者雪花 ID
bot_namestringBot 的使用者名稱與識別碼

slash_commands_synced

在 Discord 已註冊 slash 指令後會發送（僅當傳入 --slash-commands 時）。

{
  "event": "slash_commands_synced",
  "count": 3,
  "guilds": 2
}
欄位型別說明
countinteger已註冊的 slash 指令數
guildsinteger已同步指令的伺服器數量

message

在可見頻道中有訊息送出時發送。其它機器人的訊息會被排除；本機器人自己的訊息預設會包含（由 --include-self / --no-include-self 控制）。

{
  "event": "message",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "is_bot": false,
  "content": "Hello everyone!",
  "timestamp": "2024-01-15T12:30:00+00:00",
  "message_id": "333444",
  "mentions_bot": false,
  "is_dm": false,
  "attachments": [],
  "reply_to": null
}
欄位型別說明
serverstring | null伺服器名稱，DM 為 null
server_idstring | null伺服器雪花 ID，DM 為 null
channelstring頻道名稱，DM 為 "DM"
channel_idstring頻道雪花 ID
authorstring訊息作者名稱
author_idstring作者的使用者雪花 ID
is_botboolean是否為機器人
contentstring訊息文字內容
timestampstringISO 8601 時間戳
message_idstring訊息雪花 ID
mentions_botboolean是否 @ 提及本機器人
is_dmboolean是否為 DM
attachmentsarray{"filename", "url", "size"} 物件清單
reply_tostring | null回覆目標訊息 ID，或 null

slash_command

使用者觸發已註冊 slash 指令時會發送。互動會自動延遲回覆（顯示「thinking…」）。必須使用 interaction_followup 或 stream_start 搭配 interaction_token 回覆。

{
  "event": "slash_command",
  "command": "ask",
  "args": {"question": "What is discli?"},
  "channel_id": "789012",
  "user": "alice",
  "user_id": "111222",
  "guild_id": "123456",
  "interaction_token": "uuid-string",
  "is_admin": false
}
欄位型別說明
commandstringslash 指令名稱
argsobject指令參數的鍵值對（值皆為字串）
channel_idstring指令被觸發的頻道
userstring觸發者名稱
user_idstring觸發者使用者雪花 ID
guild_idstring | null伺服器 ID，DM slash 指令為 null
interaction_tokenstring用於透過 interaction_followup 或 stream_start 回覆的 token
is_adminboolean使用者是否具備該伺服器管理員權限

message_edit

非機器人使用者編輯訊息時會發送。

{
  "event": "message_edit",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "message_id": "333444",
  "old_content": "Hello",
  "new_content": "Hello everyone!",
  "timestamp": "2024-01-15T12:35:00+00:00"
}
欄位型別說明
serverstring | null伺服器名稱
server_idstring | null伺服器雪花 ID
channelstring頻道名稱
channel_idstring頻道雪花 ID
authorstring作者名稱
author_idstring作者使用者雪花 ID
message_idstring已編輯訊息的雪花 ID
old_contentstring | null編輯前內容（若未快取可能為 null）
new_contentstring編輯後內容
timestampstring編輯發生時間（ISO 8601）

message_delete

訊息被刪除時會發送。

{
  "event": "message_delete",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "message_id": "333444",
  "content": "Hello everyone!"
}
欄位型別說明
serverstring | null伺服器名稱
server_idstring | null伺服器雪花 ID
channelstring頻道名稱
channel_idstring頻道雪花 ID
authorstring | null作者名稱（未快取時為 null）
author_idstring | null作者使用者雪花 ID（未快取時為 null）
message_idstring被刪除訊息的雪花 ID
contentstring | null訊息內容（未快取時為 null）

reaction_add

使用者為訊息加上反應時會發送。

{
  "event": "reaction_add",
  "server": "My Server",
  "channel": "general",
  "channel_id": "789012",
  "message_id": "333444",
  "emoji": "thumbsup",
  "user": "alice",
  "user_id": "111222"
}
欄位型別說明
serverstring | null伺服器名稱
channelstring頻道名稱
channel_idstring頻道雪花 ID
message_idstring訊息雪花 ID
emojistringEmoji 名稱或 Unicode 字元
userstring反應使用者名稱
user_idstring反應使用者的使用者雪花 ID

reaction_remove

使用者移除訊息反應時會發送。

{
  "event": "reaction_remove",
  "channel": "general",
  "channel_id": "789012",
  "message_id": "333444",
  "emoji": "thumbsup",
  "user": "alice",
  "user_id": "111222"
}
欄位型別說明
serverstring | null伺服器名稱
channelstring頻道名稱
channel_idstring頻道雪花 ID
message_idstring訊息雪花 ID
emojistringEmoji 名稱或 Unicode 字元
userstring反應使用者名稱
user_idstring使用者雪花 ID

member_join

新成員加入伺服器時會發送。

{
  "event": "member_join",
  "server": "My Server",
  "server_id": "123456",
  "member": "alice",
  "member_id": "111222"
}
欄位型別說明
serverstring伺服器名稱
server_idstring伺服器雪花 ID
memberstring新成員名稱
member_idstring成員使用者雪花 ID

member_remove

成員離開或被移出伺服器時會發送。

{
  "event": "member_remove",
  "server": "My Server",
  "server_id": "123456",
  "member": "alice",
  "member_id": "111222"
}
欄位型別說明
serverstring伺服器名稱
server_idstring伺服器雪花 ID
memberstring成員名稱
member_idstring成員使用者雪花 ID

voice_state

當語音成員狀態變更時（加入、離開、頻道移動，或更新語音設定）會發送。

{
  "event": "voice_state",
  "action": "joined",
  "member": "alice",
  "channel": "General Voice",
  "channel_id": "789012"
}
欄位型別說明
actionstring可能為 joined、left、moved、updated 之一
memberstring成員名稱
channelstring語音頻道名稱
channel_idstring語音頻道雪花 ID

Voice 事件

Bot 連線、播放音訊、轉譯語音時，語音引擎會輸出這些事件。每則事件都包含標準的 event 欄位與 guild_id。

voice_connected

Bot 加入語音頻道後發送。

{"event": "voice_connected", "guild_id": "767327865100304394", "channel_id": "1016638171854938152"}

voice_disconnected

Bot 離開語音頻道後發送。

{"event": "voice_disconnected", "guild_id": "767327865100304394"}

voice_playback_started

TTS 或檔案播放開始時發送。

{"event": "voice_playback_started", "guild_id": "767327865100304394", "type": "tts"}
欄位型別說明
typestringtts 或 file
sourcestring來源 URL/路徑（file 類型）

voice_playback_finished

播放完成或被中止時發送。

{"event": "voice_playback_finished", "guild_id": "767327865100304394"}

voice_speech_detected

STT 回傳特定成員最終稿文字時發送。不會輸出未完成的中繼結果，僅輸出最終結果。

{
  "event": "voice_speech_detected",
  "guild_id": "767327865100304394",
  "channel_id": "1016638171854938152",
  "user_id": "743173584935190620",
  "text": "okay let's get started",
  "confidence": 0.94,
  "is_final": true
}
欄位型別說明
user_idstring發言者使用者雪花 ID
textstring最終稿文字
confidencenumber供應者回報的信心值（0.0 – 1.0）
is_finalbool此事件永遠為 true（中繼結果會被過濾）

component_interaction

使用者與訊息元件互動（按鈕點擊、下拉選單選擇）時發送。回覆可使用 interaction_respond、interaction_edit 或 modal_send，並傳入 interaction_token。

{
  "event": "component_interaction",
  "custom_id": "ok",
  "component_type": 2,
  "values": [],
  "user": "alice",
  "interaction_token": "uuid-string"
}
欄位型別說明
custom_idstring元件上設定的 custom_id
component_typeinteger元件類型（2 = 按鈕、3 = 下拉選單）
valuesarray已選值（按鈕為空陣列，下拉選單有值）
userstring互動者名稱
interaction_tokenstring回覆互動用 token

使用者提交 modal 時會發送。回覆可使用 interaction_respond 或 interaction_edit 搭配 interaction_token。

{
  "event": "modal_submit",
  "custom_id": "feedback-form",
  "fields": {"name": "Alice", "message": "Great bot!"},
  "user": "alice",
  "interaction_token": "uuid-string"
}
欄位型別說明
custom_idstringmodal 上設定的 custom_id
fieldsobject欄位 custom_id 與回傳值的鍵值對
userstring提交者名稱
interaction_tokenstring回覆互動提交用 token

disconnected

機器人與 Discord gateway 連線中斷時發送。

{"event": "disconnected"}

無額外欄位。

resumed

機器人斷線後成功重連到 Discord gateway 時發送。

{"event": "resumed"}

無額外欄位。

response

回覆 stdin 每筆指令皆使用此事件。若成功則包含 "ok": true，失敗則為 "error" 字串。若原始指令帶有 req_id，會回傳相同值。

{"event": "response", "ok": true, "message_id": "789", "req_id": "1"}
{"event": "response", "error": "Channel not found: 999", "req_id": "2"}
欄位型別說明
okboolean成功時存在且為 true
errorstring失敗時存在，內容為錯誤描述
req_idstring若有提供，回傳原始 req_id
(依動作而異)額外欄位會依 action 不同而變動，請參考 Serve 動作

error

當內部錯誤發生時發送，例如 stdin JSON 無效、slash 指令同步失敗。

{"event": "error", "message": "Invalid JSON: {bad input"}
欄位型別說明
messagestring錯誤描述

shutdown

當 Bot 程序進入關機流程時發送，例如 Ctrl+C。

{"event": "shutdown"}

無額外欄位。

事件篩選

可用 --events 選項限制輸出事件。傳入以逗號分隔的事件分類清單：

分類含蓋事件
messagesmessage
editsmessage_edit
deletesmessage_delete
reactionsreaction_add、reaction_remove
membersmember_join、member_remove
voicevoice_state、voice_connected、voice_disconnected、voice_playback_started、voice_playback_finished、voice_speech_detected

ready、slash_command、slash_commands_synced、component_interaction、modal_submit、response、error、disconnected、resumed、shutdown 事件不受此篩選影響，始終輸出。

範例：

discli serve --events messages,reactions
Last updated: August 2, 2026
2 min read
Edit this page