telegram

Documentation

Overview

Package telegram is the gateway's Telegram channel adapter. It talks to the Bot API directly over net/http (long-poll getUpdates + sendMessage) — no SDK, matching the repo's thin-dependency ethos. The user creates their own bot via @BotFather and puts the token in the global .env as TELEGRAM_BOT_TOKEN; messages and the token never leave the machine running the gateway.

Index

• type Channel
  • func New(token string, store OffsetStore, mediaDir string) *Channel
  • func (c *Channel) Name() string
  • func (c *Channel) Send(ctx context.Context, conversation string, msg channels.Outbound) error
  • func (c *Channel) Start(ctx context.Context, sink channels.Sink) error
• type OffsetStore

Types

type Channel

type Channel struct {
	// contains filtered or unexported fields
}

Channel is a Telegram bot connection.

func New

func New(token string, store OffsetStore, mediaDir string) *Channel

New builds a Telegram channel for the given bot token. store may be nil, in which case the poll offset lives only in memory (and a restart re-reads the backlog, which the router's dedup then discards). mediaDir is the gateway media spool photos/voice notes/documents are downloaded into; "" disables attachment handling (messages still flow as text).

func (*Channel) Name

func (c *Channel) Name() string

Name returns the adapter identifier.

func (*Channel) Send

func (c *Channel) Send(ctx context.Context, conversation string, msg channels.Outbound) error

Send posts a text reply to a chat, split with the shared chunker to respect Telegram's per-message limit. Each part honors a 429 flood-wait; a permanent error (any other non-2xx) fails fast instead of retrying forever. A synthesized voice rendition (VoicePath, OGG/Opus) is sent first as a native voice bubble, best-effort — the text always follows.

func (*Channel) Start

func (c *Channel) Start(ctx context.Context, sink channels.Sink) error

Start long-polls getUpdates and forwards each text message as an Inbound until ctx is cancelled. The ack cursor is loaded from (and saved to) the offset store so a restart resumes where it left off. Transient errors back off with jitter rather than returning, so a flaky network never takes the gateway down.

type OffsetStore

type OffsetStore interface {
	Offset(ctx context.Context, channel string) (int64, error)
	SetOffset(ctx context.Context, channel string, offset int64) error
}

OffsetStore persists the getUpdates ack cursor so a restart resumes where it left off instead of re-fetching (and re-running) the whole backlog. Satisfied by the gateway's state store; nil in tests / when no persistence is wired.