# Discord API

`github.com/pardnchiu/go-bot/core/discord` 的全部 exported 符號，底層為 `github.com/bwmarrin/discordgo` v0.29.0。

## 型別

| 符號 | 定義 | 說明 |
|---|---|---|
| `Bot` | `struct`（欄位未匯出） | 以 `New` 建立；方法可並行呼叫 |
| `Status` | `struct { Running bool; Username string; UserID string }` | `Status()` 的回傳值 |
| `Input` | `struct` | 欄位：`ChannelID`、`ChannelName`、`GuildID`、`MessageID`、`UserID`、`Username`、`Text`（皆為 `string`）、`Attachments []*discordgo.MessageAttachment`、`CallbackPicks []string`、`Raw *discordgo.MessageCreate`。見 [Discord 設定](/zh/discord#input) |
| `ReplyHandler` | `func(ctx context.Context, input Input) string` | |
| `ChannelStatus` | `struct`（欄位未匯出） | `SendStatus` 管理的每個 channel 狀態項目；呼叫端不需建立 |
| `StatusOption` | `func(*statusOptions)` | `SendStatus` 的選項 |

## 建構子與選項

| 函式 | 效果 |
|---|---|
| `New(token string) (*Bot, error)` | `token` 為空或被 discordgo 拒絕時回 error |
| `WithStatusEmoji(emoji string) StatusOption` | reaction emoji；預設 `🤔` |

## 方法

| 方法 | 回傳 | 錯誤與限制 |
|---|---|---|
| `Start(ctx context.Context)` | `error` | `User("@me")` 或 `Session.Open` 失敗 |
| `Close()` | `error` | `Session.Close` 失敗 |
| `Status()` | `Status` | |
| `Reply(handler ReplyHandler)` | — | 取代先前的 handler |
| `Send(ctx, channelID, replyTo, text string)` | `(*discordgo.Message, error)` | 空 channel ID、API 錯誤 |
| `Delete(ctx, channelID, messageID string)` | `error` | 空 ID、API 錯誤 |
| `SendFiles(ctx, channelID, replyTo string, paths []string, caption ...string)` | `(*discordgo.Message, error)` | 空 channel ID、路徑為 0 個或超過 10 個、空路徑、`os.Open` 失敗 |
| `SendVoice(ctx, channelID, replyTo, path string, caption ...string)` | `(*discordgo.Message, error)` | 空 channel ID 或路徑、`os.Open` 失敗 |
| `SendInput(ctx, channelID, replyTo, prompt string)` | `(*discordgo.Message, error)` | 空 channel ID 或 prompt、UUID 失敗 |
| `SendSelect(ctx, channelID, replyTo, text string, items []string)` | `(*discordgo.Message, error)` | 空 channel ID 或文字、非空項目為 0 個或超過 25 個、UUID 失敗 |
| `SendMultiSelect(ctx, channelID, replyTo, text string, items []string)` | `(*discordgo.Message, error)` | 同 `SendSelect` |
| `SendStatus(ctx, channelID, replyTo, text string, opts ...StatusOption)` | `error` | 立即 flush 時的送出／編輯錯誤 |
| `FinishStatus(ctx, channelID string)` | `error` | 刪除錯誤，或等待進行中編輯時的 `ctx.Err()` |
| `Save(ctx, att *discordgo.MessageAttachment, dir string)` | `(string, error)` | 附件為 nil、URL 或 dir 為空、超過 25 MiB、HTTP 非 200、檔案系統錯誤 |

## 相關頁面

[Discord 設定](/zh/discord) · [Discord 訊息](/zh/discord-messages) · [Discord 互動](/zh/discord-interactions) · [狀態訊息](/zh/status-messages) · [媒體落地](/zh/media-save)