# Telegram API

Every exported symbol of `github.com/pardnchiu/go-bot/core/telegram`, built on `github.com/go-telegram/bot` v1.20.0.

## Types

| Symbol | Definition | Notes |
|---|---|---|
| `Bot` | `struct` (unexported fields) | Create with `New`; methods are safe for concurrent use |
| `Status` | `struct { Running bool; Username string; UserID int64 }` | Returned by `Status()` |
| `Input` | `struct` | Fields: `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`. See [Telegram Setup](/telegram#input) |
| `ReplyHandler` | `func(ctx context.Context, input Input) string` | |
| `ChatStatus` | `struct` (unexported fields) | Per-chat status entry managed by `SendStatus`; not constructed by callers |
| `Option` | `func(*options)` | Options for `New` |
| `MessageOption` | `func(*messageOptions)` | Options for `Send`, `SendInput`, `SendSelect`, `SendMultiSelect` |
| `StatusOption` | `func(*statusOptions)` | Options for `SendStatus` |
| `SendType` | `int` | Constants `TypeMarkdown` (MarkdownV2), `TypeHTML` |
| `FileType` | `int` | Constants `TypeDocument`, `TypeVideo`, `TypeAudio` |

## Constructor and options

| Function | Effect |
|---|---|
| `New(token string, opts ...Option) (*Bot, error)` | Error when `token` is empty or the SDK's `getMe` check fails (5-second timeout) |
| `WithHTTPClient(client *http.Client) Option` | HTTP client for polling and uploads |
| `WithPollTimeout(d time.Duration) Option` | Long-poll timeout for `getUpdates` |
| `WithSendType(t SendType) MessageOption` | Parse mode for message text |
| `WithStatusEmoji(emoji string) StatusOption` | Reaction emoji; default `🤔` |
| `WithStatusSendType(t SendType) StatusOption` | Parse mode for status text |

## Methods

| Method | Returns | Errors and limits |
|---|---|---|
| `Start(ctx context.Context)` | `error` | `GetMe` failure |
| `Close()` | `error` | Always `nil` |
| `Status()` | `Status` | |
| `Reply(handler ReplyHandler)` | — | Replaces the previous handler |
| `Send(ctx, chatID int64, replyTo int, text string, opts ...MessageOption)` | `(*models.Message, error)` | API error |
| `Delete(ctx, chatID int64, msgID int)` | `error` | API error |
| `SendFile(ctx, chatID int64, fileType FileType, path string, caption ...string)` | `(*models.Message, error)` | Empty path, `os.Open` failure, unknown `FileType` |
| `SendPhoto(ctx, chatID int64, paths []string, caption ...string)` | `([]*models.Message, error)` | 0 or more than 10 non-empty paths |
| `SendVoice(ctx, chatID int64, path string, caption ...string)` | `(*models.Message, error)` | Empty path, `os.Open` failure |
| `SendInput(ctx, chatID int64, replyTo int, text string, opts ...MessageOption)` | `(*models.Message, error)` | Empty text |
| `SendSelect(ctx, chatID int64, replyTo int, text string, items []string, opts ...MessageOption)` | `(*models.Message, error)` | Empty text, no non-empty item |
| `SendMultiSelect(ctx, chatID int64, replyTo int, text string, items []string, opts ...MessageOption)` | `(*models.Message, error)` | Empty text, no non-empty item, reserved item `__bot_multiselect_done__` |
| `SendStatus(ctx, chatID int64, replyTo int, text string, opts ...StatusOption)` | `error` | Send/edit error when flushed immediately |
| `FinishStatus(ctx, chatID int64)` | `error` | Delete error, or `ctx.Err()` while waiting for an in-flight edit |
| `Save(ctx, fileID, dir string)` | `(string, error)` | Empty args, file over 20 MiB, HTTP non-200, file system errors |

## Related pages

[Telegram Setup](/telegram) · [Telegram Messages](/telegram-messages) · [Telegram Interactions](/telegram-interactions) · [Status Messages](/status-messages) · [Saving Media](/media-save)