# Telegram API

`github.com/pardnchiu/go-bot/core/telegram` 的全部 exported 符號，底層為 `github.com/go-telegram/bot` v1.20.0。

## 型別

| 符號 | 定義 | 說明 |
|---|---|---|
| `Bot` | `struct`（欄位未匯出） | 以 `New` 建立；方法可並行呼叫 |
| `Status` | `struct { Running bool; Username string; UserID int64 }` | `Status()` 的回傳值 |
| `Input` | `struct` | 欄位：`ChatID int64`、`ChatName string`、`MessageID int`、`UserID int64`、`Username string`、`Text string`、`Caption string`、`Photo []models.PhotoSize`、`Document *models.Document`、`CallbackData string`、`CallbackPicks []string`、`Raw *models.Update`。見 [Telegram 設定](/zh/telegram#input) |
| `ReplyHandler` | `func(ctx context.Context, input Input) string` | |
| `ChatStatus` | `struct`（欄位未匯出） | `SendStatus` 管理的每個 chat 狀態項目；呼叫端不需建立 |
| `Option` | `func(*options)` | `New` 的選項 |
| `MessageOption` | `func(*messageOptions)` | `Send`、`SendInput`、`SendSelect`、`SendMultiSelect` 的選項 |
| `StatusOption` | `func(*statusOptions)` | `SendStatus` 的選項 |
| `SendType` | `int` | 常數 `TypeMarkdown`（MarkdownV2）、`TypeHTML` |
| `FileType` | `int` | 常數 `TypeDocument`、`TypeVideo`、`TypeAudio` |

## 建構子與選項

| 函式 | 效果 |
|---|---|
| `New(token string, opts ...Option) (*Bot, error)` | `token` 為空或 SDK 的 `getMe` 檢查失敗（5 秒逾時）時回 error |
| `WithHTTPClient(client *http.Client) Option` | polling 與上傳使用的 HTTP client |
| `WithPollTimeout(d time.Duration) Option` | `getUpdates` 的 long-poll timeout |
| `WithSendType(t SendType) MessageOption` | 訊息文字的 parse mode |
| `WithStatusEmoji(emoji string) StatusOption` | reaction emoji；預設 `🤔` |
| `WithStatusSendType(t SendType) StatusOption` | status 文字的 parse mode |

## 方法

| 方法 | 回傳 | 錯誤與限制 |
|---|---|---|
| `Start(ctx context.Context)` | `error` | `GetMe` 失敗 |
| `Close()` | `error` | 一律 `nil` |
| `Status()` | `Status` | |
| `Reply(handler ReplyHandler)` | — | 取代先前的 handler |
| `Send(ctx, chatID int64, replyTo int, text string, opts ...MessageOption)` | `(*models.Message, error)` | API 錯誤 |
| `Delete(ctx, chatID int64, msgID int)` | `error` | API 錯誤 |
| `SendFile(ctx, chatID int64, fileType FileType, path string, caption ...string)` | `(*models.Message, error)` | 空路徑、`os.Open` 失敗、未知的 `FileType` |
| `SendPhoto(ctx, chatID int64, paths []string, caption ...string)` | `([]*models.Message, error)` | 非空路徑為 0 個或超過 10 個 |
| `SendVoice(ctx, chatID int64, path string, caption ...string)` | `(*models.Message, error)` | 空路徑、`os.Open` 失敗 |
| `SendInput(ctx, chatID int64, replyTo int, text string, opts ...MessageOption)` | `(*models.Message, error)` | 空文字 |
| `SendSelect(ctx, chatID int64, replyTo int, text string, items []string, opts ...MessageOption)` | `(*models.Message, error)` | 空文字、沒有非空項目 |
| `SendMultiSelect(ctx, chatID int64, replyTo int, text string, items []string, opts ...MessageOption)` | `(*models.Message, error)` | 空文字、沒有非空項目、保留項目 `__bot_multiselect_done__` |
| `SendStatus(ctx, chatID int64, replyTo int, text string, opts ...StatusOption)` | `error` | 立即 flush 時的送出／編輯錯誤 |
| `FinishStatus(ctx, chatID int64)` | `error` | 刪除錯誤，或等待進行中編輯時的 `ctx.Err()` |
| `Save(ctx, fileID, dir string)` | `(string, error)` | 空參數、超過 20 MiB、HTTP 非 200、檔案系統錯誤 |

## 相關頁面

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