telegram

package
v0.33.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MessageTypeRegular is 'message'
	MessageTypeRegular = "message"

	// MessageTypeEdited is 'edited_message'
	MessageTypeEdited = "edited_message"

	// MessageTypeChannelPost is 'channel_post'
	MessageTypeChannelPost = "channel_post"

	// MessageTypeEditedChannelPost is 'edited_channel_post'
	MessageTypeEditedChannelPost = "edited_channel_post"
)
View Source 
const EnvTelegramRequireWebhookSecret = "TELEGRAM_WEBHOOK_REQUIRE_SECRET"

EnvTelegramRequireWebhookSecret, when truthy ("true"/"1"/"yes"/"on"), makes a missing webhook secret a HARD FAILURE fleet-wide: if no secret resolves for a bot (neither a per-bot WebhookSecretToken nor the fleet-wide TELEGRAM_WEBHOOK_SECRET), the webhook is rejected rather than allowed with a warning. It is the fleet-wide equivalent of the per-bot BotSettings.RequireWebhookSecret — set it in production so an accidentally-unset secret fails CLOSED (bots reject) instead of silently serving unauthenticated webhooks.

View Source 
const EnvTelegramWebhookSecret = "TELEGRAM_WEBHOOK_SECRET"

EnvTelegramWebhookSecret is the environment variable holding the single, fleet-wide Telegram webhook secret_token. It is applied to EVERY bot that does not set its own BotSettings.WebhookSecretToken, so one provisioned secret authenticates the whole fleet's webhooks with no per-bot configuration (SEC-4). A bot that needs an isolated secret can still override it via BotSettings.WebhookSecretToken.

View Source 
const ForwardedHostHeader = "X-Forwarded-Host"

ForwardedHostHeader is the de-facto standard reverse-proxy header carrying the original Host the client requested, before any Host-rewriting hop (e.g. a proxy that swaps Host to match a backend's own routing requirements). SetWebhook prefers this over r.Host so the webhook URL registered with Telegram reflects the public host callers actually want, even when reached through such a proxy.

View Source 
const PlatformID botsfwconst.Platform = "telegram"

PlatformID is 'telegram'

View Source 
const TelegramWebhookSecretTokenHeader = "X-Telegram-Bot-Api-Secret-Token"

TelegramWebhookSecretTokenHeader is the HTTP header Telegram sends the configured `secret_token` back on with every webhook call, so a handler can verify the request actually came from Telegram (and not from anyone who guessed/discovered the webhook URL, which is not itself a secret - see SEC-4). https://core.telegram.org/bots/api#setwebhook

Variables

View Source 
var CallbackCurrent botmsg.MessageUID = &callbackCurrent{}

CallbackCurrent is what?

View Source 
var Platform botsfw.BotPlatform = platform{}

Platform is a bots platform descriptor (in this case - for Telegram)

View Source 
var TelegramDescriptor = botplan.Descriptor{

	MaxPromptButtons:    100,
	MaxListRows:         0,
	MaxButtonLabelChars: 0,

	SupportsEdit:            true,
	SupportsDelete:          true,
	SupportsCallbackAck:     true,
	WindowGated:             false,
	SupportsInlineURLButton: true,
	SupportsButtonGrid:      true,
	SupportsMedia:           true,
	TextMarkup:              botplan.MarkupHTML,
	SupportsAnchorTextLinks: true,
}

TelegramDescriptor is Telegram's static capability descriptor.

Every field mirrors a record in can-i-use/capability-map.json (cited on the botplan.Descriptor field it sets). Telegram is the richest pilot platform: grid inline buttons, HTML with anchor links, edit and delete, callback acks, no send window.

Functions

func BaseTgChatDtoMaker 

func BaseTgChatDtoMaker(botID string) (botChat botsfwmodels.BotChatData, err error)

func BaseTgUserDtoMaker 

func BaseTgUserDtoMaker(botID string) (botsfwmodels.PlatformUserData, error)

func EditMessageOnCallbackQuery 

func EditMessageOnCallbackQuery(whcbq botinput.CallbackQuery, parseMode, text string) *tgbotapi.EditMessageTextConfig

EditMessageOnCallbackQuery creates edit message

func GetInlineKeyboard added in v0.30.0 

func GetInlineKeyboard(kb *botkb.MessageKeyboard) *tgbotapi.InlineKeyboardMarkup

GetInlineKeyboard converts a botkb.MessageKeyboard into a Telegram inline keyboard markup, for use as an editMessageText/ sendMessage ReplyMarkup from off-webhook code. See GetTelegramKeyboard for the general case.

func GetTelegramBotAPIClient added in v0.20.0 

func GetTelegramBotAPIClient(ctx context.Context, botContext botsfw.BotContext) *tgbotapi.BotAPI

func GetTelegramKeyboard added in v0.30.0 

func GetTelegramKeyboard(keyboard botkb.Keyboard) tgbotapi.Keyboard

GetTelegramKeyboard converts a platform-neutral botkb.Keyboard into its Telegram representation. Exported so code that builds Telegram messages OUTSIDE a webhook responder — e.g. a delayed/background task that edits a message via tgbotapi directly — can reuse the same conversion the responder uses. A nil keyboard yields a nil Telegram keyboard.

func NewBotRecordsFieldsSetter 

func NewBotRecordsFieldsSetter() botsfw.BotRecordsFieldsSetter

func NewTelegramBot 

func NewTelegramBot(
	environment string,
	profile botsfw.BotProfile,
	code, token, paymentTestToken, paymentToken, gaToken string,
	locale i18n.Locale,
	store botsfwstore.StateStore,
) botsfw.BotSettings

NewTelegramBot creates definition of new telegram bot

func NewTelegramChatInstance added in v0.19.0 

func NewTelegramChatInstance(chatInstanceID string, chatID int64, preferredLanguage string) botsfwtgmodels.TgChatInstanceData

func NewTelegramWebhookHandler 

func NewTelegramWebhookHandler(
	botContextProvider botsfw.BotContextProvider,
	translatorProvider botsfw.TranslatorProvider,
	chatInstances ChatInstanceStore,
	opts ...TgWebhookHandlerOption,
) botsfw.WebhookHandler

NewTelegramWebhookHandler creates new Telegram webhooks handler

func NewTelegramWebhookInput 

func NewTelegramWebhookInput(update *tgbotapi.Update, logRequest func()) (botinput.InputMessage, error)

NewTelegramWebhookInput maps telegram update struct to bots framework interface

Types

type CallbackAnswer 

type CallbackAnswer tgbotapi.AnswerCallbackQueryConfig

CallbackAnswer is a callback answer message

func (CallbackAnswer) BotEndpoint added in v0.20.0 

func (a CallbackAnswer) BotEndpoint() string

func (CallbackAnswer) BotMessageType 

func (CallbackAnswer) BotMessageType() botmsg.Type

BotMessageType returns BotMessageTypeCallbackAnswer

type ChatInstanceStore added in v0.28.0 

type ChatInstanceStore interface {
	Get(ctx context.Context, botCode, chatInstanceID string) (data botsfwtgmodels.TgChatInstanceData, found bool, err error)
	Save(ctx context.Context, botCode, chatInstanceID string, data botsfwtgmodels.TgChatInstanceData) error
}

ChatInstanceStore persists the Telegram callback-query to chat mapping. A callback that has no Message uses this mapping to recover the chat and locale. It is intentionally independent from the framework state store because it is Telegram-specific metadata.

type ChatMessageUID 

type ChatMessageUID struct {
	ChatID    int64
	MessageID int
}

ChatMessageUID is what?

func GetMessageUID added in v0.17.0 

func GetMessageUID(whc botsfw.WebhookContext) (*ChatMessageUID, error)

GetMessageUID returns UID of the message to be edited

func NewChatMessageUID 

func NewChatMessageUID(chatID int64, messageID int) *ChatMessageUID

NewChatMessageUID create new ChatMessageUID

func (ChatMessageUID) GetChatID added in v0.25.0 

func (m ChatMessageUID) GetChatID() int64

func (ChatMessageUID) GetMessageID added in v0.25.0 

func (m ChatMessageUID) GetMessageID() int

func (ChatMessageUID) UID 

func (m ChatMessageUID) UID() string

UID return unique ID of the message

type EditRichMessage added in v0.33.3 

type EditRichMessage tgbotapi.EditMessageTextConfig

EditRichMessage is a handler-friendly Telegram BotMessage for replacing the content of an existing message with a native rich message.

func NewEditInlineRichMessage added in v0.33.3 

func NewEditInlineRichMessage(inlineMessageID string, richMessage tgbotapi.InputRichMessage) EditRichMessage

NewEditInlineRichMessage constructs a rich edit for an inline message.

func NewEditRichMessage added in v0.33.3 

func NewEditRichMessage(chatID int64, messageID int, richMessage tgbotapi.InputRichMessage) EditRichMessage

NewEditRichMessage constructs an edit for an arbitrary chat message, which is useful for independently maintained per-player game cards.

func (EditRichMessage) BotEndpoint added in v0.33.3 

func (m EditRichMessage) BotEndpoint() string

func (EditRichMessage) BotMessageType added in v0.33.3 

func (EditRichMessage) BotMessageType() botmsg.Type
type ExportChatInviteLink tgbotapi.ExportChatInviteLink

ExportChatInviteLink is a TG message

func (ExportChatInviteLink) BotEndpoint added in v0.20.0 

func (m ExportChatInviteLink) BotEndpoint() string

func (ExportChatInviteLink) BotMessageType 

func (ExportChatInviteLink) BotMessageType() botmsg.Type

BotMessageType returns BotMessageTypeExportChatInviteLink

type InlineBotMessage 

type InlineBotMessage tgbotapi.InlineConfig

InlineBotMessage is a wrapper for Telegram bot message

func (InlineBotMessage) BotEndpoint added in v0.20.0 

func (m InlineBotMessage) BotEndpoint() string

func (InlineBotMessage) BotMessageType 

func (InlineBotMessage) BotMessageType() botmsg.Type

BotMessageType returns BotMessageTypeInlineResults

type InlineMessageUID 

type InlineMessageUID struct {
	InlineMessageID string
}

InlineMessageUID is inline message UID

func NewInlineMessageUID 

func NewInlineMessageUID(inlineMessageID string) *InlineMessageUID

NewInlineMessageUID creates new inline message UID

func (InlineMessageUID) UID 

func (m InlineMessageUID) UID() string

UID is unique ID of the message

type Invoice added in v0.20.0 

type Invoice tgbotapi.InvoiceConfig

func (Invoice) BotEndpoint added in v0.20.0 

func (m Invoice) BotEndpoint() string

func (Invoice) BotMessageType added in v0.20.0 

func (Invoice) BotMessageType() botmsg.Type

type LeaveChat 

type LeaveChat tgbotapi.LeaveChatConfig

LeaveChat is a leave chat message from bot

func (LeaveChat) BotEndpoint added in v0.20.0 

func (m LeaveChat) BotEndpoint() string

func (LeaveChat) BotMessageType 

func (LeaveChat) BotMessageType() botmsg.Type

BotMessageType return BotMessageTypeLeaveChat

type MessageType added in v0.24.0 

type MessageType string

MessageType represents tpye of Telegram message

type PreCheckoutQueryAnswer added in v0.20.0 

type PreCheckoutQueryAnswer tgbotapi.AnswerPreCheckoutQueryConfig

func (PreCheckoutQueryAnswer) BotMessageType added in v0.20.0 

func (PreCheckoutQueryAnswer) BotMessageType() botmsg.Type

type Renderer added in v0.26.0 

type Renderer struct{}

Renderer renders a neutral botplan.MessagePlan into Telegram messages.

It emits botmsg.MessageFromBot values the existing tgWebhookResponder already knows how to send: text uses FormatHTML (richToHTML), a prompt becomes an inline keyboard whose choice tokens ride as callback_data, a URL action becomes a URL button in the same keyboard, a live panel sets IsEdit, an image becomes a SendPhoto, and a proactive send is an ordinary message (Telegram has no window or templates).

func NewRenderer added in v0.26.0 

func NewRenderer() Renderer

NewRenderer returns a Telegram botplan.Renderer.

func (Renderer) Descriptor added in v0.26.0 

func (Renderer) Descriptor() botplan.Descriptor

Descriptor implements botplan.Renderer.

func (Renderer) Render added in v0.26.0 

func (r Renderer) Render(plan botplan.MessagePlan, target botplan.RenderTarget) ([]botmsg.MessageFromBot, error)

Render implements botplan.Renderer.

Telegram carries a prompt and a URL action in a single keyboard, so a plan almost always renders to exactly one message. An image renders as a separate SendPhoto message preceding the text (Telegram photo captions are limited and the plan's text may be long), so a plan with Media yields two messages.

type SendPhoto added in v0.21.0 

type SendPhoto tgbotapi.PhotoConfig

func (SendPhoto) BotEndpoint added in v0.21.0 

func (m SendPhoto) BotEndpoint() string

func (SendPhoto) BotMessageType added in v0.21.0 

func (SendPhoto) BotMessageType() botmsg.Type

type SendRichMessage added in v0.33.3 

type SendRichMessage tgbotapi.RichMessageConfig

SendRichMessage is a handler-friendly Telegram BotMessage for a persistent native rich message. MessageFromBot.Keyboard is applied as its reply markup by the Telegram responder.

func NewSendRichMessage added in v0.33.3 

func NewSendRichMessage(chatID int64, richMessage tgbotapi.InputRichMessage) SendRichMessage

NewSendRichMessage constructs a persistent rich message. chatID may be zero: the responder then uses MessageFromBot.ToChat or the current update's chat.

func (SendRichMessage) BotEndpoint added in v0.33.3 

func (m SendRichMessage) BotEndpoint() string

func (SendRichMessage) BotMessageType added in v0.33.3 

func (SendRichMessage) BotMessageType() botmsg.Type

type SendRichMessageDraft added in v0.33.3 

type SendRichMessageDraft tgbotapi.RichMessageDraftConfig

SendRichMessageDraft is a handler-friendly Telegram BotMessage for streaming a temporary rich-message draft. Telegram returns bool for this method.

func NewSendRichMessageDraft added in v0.33.3 

func NewSendRichMessageDraft(chatID, draftID int64, richMessage tgbotapi.InputRichMessage) SendRichMessageDraft

NewSendRichMessageDraft constructs a streaming draft. chatID may be zero and is resolved by the responder in the same way as NewSendRichMessage.

func (SendRichMessageDraft) BotEndpoint added in v0.33.3 

func (m SendRichMessageDraft) BotEndpoint() string

func (SendRichMessageDraft) BotMessageType added in v0.33.3 

func (SendRichMessageDraft) BotMessageType() botmsg.Type

type SetBotCommands added in v0.20.0 

type SetBotCommands tgbotapi.SetMyCommandsConfig

func (SetBotCommands) BotEndpoint added in v0.20.0 

func (m SetBotCommands) BotEndpoint() string

func (SetBotCommands) BotMessageType added in v0.20.0 

func (SetBotCommands) BotMessageType() botmsg.Type

type SetBotDescription added in v0.20.0 

type SetBotDescription tgbotapi.SetMyDescription

func (SetBotDescription) BotEndpoint added in v0.20.0 

func (m SetBotDescription) BotEndpoint() string

func (SetBotDescription) BotMessageType added in v0.20.0 

func (SetBotDescription) BotMessageType() botmsg.Type

type SetBotShortDescription added in v0.20.0 

type SetBotShortDescription tgbotapi.SetMyShortDescription

func (SetBotShortDescription) BotEndpoint added in v0.20.0 

func (m SetBotShortDescription) BotEndpoint() string

func (SetBotShortDescription) BotMessageType added in v0.20.0 

func (SetBotShortDescription) BotMessageType() botmsg.Type

type TelegramRequest added in v0.33.3 

type TelegramRequest struct {
	Request        tgbotapi.Sendable
	ReturnsMessage bool
}

TelegramRequest exposes any low-level Telegram Sendable through the standard MessageFromBot handler path. Prefer a dedicated wrapper such as SendRichMessage when one exists; use this for Telegram-only methods such as ephemeral-message edits and deletes.

func NewTelegramBooleanRequest added in v0.33.3 

func NewTelegramBooleanRequest(request tgbotapi.Sendable) TelegramRequest

NewTelegramBooleanRequest wraps a Telegram method that returns True.

func NewTelegramMessageRequest added in v0.33.3 

func NewTelegramMessageRequest(request tgbotapi.Sendable) TelegramRequest

NewTelegramMessageRequest wraps a Telegram method that returns Message.

func (TelegramRequest) BotMessageType added in v0.33.3 

func (TelegramRequest) BotMessageType() botmsg.Type

BotMessageType is intentionally undefined: tgWebhookResponder recognizes TelegramRequest by concrete type before the platform-neutral type switch.

func (TelegramRequest) TelegramMethod added in v0.33.3 

func (m TelegramRequest) TelegramMethod() string

func (TelegramRequest) Values added in v0.33.3 

func (m TelegramRequest) Values() (url.Values, error)

type TgChat added in v0.24.0 

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

TgChat is wrapper for Telegram chat

func (TgChat) GetID added in v0.24.0 

func (wh TgChat) GetID() string

GetID returns telegram chat ID

func (TgChat) GetType added in v0.24.0 

func (wh TgChat) GetType() string

GetType returns telegram chat type

func (TgChat) IsGroupChat added in v0.24.0 

func (wh TgChat) IsGroupChat() bool

IsGroupChat indicates type of chat (group or private)

type TgWebhookHandlerOption added in v0.32.0 

type TgWebhookHandlerOption func(*tgWebhookHandler)

TgWebhookHandlerOption configures a Telegram webhook handler at construction time (functional-options pattern).

func WithAdminPathPrefix added in v0.32.0 

func WithAdminPathPrefix(adminPrefix string) TgWebhookHandlerOption

WithAdminPathPrefix mounts the admin-only endpoints (set-webhook and the test route) under adminPrefix instead of the public webhook pathPrefix, so a host can gate that prefix with admin auth. set-webhook (re-)points a bot's live webhook using the bot's own token, so on a publicly reachable origin it must NOT be open.

The public /tg/hook endpoint (which Telegram POSTs to) and the hook URL that set-webhook registers with Telegram are unaffected — both keep using the public pathPrefix. An empty adminPrefix (the default) preserves the legacy behaviour of mounting every endpoint under the public pathPrefix.

func WithResponderTransform added in v0.33.1 

func WithResponderTransform(transform WebhookResponderTransform) TgWebhookHandlerOption

WithResponderTransform installs a host-owned responder transform. The transform is applied once per webhook after the Telegram responder has been created and before any router action can run.

func WithRouterResponderTransform added in v0.33.1 

func WithRouterResponderTransform(transform WebhookResponderTransform) TgWebhookHandlerOption

WithRouterResponderTransform installs a transform used only for messages returned through router dispatch. WebhookContext.Responder remains governed by WithResponderTransform, so feature direct sends cannot obtain router-only command authority.

type TgWebhookInlineQuery 

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

TgWebhookInlineQuery is wrapper

func (TgWebhookInlineQuery) BotChatID 

func (iq TgWebhookInlineQuery) BotChatID() (string, error)

BotChatID returns bot chat ID

func (TgWebhookInlineQuery) Chat 

func (whi TgWebhookInlineQuery) Chat() botinput.Chat

func (TgWebhookInlineQuery) GetFrom 

func (iq TgWebhookInlineQuery) GetFrom() botinput.Sender

GetFrom returns recipient

func (TgWebhookInlineQuery) GetID 

func (whi TgWebhookInlineQuery) GetID() interface{}

func (TgWebhookInlineQuery) GetInlineQueryID 

func (iq TgWebhookInlineQuery) GetInlineQueryID() string

GetInlineQueryID return inline query ID

func (TgWebhookInlineQuery) GetOffset 

func (iq TgWebhookInlineQuery) GetOffset() string

GetOffset returns offset

func (TgWebhookInlineQuery) GetQuery 

func (iq TgWebhookInlineQuery) GetQuery() string

GetQuery returns query string

func (TgWebhookInlineQuery) GetRecipient 

func (whi TgWebhookInlineQuery) GetRecipient() botinput.Recipient

func (TgWebhookInlineQuery) GetSender 

func (whi TgWebhookInlineQuery) GetSender() botinput.User

func (TgWebhookInlineQuery) GetTime 

func (whi TgWebhookInlineQuery) GetTime() time.Time

func (TgWebhookInlineQuery) InputType 

func (whi TgWebhookInlineQuery) InputType() botinput.Type

func (TgWebhookInlineQuery) LogRequest 

func (whi TgWebhookInlineQuery) LogRequest()

func (TgWebhookInlineQuery) MessageIntID added in v0.23.0 

func (whi TgWebhookInlineQuery) MessageIntID() int

func (TgWebhookInlineQuery) MessageStringID added in v0.23.0 

func (whi TgWebhookInlineQuery) MessageStringID() string

func (TgWebhookInlineQuery) TelegramChatID 

func (whi TgWebhookInlineQuery) TelegramChatID() int64

func (TgWebhookInlineQuery) TgUpdate 

func (whi TgWebhookInlineQuery) TgUpdate() *tgbotapi.Update

type TgWebhookInput 

type TgWebhookInput interface {
	TgUpdate() *tgbotapi.Update
}

TgWebhookInput is a wrapper of telegram update struct to bots framework interface

type WebhookCallbackQuery added in v0.19.0 

type WebhookCallbackQuery interface {
	botinput.CallbackQuery
	GetInlineMessageID() string // Telegram only?
	GetChatInstanceID() string  // Telegram only?
}

type WebhookResponderTransform added in v0.33.1 

type WebhookResponderTransform func(botsfw.WebhookContext, botsfw.WebhookResponder) botsfw.WebhookResponder

WebhookResponderTransform wraps the responder used for a single webhook. The transformed responder is installed into WebhookContext as well as passed to router dispatch, so direct responder sends and router-returned messages share one host-enforced delivery boundary.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.