Documentation
¶
Overview ¶
Package telegram implements the Telegram Bot API adapter for the orb chat gateway: ingress (webhook and long poll), delivery (typing indicator, streamed preview edits, HTML finalization with chunking), and media download. It plugs into the chat processor via chat.Adapter.
Index ¶
- Constants
- type APIError
- type Adapter
- func (a *Adapter) Account() string
- func (a *Adapter) Download(ctx context.Context, ref chat.AttachmentRef) (io.ReadCloser, string, error)
- func (a *Adapter) NewDelivery(key chat.ConversationKey, replyTo string, resumePreviewID string) chat.Delivery
- func (a *Adapter) Platform() string
- func (a *Adapter) Poll(ctx context.Context, publish func(chat.Message) error) error
- func (a *Adapter) Webhook(publish func(chat.Message) error) http.Handler
- type Options
Constants ¶
const DefaultBaseURL = "https://api.telegram.org"
DefaultBaseURL is the production Bot API endpoint.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
Method string
Code int
Description string
// RetryAfter is the server-requested flood-control pause, when present.
RetryAfter time.Duration
}
APIError is a decoded Bot API failure envelope.
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter is the Telegram implementation of chat.Adapter.
func New ¶
New creates a Telegram adapter. It performs no network calls; the bot identity is resolved lazily via getMe when needed.
func (*Adapter) Account ¶
Account returns the bot's numeric id — the public prefix of the token — matching the Account set on every normalized message.
func (*Adapter) Download ¶
func (a *Adapter) Download(ctx context.Context, ref chat.AttachmentRef) (io.ReadCloser, string, error)
Download implements chat.Adapter: getFile resolves the file path, then the file URL is streamed. The MIME type is the one carried on the ref (getFile does not report one).
func (*Adapter) NewDelivery ¶
func (a *Adapter) NewDelivery(key chat.ConversationKey, replyTo string, resumePreviewID string) chat.Delivery
NewDelivery implements chat.Adapter. replyTo is the inbound event id ("tg:<chat_id>:<message_id>"); a non-empty resumePreviewID makes Finalize edit that message instead of sending a new one (crash recovery).
func (*Adapter) Poll ¶
Poll runs the long-poll ingress loop until ctx ends or publishing fails. It deletes any webhook first (the two ingress modes are mutually exclusive), resolves the bot identity, and advances the update offset only after every message of a batch has been published — a crash before that leaves the batch unacknowledged for redelivery. Run one Poll per bot account.
func (*Adapter) Webhook ¶
Webhook returns the webhook ingress handler: it authenticates the secret token (constant-time, 403 on mismatch), normalizes the update, and hands the message to publish. A publish failure answers non-2xx so Telegram redelivers; album parts hold their response until the buffered group has flushed so a failed flush is redelivered too. Options.Secret is required: with an empty secret every POST would authenticate.
type Options ¶
type Options struct {
// Token is the bot token from @BotFather. Required.
Token string
// BaseURL overrides the Bot API endpoint (tests). Default [DefaultBaseURL].
BaseURL string
// Secret is the webhook secret token compared (constant-time) against the
// X-Telegram-Bot-Api-Secret-Token header. Required for Webhook ingress
// (an empty secret would accept every POST); unused by Poll.
Secret string
// BotUsername pre-seeds the bot identity used for group mention gating
// and /cmd@botname normalization; resolved via getMe when empty.
BotUsername string
// HTTPClient overrides both API clients, including the long-poll one
// (tests). When nil, the poll client timeout is PollTimeout + 10s.
HTTPClient *http.Client
// PollTimeout is the getUpdates long-poll hold. Default 30s.
PollTimeout time.Duration
// PreviewMinInterval rate-limits preview edits per chat. Default 1s.
PreviewMinInterval time.Duration
// TypingInterval is the sendChatAction refresh cadence. Default 4.5s.
TypingInterval time.Duration
// MediaGroupDelay is the album buffering window. Default 1.2s.
MediaGroupDelay time.Duration
// Logger receives non-fatal diagnostics. Optional.
Logger *slog.Logger
}
Options configures New.
Source Files