Serve 動作

執行 discli serve 時，會將 JSON 物件（每行一筆）送入 stdin。每個動作都必須包含 "action" 欄位。回傳中可選的 "req_id" 欄位會回拋，以用於關聯。

一般請求格式：

{"action": "<action_name>", "req_id": "optional-correlation-id", ...fields}

一般回應格式：

{"event": "response", "status": "ok", "req_id": "1", ...result_fields}

發生錯誤時，回應會改為使用 "error" 欄位，而非 "ok"：

{"event": "response", "error": "Channel not found: 999", "req_id": "1"}

訊息操作

send

發送訊息到一個頻道。

請求：

{"action": "send", "channel_id": "123456", "content": "Hello!", "req_id": "1"}

回應：

{"event": "response", "ok": true, "message_id": "789", "req_id": "1"}

欄位	必填	型別	說明
`channel_id`	是	字串	目標頻道 ID
`content`	否	字串	訊息文字
`embed`	否	物件	嵌入物件
`components`	否	陣列	訊息元件 (參見 send / reply 的元件)
`files`	否	字串陣列	本機附加檔案路徑
`req_id`	否	字串	關聯識別碼

reply

回覆指定訊息。

請求：

{"action": "reply", "channel_id": "123456", "message_id": "111", "content": "Got it!", "req_id": "2"}

回應：

{"event": "response", "ok": true, "message_id": "222", "req_id": "2"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要回覆的訊息
`content`	否	字串	回覆文字
`embed`	否	物件	嵌入物件
`components`	否	陣列	訊息元件 (參見 send / reply 的元件)
`files`	否	字串陣列	本機附加檔案路徑
`req_id`	否	字串	關聯識別碼

edit

編輯現有訊息（必須由機器人建立）。

請求：

{"action": "edit", "channel_id": "123456", "message_id": "789", "content": "Updated text", "req_id": "3"}

回應：

{"event": "response", "ok": true, "req_id": "3"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要編輯的訊息
`content`	否	字串	更新後訊息內容
`req_id`	否	字串	關聯識別碼

delete

刪除一則訊息。

請求：

{"action": "delete", "channel_id": "123456", "message_id": "789", "req_id": "4"}

回應：

{"event": "response", "ok": true, "req_id": "4"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要刪除的訊息
`req_id`	否	字串	關聯識別碼

message_pin

將訊息釘選到頻道。

請求：

{"action": "message_pin", "channel_id": "123456", "message_id": "789", "req_id": "5"}

回應：

{"event": "response", "ok": true, "req_id": "5"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要釘選的訊息
`req_id`	否	字串	關聯識別碼

message_unpin

取消釘選頻道中的訊息。

請求：

{"action": "message_unpin", "channel_id": "123456", "message_id": "789", "req_id": "6"}

回應：

{"event": "response", "ok": true, "req_id": "6"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要取消釘選的訊息
`req_id`	否	字串	關聯識別碼

message_bulk_delete

一次刪除多則訊息。

請求：

{"action": "message_bulk_delete", "channel_id": "123456", "message_ids": ["789", "790"], "req_id": "7"}

回應：

{"event": "response", "ok": true, "req_id": "7"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_ids`	是	字串陣列	要刪除的訊息 ID
`req_id`	否	字串	關聯識別碼

send / reply 的 embed

send 與 reply 的 embed 欄位可接受如下結構物件：

{
  "action": "send",
  "channel_id": "123456",
  "content": "Check this out",
  "embed": {
    "title": "My Embed",
    "description": "A description",
    "color": "5865F2",
    "footer": "Footer text",
    "image": "https://example.com/image.png",
    "thumbnail": "https://example.com/thumb.png",
    "author": {"name": "Author Name", "icon_url": "https://example.com/icon.png"},
    "fields": [{"name": "Field", "value": "Value", "inline": true}]
  }
}

欄位	必填	型別	說明
`title`	否	字串	嵌入標題
`description`	否	字串	嵌入描述
`color`	否	字串	色碼（例如 `5865F2`）
`footer`	否	字串	頁尾文字
`image`	否	字串	圖片網址
`thumbnail`	否	字串	縮圖網址
`author`	否	物件	作者，含 `name` 與可選的 `icon_url`
`fields`	否	陣列	`{"name", "value", "inline"}` 物件清單

send / reply 的元件

send 與 reply 的 components 欄位可接受操作列陣列。每一列是元件物件陣列。

{
  "action": "send",
  "channel_id": "123456",
  "content": "Pick an option",
  "components": [
    [{"type": "button", "label": "OK", "style": "primary", "custom_id": "ok"}],
    [{"type": "select", "custom_id": "pick", "placeholder": "Choose...", "options": [{"label": "A", "value": "a"}]}],
    [{"type": "user_select", "custom_id": "user", "placeholder": "Pick user..."}],
    [{"type": "role_select", "custom_id": "role", "placeholder": "Pick role..."}],
    [{"type": "channel_select", "custom_id": "ch", "placeholder": "Pick channel..."}]
  ]
}

支援的元件類型：

類型	欄位	說明
`button`	`label`, `style`, `custom_id`	按鈕。樣式： `primary`, `secondary`, `success`, `danger`
`select`	`custom_id`, `placeholder`, `options`	字串下拉式選單。選項： `[{"label", "value"}]`
`user_select`	`custom_id`, `placeholder`	使用者下拉選單
`role_select`	`custom_id`, `placeholder`	身分組下拉選單
`channel_select`	`custom_id`, `placeholder`	頻道下拉選單

串流

串流可發送可即時更新的回應（例如 LLM 逐詞輸出）。流程為：stream_start 先建立佔位訊息、stream_chunk 逐段加上文字、stream_end 完成，串流期間每 1.5 秒會更新至 Discord。

stream_start

開始一則串流訊息。在頻道中先建立一則佔位訊息（"..."）。

請求：

{"action": "stream_start", "channel_id": "123456", "req_id": "10"}

回應：

{"event": "response", "stream_id": "a1b2c3d4", "message_id": "789", "req_id": "10"}

欄位	必填	型別	說明
`channel_id`	是	字串	發送目標頻道
`reply_to`	否	字串	回覆目標訊息 ID
`interaction_token`	否	字串	回覆 slash 指令的互動 token
`req_id`	否	字串	關聯識別碼

stream_chunk

為進行中的串流追加文字。內容會先快取並定期推送。

請求：

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "Hello ", "req_id": "11"}

回應：

{"event": "response", "ok": true, "req_id": "11"}

欄位	必填	型別	說明
`stream_id`	是	字串	`stream_start` 回傳的串流 ID
`content`	否	字串	要追加的文字
`req_id`	否	字串	關聯識別碼

stream_end

完成串流訊息。會用完整內容做最後一次編輯；若超過 2000 字元，會拆成後續訊息補送。

請求：

{"action": "stream_end", "stream_id": "a1b2c3d4", "req_id": "12"}

回應：

{"event": "response", "ok": true, "message_id": "789", "req_id": "12"}

欄位	必填	型別	說明
`stream_id`	是	字串	`stream_start` 回傳的串流 ID
`req_id`	否	字串	關聯識別碼

互動

interaction_followup

對延後處理的 slash 互動送出後續回應。

請求：

{"action": "interaction_followup", "interaction_token": "uuid-token", "content": "Done!", "req_id": "20"}

回應：

{"event": "response", "ok": true, "req_id": "20"}

欄位	必填	型別	說明
`interaction_token`	是	字串	來自 `slash_command` 事件的 token
`content`	否	字串	後續回應文字
`req_id`	否	字串	關聯識別碼

interaction_respond

立即回應一筆互動。未延後處理時，請改用此項目而非 interaction_followup。

請求：

{"action": "interaction_respond", "interaction_token": "uuid-token", "content": "Done!", "ephemeral": true, "req_id": "21"}

回應：

{"event": "response", "ok": true, "req_id": "21"}

欄位	必填	型別	說明
`interaction_token`	是	字串	來自互動事件的 token
`content`	否	字串	回應訊息文字
`embed`	否	物件	嵌入物件
`components`	否	陣列	訊息元件
`ephemeral`	否	布林	僅對觸發者可見（預設：false）
`req_id`	否	字串	關聯識別碼

interaction_edit

編輯原始互動回應訊息。

請求：

{"action": "interaction_edit", "interaction_token": "uuid-token", "content": "Updated!", "req_id": "22"}

回應：

{"event": "response", "ok": true, "req_id": "22"}

欄位	必填	型別	說明
`interaction_token`	是	字串	來自互動事件的 token
`content`	否	字串	更新後訊息內容
`embed`	否	物件	新的嵌入物件
`components`	否	陣列	新的訊息元件
`req_id`	否	字串	關聯識別碼

modal_send

回應互動並開啟 modal 表單。

請求：

{
  "action": "modal_send",
  "interaction_token": "uuid-token",
  "custom_id": "feedback-form",
  "title": "Feedback",
  "fields": [
    {"custom_id": "name", "label": "Name", "style": "short", "required": true},
    {"custom_id": "message", "label": "Message", "style": "long", "placeholder": "Your feedback..."}
  ],
  "req_id": "23"
}

回應：

{"event": "response", "ok": true, "req_id": "23"}

欄位	必填	型別	說明
`interaction_token`	是	字串	來自互動事件的 token
`custom_id`	是	字串	Modal 的唯一識別碼
`title`	是	字串	Modal 標題
`fields`	是	陣列	文字輸入欄位清單
`req_id`	否	字串	關聯識別碼

欄位物件：

欄位	必填	型別	說明
`custom_id`	是	字串	欄位的唯一識別碼
`label`	是	字串	欄位標籤
`style`	是	字串	`short`（單行）或 `long`（段落）
`required`	否	布林	欄位是否必填（預設：true）
`placeholder`	否	字串	預留位文字
`value`	否	字串	預填值

輸入提示與狀態

typing_start

在頻道中啟動輸入指示符號。會持續顯示，直到送出 typing_stop 或 bot 發送訊息為止。

請求：

{"action": "typing_start", "channel_id": "123456", "req_id": "30"}

回應：

{"event": "response", "ok": true, "req_id": "30"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`req_id`	否	字串	關聯識別碼

typing_stop

停止在頻道中顯示輸入指示符號。

請求：

{"action": "typing_stop", "channel_id": "123456", "req_id": "31"}

回應：

{"event": "response", "ok": true, "req_id": "31"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`req_id`	否	字串	關聯識別碼

presence

設定機器人的線上狀態與活動。

請求：

{"action": "presence", "status": "dnd", "activity_type": "watching", "activity_text": "the logs", "req_id": "32"}

回應：

{"event": "response", "ok": true, "req_id": "32"}

欄位	必填	型別	說明
`status`	否	字串	`online`、`idle`、`dnd` 或 `invisible`（預設：`online`）
`activity_type`	否	字串	`playing`、`watching`、`listening` 或 `competing`
`activity_text`	否	字串	顯示活動的文字
`req_id`	否	字串	關聯識別碼

反應

reaction_add

為訊息新增回應。

請求：

{"action": "reaction_add", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "req_id": "40"}

回應：

{"event": "response", "ok": true, "req_id": "40"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要反應的訊息
`emoji`	是	字串	Emoji 字元或自訂 emoji 字串
`req_id`	否	字串	關聯識別碼

reaction_remove

移除機器人對訊息的反應。

請求：

{"action": "reaction_remove", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "req_id": "41"}

回應：

{"event": "response", "ok": true, "req_id": "41"}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	要移除反應的訊息
`emoji`	是	字串	Emoji 字元或自訂 emoji 字串
`req_id`	否	字串	關聯識別碼

reaction_users

列出使用指定 emoji 反應的使用者。

請求：

{"action": "reaction_users", "channel_id": "123456", "message_id": "789", "emoji": "thumbsup", "limit": 100, "req_id": "42"}

回應：

{
  "event": "response",
  "ok": true,
  "users": [
    {"id": "111", "name": "alice"}
  ],
  "req_id": "42"
}

欄位	必填	型別	說明
`channel_id`	是	字串	訊息所在頻道
`message_id`	是	字串	訊息 ID
`emoji`	是	字串	Emoji 字元或自訂 emoji 字串
`limit`	否	整數	回傳的最大使用者數（預設：100）
`req_id`	否	字串	關聯識別碼

討論串

thread_create

建立新討論串，可選擇從既有訊息建立。

請求：

{"action": "thread_create", "channel_id": "123456", "name": "Discussion", "message_id": "789", "req_id": "50"}

回應：

{"event": "response", "ok": true, "thread_id": "999", "thread_name": "Discussion", "req_id": "50"}

欄位	必填	型別	說明
`channel_id`	是	字串	上層頻道 ID
`name`	是	字串	討論串名稱
`message_id`	否	字串	建立討論串的訊息來源 (單獨討論串可省略此欄位)
`auto_archive_duration`	否	整數	N 分鐘後自動封存（預設：1440）
`content`	否	字串	討論串初始訊息
`req_id`	否	字串	關聯識別碼

thread_send

向現有討論串發送訊息。

請求：

{"action": "thread_send", "thread_id": "999", "content": "Hello thread!", "req_id": "51"}

回應：

{"event": "response", "ok": true, "message_id": "1000", "req_id": "51"}

欄位	必填	型別	說明
`thread_id`	是	字串	討論串 ID
`content`	否	字串	訊息文字
`files`	否	字串陣列	本機附加檔案路徑
`req_id`	否	字串	關聯識別碼

thread_list

列出頻道中的進行中討論串。

請求：

{"action": "thread_list", "channel_id": "123456", "req_id": "52"}

回應：

{
  "event": "response",
  "ok": true,
  "threads": [
    {"id": "999", "name": "Discussion", "message_count": 5, "member_count": 3, "archived": false}
  ],
  "req_id": "52"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`req_id`	否	字串	關聯識別碼

thread_archive

封存討論串。

請求：

{"action": "thread_archive", "thread_id": "999", "req_id": "53"}

回應：

{"event": "response", "ok": true, "req_id": "53"}

欄位	必填	型別	說明
`thread_id`	是	字串	討論串 ID
`req_id`	否	字串	關聯識別碼

thread_rename

重新命名討論串。

請求：

{"action": "thread_rename", "thread_id": "999", "name": "New Name", "req_id": "54"}

回應：

{"event": "response", "ok": true, "req_id": "54"}

欄位	必填	型別	說明
`thread_id`	是	字串	討論串 ID
`name`	是	字串	新討論串名稱
`req_id`	否	字串	關聯識別碼

thread_add_member

新增成員至討論串。

請求：

{"action": "thread_add_member", "thread_id": "999", "member_id": "111", "req_id": "55"}

回應：

{"event": "response", "ok": true, "req_id": "55"}

欄位	必填	型別	說明
`thread_id`	是	字串	討論串 ID
`member_id`	是	字串	成員使用者 ID
`req_id`	否	字串	關聯識別碼

thread_remove_member

從討論串移除成員。

請求：

{"action": "thread_remove_member", "thread_id": "999", "member_id": "111", "req_id": "56"}

回應：

{"event": "response", "ok": true, "req_id": "56"}

欄位	必填	型別	說明
`thread_id`	是	字串	討論串 ID
`member_id`	是	字串	成員使用者 ID
`req_id`	否	字串	關聯識別碼

投票

poll_send

在頻道中建立投票。

請求：

{
  "action": "poll_send",
  "channel_id": "123456",
  "question": "Favorite AI?",
  "answers": ["Claude", "Gemini", "ChatGPT"],
  "duration_hours": 24,
  "multiple": false,
  "req_id": "60"
}

答案也可使用 emoji 物件形式：

{
  "action": "poll_send",
  "channel_id": "123456",
  "question": "Vote!",
  "answers": [{"text": "Yes", "emoji": "white_check_mark"}, {"text": "No", "emoji": "x"}],
  "req_id": "61"
}

回應：

{"event": "response", "ok": true, "message_id": "789", "req_id": "60"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`question`	是	字串	投票問題
`answers`	是	陣列	答案字串陣列，或 `{"text": "...", "emoji": "..."}` 物件陣列（至少 2 個）
`duration_hours`	否	整數	持續時間（小時，預設：24）
`multiple`	否	布林	允許多選（預設：false）
`content`	否	字串	投票附帶的選填訊息文字
`req_id`	否	字串	關聯識別碼

poll_results

檢視投票結果。

請求：

{"action": "poll_results", "channel_id": "123456", "message_id": "789", "req_id": "62"}

回應：

{
  "event": "response",
  "ok": true,
  "question": "Favorite AI?",
  "answers": [
    {"text": "Claude", "votes": 10},
    {"text": "Gemini", "votes": 5},
    {"text": "ChatGPT", "votes": 3}
  ],
  "req_id": "62"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`message_id`	是	字串	投票訊息 ID
`req_id`	否	字串	關聯識別碼

poll_end

提早結束投票。

請求：

{"action": "poll_end", "channel_id": "123456", "message_id": "789", "req_id": "63"}

回應：

{"event": "response", "ok": true, "req_id": "63"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`message_id`	是	字串	投票訊息 ID
`req_id`	否	字串	關聯識別碼

頻道

channel_list

列出全部伺服器或指定伺服器中的頻道。

請求：

{"action": "channel_list", "guild_id": "123456", "req_id": "70"}

回應：

{
  "event": "response",
  "ok": true,
  "channels": [
    {"id": "111", "name": "general", "type": "text", "server": "My Server", "server_id": "123456"}
  ],
  "req_id": "70"
}

欄位	必填	型別	說明
`guild_id`	否	字串	伺服器 ID（不填則列全部）
`req_id`	否	字串	關聯識別碼

channel_create

在伺服器中建立頻道。

請求：

{"action": "channel_create", "guild_id": "123456", "name": "new-channel", "type": "text", "req_id": "71"}

回應：

{"event": "response", "ok": true, "channel_id": "222", "name": "new-channel", "req_id": "71"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`name`	是	字串	頻道名稱
`type`	否	字串	`text`、`voice`、`category` 或 `forum`（預設：`text`）
`req_id`	否	字串	關聯識別碼

channel_info

取得頻道的詳細資訊。

請求：

{"action": "channel_info", "channel_id": "123456", "req_id": "72"}

回應：

{
  "event": "response",
  "ok": true,
  "id": "123456",
  "name": "general",
  "type": "text",
  "server": "My Server",
  "server_id": "789",
  "topic": "General discussion",
  "created_at": "2024-01-01T00:00:00+00:00",
  "req_id": "72"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`req_id`	否	字串	關聯識別碼

channel_edit

編輯頻道設定。

請求：

{"action": "channel_edit", "channel_id": "123456", "name": "new-name", "topic": "New topic", "slowmode": 5, "nsfw": false, "req_id": "73"}

回應：

{"event": "response", "ok": true, "req_id": "73"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`name`	否	字串	新頻道名稱
`topic`	否	字串	新頻道主題
`slowmode`	否	整數	慢速模式秒數（0 表示停用）
`nsfw`	否	布林	NSFW 設定
`req_id`	否	字串	關聯識別碼

channel_set_permissions

設定頻道權限覆寫。

請求：

{"action": "channel_set_permissions", "channel_id": "123456", "target_id": "222", "target_type": "role", "allow": "send_messages,read_messages", "deny": "manage_messages", "req_id": "74"}

回應：

{"event": "response", "ok": true, "req_id": "74"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`target_id`	是	字串	身分組或成員 ID
`target_type`	否	字串	`role` 或 `member` (default: `role`)
`allow`	否	字串	允許的權限（逗號分隔）
`deny`	否	字串	拒絕的權限（逗號分隔）
`req_id`	否	字串	關聯識別碼

forum_post

在論壇頻道建立討論串。

請求：

{"action": "forum_post", "channel_id": "123456", "title": "My Post", "content": "Post body", "req_id": "75"}

回應：

{"event": "response", "ok": true, "thread_id": "999", "req_id": "75"}

欄位	必填	型別	說明
`channel_id`	是	字串	論壇頻道 ID
`title`	是	字串	貼文標題
`content`	是	字串	貼文本文
`files`	否	字串陣列	本機附加檔案路徑
`req_id`	否	字串	關聯識別碼

成員

member_list

列出伺服器成員。

請求：

{"action": "member_list", "guild_id": "123456", "limit": 50, "req_id": "80"}

回應：

{
  "event": "response",
  "ok": true,
  "members": [
    {"id": "111", "name": "alice", "nick": null, "bot": false}
  ],
  "req_id": "80"
}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`limit`	否	整數	回傳成員數上限（預設：50）
`req_id`	否	字串	關聯識別碼

member_info

取得指定成員的詳細資訊。

請求：

{"action": "member_info", "guild_id": "123456", "member_id": "111", "req_id": "81"}

回應：

{
  "event": "response",
  "ok": true,
  "id": "111",
  "name": "alice",
  "nick": null,
  "bot": false,
  "roles": [{"id": "222", "name": "Admin"}],
  "joined_at": "2024-01-01T00:00:00+00:00",
  "req_id": "81"
}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`member_id`	是	字串	成員使用者 ID
`req_id`	否	字串	關聯識別碼

member_timeout

對成員進行超時處理，阻止其發言或加入語音頻道。

請求：

{"action": "member_timeout", "guild_id": "123456", "member_id": "111", "duration": 300, "reason": "Spamming", "req_id": "82"}

回應：

{"event": "response", "ok": true, "req_id": "82"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`member_id`	是	字串	成員使用者 ID
`duration`	是	整數	超時秒數（0 表示取消超時）
`reason`	否	字串	超時原因
`req_id`	否	字串	關聯識別碼

身分組

role_list

列出伺服器身分組。

請求：

{"action": "role_list", "guild_id": "123456", "req_id": "90"}

回應：

{
  "event": "response",
  "ok": true,
  "roles": [
    {"id": "222", "name": "Admin", "color": "#ff0000", "members": 3}
  ],
  "req_id": "90"
}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`req_id`	否	字串	關聯識別碼

role_assign

將身分組指派給成員。

請求：

{"action": "role_assign", "guild_id": "123456", "member_id": "111", "role_id": "222", "req_id": "91"}

回應：

{"event": "response", "ok": true, "member": "alice", "role": "Admin", "req_id": "91"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`member_id`	是	字串	成員使用者 ID
`role_id`	是	字串	要指派的身分組 ID
`req_id`	否	字串	關聯識別碼

role_remove

移除成員的身分組。

請求：

{"action": "role_remove", "guild_id": "123456", "member_id": "111", "role_id": "222", "req_id": "92"}

回應：

{"event": "response", "ok": true, "member": "alice", "role": "Admin", "req_id": "92"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`member_id`	是	字串	成員使用者 ID
`role_id`	是	字串	要移除的身分組 ID
`req_id`	否	字串	關聯識別碼

role_edit

編輯身分組設定。

請求：

{"action": "role_edit", "guild_id": "123456", "role_id": "222", "name": "Moderator", "color": "00ff00", "hoist": true, "mentionable": false, "req_id": "93"}

回應：

{"event": "response", "ok": true, "req_id": "93"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`role_id`	是	字串	角色 ID
`name`	否	字串	新身分組名稱
`color`	否	字串	十六進位顏色（例如 `00ff00`）
`hoist`	否	布林	在側邊欄中分開顯示身分組
`mentionable`	否	布林	身分組是否可被 @ 提及
`req_id`	否	字串	關聯識別碼

DMs

dm_send

傳送私人訊息給使用者。

請求：

{"action": "dm_send", "user_id": "111", "content": "Hello!", "req_id": "100"}

回應：

{"event": "response", "ok": true, "message_id": "222", "recipient": "alice", "req_id": "100"}

欄位	必填	型別	說明
`user_id`	是	字串	收件人使用者 ID
`content`	否	字串	訊息文字
`req_id`	否	字串	關聯識別碼

查詢

message_list

列出頻道中的近期訊息。

請求：

{"action": "message_list", "channel_id": "123456", "limit": 20, "req_id": "110"}

回應：

{
  "event": "response",
  "ok": true,
  "messages": [
    {
      "id": "789",
      "author": "alice",
      "author_id": "111",
      "content": "Hello!",
      "timestamp": "2024-01-01T12:00:00+00:00",
      "attachments": []
    }
  ],
  "req_id": "110"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`limit`	否	整數	最大訊息數（預設：20）
`req_id`	否	字串	關聯識別碼

message_get

依 ID 取得單則訊息。

請求：

{"action": "message_get", "channel_id": "123456", "message_id": "789", "req_id": "111"}

回應：

{
  "event": "response",
  "ok": true,
  "id": "789",
  "author": "alice",
  "author_id": "111",
  "content": "Hello!",
  "timestamp": "2024-01-01T12:00:00+00:00",
  "attachments": [],
  "embeds": [],
  "reply_to": null,
  "req_id": "111"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`message_id`	是	字串	訊息 ID
`req_id`	否	字串	關聯識別碼

message_search

依內容搜尋頻道訊息。

請求：

{"action": "message_search", "channel_id": "123456", "query": "hello", "limit": 100, "author": "alice", "req_id": "112"}

回應：

{
  "event": "response",
  "ok": true,
  "messages": [
    {"id": "789", "author": "alice", "content": "Hello world!", "timestamp": "2024-01-01T12:00:00+00:00"}
  ],
  "req_id": "112"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`query`	否	字串	不分大小寫的搜尋字串
`limit`	否	整數	要掃描的訊息數（預設：100）
`author`	否	字串	依作者名稱過濾
`req_id`	否	字串	關聯識別碼

伺服器

server_list

列出 bot 所在的所有伺服器。

請求：

{"action": "server_list", "req_id": "120"}

回應：

{
  "event": "response",
  "ok": true,
  "servers": [
    {"id": "123456", "name": "My Server", "member_count": 42}
  ],
  "req_id": "120"
}

欄位	必填	型別	說明
`req_id`	否	字串	關聯識別碼

server_info

取得指定伺服器的詳細資訊。

請求：

{"action": "server_info", "guild_id": "123456", "req_id": "121"}

回應：

{
  "event": "response",
  "ok": true,
  "id": "123456",
  "name": "My Server",
  "owner": "alice",
  "member_count": 42,
  "channel_count": 10,
  "role_count": 5,
  "created_at": "2024-01-01T00:00:00+00:00",
  "req_id": "121"
}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`req_id`	否	字串	關聯識別碼

Webhooks

webhook_list

列出指定頻道的 webhook。

請求：

{"action": "webhook_list", "channel_id": "123456", "req_id": "130"}

回應：

{
  "event": "response",
  "ok": true,
  "webhooks": [
    {"id": "555", "name": "My Hook", "channel_id": "123456"}
  ],
  "req_id": "130"
}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`req_id`	否	字串	關聯識別碼

webhook_create

建立指定頻道的 webhook。

請求：

{"action": "webhook_create", "channel_id": "123456", "name": "My Hook", "req_id": "131"}

回應：

{"event": "response", "ok": true, "webhook_id": "555", "name": "My Hook", "req_id": "131"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`name`	是	字串	Webhook 名稱
`req_id`	否	字串	關聯識別碼

webhook_delete

刪除 webhook。

請求：

{"action": "webhook_delete", "channel_id": "123456", "webhook_id": "555", "req_id": "132"}

回應：

{"event": "response", "ok": true, "req_id": "132"}

欄位	必填	型別	說明
`channel_id`	是	字串	頻道 ID
`webhook_id`	是	字串	Webhook ID
`req_id`	否	字串	關聯識別碼

事件

event_list

列出伺服器的排程活動。

請求：

{"action": "event_list", "guild_id": "123456", "req_id": "140"}

回應：

{
  "event": "response",
  "ok": true,
  "events": [
    {"id": "777", "name": "Game Night", "start_time": "2026-04-01T20:00:00+00:00", "status": "scheduled"}
  ],
  "req_id": "140"
}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`req_id`	否	字串	關聯識別碼

event_create

建立排程活動。

請求：

{
  "action": "event_create",
  "guild_id": "123456",
  "name": "Game Night",
  "start_time": "2026-04-01T20:00:00+00:00",
  "end_time": "2026-04-01T23:00:00+00:00",
  "description": "Weekly game night!",
  "channel_id": "789",
  "req_id": "141"
}

回應：

{"event": "response", "ok": true, "event_id": "777", "req_id": "141"}

欄位	必填	型別	說明
`guild_id`	是	字串	伺服器 ID
`name`	是	字串	活動名稱
`start_time`	是	字串	開始時間（ISO 8601）
`end_time`	否	字串	結束時間（ISO 8601）
`description`	否	字串	活動描述
`channel_id`	否	字串	語音/舞台頻道 ID
`location`	否	字串	外部地點
`req_id`	否	字串	關聯識別碼

語音

所有語音相關動作都需要 voice 可選功能。大多數可用 channel_id 或 guild_id 進行路由；若只提供 channel_id，會自動解析該語音頻道所屬伺服器。前台使用流程請參考語音指南。

voice_connect

加入伺服器語音頻道。

{"action": "voice_connect", "channel_id": "1016638171854938152", "req_id": "1"}

欄位	必填	型別	說明
`channel_id`	是	字串	語音頻道 ID
`req_id`	否	字串	關聯識別碼

voice_disconnect

離開目前語音頻道。

{"action": "voice_disconnect", "guild_id": "767327865100304394"}

voice_move

將機器人移動到同一伺服器的其他語音頻道。

{"action": "voice_move", "channel_id": "1016638171854938152"}

voice_speak

透過 TTS 合成文字並播放。

{"action": "voice_speak", "channel_id": "1016638171854938152", "text": "joining the call now", "voice": "alloy", "speed": 1.0, "tts": "openai"}

欄位	必填	型別	說明
`channel_id` 或 `guild_id`	是	字串	語音頻道 ID 或伺服器 ID
`text`	是	字串	要合成的文字
`voice`	否	字串	TTS 聲音 ID（依提供者而定）
`speed`	否	數字	語速倍率 (預設 `1.0`)
`tts`	否	字串	覆寫 TTS 提供者（`elevenlabs`、`openai`、`deepgram`）

voice_play

透過 ffmpeg 播放音訊檔案或網址。

{"action": "voice_play", "channel_id": "1016638171854938152", "source": "https://example.com/intro.mp3"}

欄位	必填	型別	說明
`channel_id` 或 `guild_id`	是	字串	語音頻道 ID 或伺服器 ID
`source`	是	字串	檔案路徑或 HTTP(S) 網址

voice_stop / voice_pause / voice_resume

控制目前播放行為。

{"action": "voice_stop", "guild_id": "767327865100304394"}
{"action": "voice_pause", "guild_id": "767327865100304394"}
{"action": "voice_resume", "guild_id": "767327865100304394"}

voice_listen_start

開始將輸入音訊串流至 STT，並輸出 voice_speech_detected 事件。

{"action": "voice_listen_start", "channel_id": "1016638171854938152", "stt": "deepgram"}

欄位	必填	型別	說明
`channel_id` 或 `guild_id`	是	字串	語音頻道 ID 或伺服器 ID
`stt`	否	字串	覆寫 STT 提供者（`deepgram`、`openai`）

voice_listen_stop

停止此伺服器的語音監聽。

{"action": "voice_listen_stop", "guild_id": "767327865100304394"}

voice_status

列出目前啟用的語音連線。

{"action": "voice_status"}

回應：

{"event": "response", "ok": true, "connections": [{"guild_id": 767327865100304394, "channel_id": 1016638171854938152, "is_playing": false, "is_listening": true}]}

voice_set_config

更新語音引擎設定（供應者預設值、VAD 閥值、播放音量），無需重連。

{"action": "voice_set_config", "config": {"tts_provider": "openai", "playback_volume": 0.7}}

Last updated: August 2, 2026

6 min read

Edit this page