# Telegram 設定

本頁說明如何建立 `core/telegram` bot、它的連線選項，以及 handler 收到的 `Input`。

## 建構子與選項

```go
bot, err := telegram.New(token,
    telegram.WithPollTimeout(50*time.Second),
    telegram.WithHTTPClient(&http.Client{Timeout: 70 * time.Second}),
)
```

token 為空時 `New` 回 `token is required`，SDK 錯誤包成 `Bot.New: ...`。SDK 建構時會以 5 秒逾時呼叫一次 `getMe`，因此無效 token 或連不上 Telegram API 會在這一步就回 `Bot.New: error call getMe, ...`。long polling 要到 `Start` 才開始。

| 選項 | 設定 | 兩個選項都沒傳時 |
|---|---|---|
| `WithPollTimeout(d time.Duration)` | 送給 `getUpdates` 的 long-poll `timeout` | 套用 SDK 預設 |
| `WithHTTPClient(c *http.Client)` | polling 與上傳共用的 client | 套用 SDK 預設 |

只傳其中一個時，另一個會被補上：poll timeout 預設 1 分鐘，client 預設 `&http.Client{Timeout: pollTimeout}`。

`client.Timeout` 應設得比 poll timeout 長。同一個 client 同時處理 long polling 與 multipart 上傳；client timeout 小於或等於 poll timeout 時，閒置的 poll 會在 Telegram 回應前被中止，表現為 `context deadline exceeded`。大檔上傳也需要這段餘裕。

## Start 與 webhook

`Start(ctx)` 先呼叫 `GetMe`（失敗即回 error），再呼叫 `GetWebhookInfo`。若 bot 已設定 webhook URL，會以 `DropPendingUpdates: false` 執行 `DeleteWebhook`，因為 webhook 存在時 Telegram 拒絕 long polling。這兩個呼叫失敗只記 log，不中斷 `Start`。

polling 迴圈的執行期錯誤會記 log。Telegram 回 HTTP 429 (too many requests) 並附 `retry_after` 時，錯誤處理器會先睡該秒數再繼續 polling。

## Input

| 欄位 | 型別 | 內容 |
|---|---|---|
| `ChatID` | `int64` | 事件來源 chat |
| `ChatName` | `string` | 群組／頻道的 `Title`，否則 `Username`，否則 `FirstName LastName`（私聊），都沒有則 `""` |
| `MessageID` | `int` | 使用者的訊息；select callback 時為 bot 的 prompt 訊息 |
| `UserID` / `Username` | `int64` / `string` | 傳送者（`From`）；缺少時為零值 |
| `Text` / `Caption` | `string` | 訊息文字，或媒體訊息的 caption |
| `Photo` | `[]models.PhotoSize` | 同一張圖片的各尺寸；最後一筆通常最大 |
| `Document` | `*models.Document` | 附加文件（若有） |
| `CallbackData` | `string` | 在 `SendSelect` 鍵盤點擊的項目 |
| `CallbackPicks` | `[]string` | 在 `SendMultiSelect` 鍵盤選定的項目 |
| `Raw` | `*models.Update` | 完整 SDK update，用來取上面沒有複製的欄位 |

`CallbackData` 與 `CallbackPicks` 互斥。要辨識 `SendInput` 的回答，比對 `in.Raw.Message.ReplyToMessage.ID` 與 prompt 的 ID。

## 相關頁面

- [Telegram 訊息](/zh/telegram-messages)
- [Telegram 互動](/zh/telegram-interactions)
- [媒體落地](/zh/media-save)
- [Telegram API](/zh/api-reference-telegram)