core

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ErrorCodeBadRequest          = 400 // Bad Request
	ErrorCodeUnauthorized        = 401 // Unauthorized
	ErrorCodeForbidden           = 403 // Forbidden
	ErrorCodeNotFound            = 404 // Not Found
	ErrorCodeConflict            = 409 // Conflict
	ErrorCodeTooManyRequests     = 429 // Too Many Requests
	ErrorCodeInternalServerError = 500 // Internal Server Error
)

Common Telegram Error Codes

Variables

View Source 
var (
	ErrCallbackDataKeyCount          = errors.New("callback data key/value count mismatch")
	ErrCallbackDataInvalidSeparator  = errors.New("callback data separator cannot be empty")
	ErrCallbackDataContainsSeparator = errors.New("callback data value contains separator")
	ErrCallbackDataPrefixInvalid     = errors.New("callback data prefix contains separator")
	ErrCallbackDataModelInvalid      = errors.New("callback data model must be a struct or pointer to struct")
	ErrCallbackDataMarkerMissing     = errors.New("callback data marker not found (embed tools.CallbackData)")
)

Functions

func GetCallbackStruct added in v0.2.0 

func GetCallbackStruct[T any](ctx *Context) (T, bool)

GetCallbackStruct reads parsed callback payload from Context. Use with OnCallbackStruct registrations.

func IsTelegramError 

func IsTelegramError(err error) bool

IsTelegramError checks if an error is a TelegramError

Types

type Bot 

type Bot struct {
	Token string

	StateManager *state.Manager
	*RegisterCommands
	// contains filtered or unexported fields
}

func NewBot 

func NewBot(token string) *Bot

func (*Bot) AddHandler 

func (b *Bot) AddHandler(filter FilterFunc, handler HandlerFunc, opts ...interface{})

AddHandler adds a custom handler with a filter and optional state filter

func (*Bot) AddStickerToSet 

func (b *Bot) AddStickerToSet(params models.AddStickerToSetParams) (bool, error)

func (*Bot) AnswerCallbackQuery 

func (b *Bot) AnswerCallbackQuery(callbackQueryID string, text string, showAlert bool) (bool, error)

func (*Bot) AnswerInlineQuery 

func (b *Bot) AnswerInlineQuery(params models.AnswerInlineQueryParams) (bool, error)

func (*Bot) AnswerPreCheckoutQuery 

func (b *Bot) AnswerPreCheckoutQuery(params models.AnswerPreCheckoutQueryParams) (bool, error)

func (*Bot) AnswerShippingQuery 

func (b *Bot) AnswerShippingQuery(params models.AnswerShippingQueryParams) (bool, error)

func (*Bot) ApproveChatJoinRequest 

func (b *Bot) ApproveChatJoinRequest(params models.ApproveChatJoinRequestParams) (bool, error)

func (*Bot) BanChatMember 

func (b *Bot) BanChatMember(params *models.BanChatMemberParams) (bool, error)

func (*Bot) BanChatSenderChat 

func (b *Bot) BanChatSenderChat(params models.BanChatSenderChatParams) (bool, error)

func (*Bot) CloseForumTopic 

func (b *Bot) CloseForumTopic(params models.CloseForumTopicParams) (bool, error)

func (*Bot) CloseGeneralForumTopic 

func (b *Bot) CloseGeneralForumTopic(params models.CloseGeneralForumTopicParams) (bool, error)

func (*Bot) CopyMessage 

func (b *Bot) CopyMessage(params *models.CopyMessageParams) (*models.MessageID, error)

func (*Bot) CopyMessages 

func (b *Bot) CopyMessages(params models.CopyMessagesParams) ([]models.MessageID, error)
func (b *Bot) CreateChatInviteLink(params models.CreateChatInviteLinkParams) (*models.ChatInviteLink, error)

func (*Bot) CreateForumTopic 

func (b *Bot) CreateForumTopic(params models.CreateForumTopicParams) (*models.ForumTopic, error)
func (b *Bot) CreateInvoiceLink(params models.CreateInvoiceLinkParams) (string, error)

func (*Bot) CreateNewStickerSet 

func (b *Bot) CreateNewStickerSet(params models.CreateNewStickerSetParams) (bool, error)

func (*Bot) DeclineChatJoinRequest 

func (b *Bot) DeclineChatJoinRequest(params models.DeclineChatJoinRequestParams) (bool, error)

func (*Bot) DeleteChatPhoto 

func (b *Bot) DeleteChatPhoto(params models.DeleteChatPhotoParams) (bool, error)

func (*Bot) DeleteChatStickerSet 

func (b *Bot) DeleteChatStickerSet(params models.DeleteChatStickerSetParams) (bool, error)

func (*Bot) DeleteForumTopic 

func (b *Bot) DeleteForumTopic(params models.DeleteForumTopicParams) (bool, error)

func (*Bot) DeleteMessage 

func (b *Bot) DeleteMessage(params *models.DeleteMessageParams) (bool, error)

func (*Bot) DeleteMessages 

func (b *Bot) DeleteMessages(params models.DeleteMessagesParams) (bool, error)

func (*Bot) DeleteMyCommands 

func (b *Bot) DeleteMyCommands(params models.DeleteMyCommandsParams) (bool, error)

func (*Bot) DeleteStickerFromSet 

func (b *Bot) DeleteStickerFromSet(params models.DeleteStickerFromSetParams) (bool, error)

func (*Bot) DeleteWebhook 

func (b *Bot) DeleteWebhook(params models.DeleteWebhookParams) (bool, error)
func (b *Bot) EditChatInviteLink(params models.EditChatInviteLinkParams) (*models.ChatInviteLink, error)

func (*Bot) EditForumTopic 

func (b *Bot) EditForumTopic(params models.EditForumTopicParams) (bool, error)

func (*Bot) EditGeneralForumTopic 

func (b *Bot) EditGeneralForumTopic(params models.EditGeneralForumTopicParams) (bool, error)

func (*Bot) EditMessageCaption 

func (b *Bot) EditMessageCaption(params *models.EditMessageCaptionParams) (*models.Message, error)

func (*Bot) EditMessageChecklist 

func (b *Bot) EditMessageChecklist(params *models.EditMessageChecklistParams) (*models.Message, error)

func (*Bot) EditMessageLiveLocation 

func (b *Bot) EditMessageLiveLocation(params *models.EditMessageLiveLocationParams) (*models.Message, error)

func (*Bot) EditMessageMedia 

func (b *Bot) EditMessageMedia(params *models.EditMessageMediaParams) (*models.Message, error)

func (*Bot) EditMessageReplyMarkup 

func (b *Bot) EditMessageReplyMarkup(params *models.EditMessageReplyMarkupParams) (*models.Message, error)

func (*Bot) EditMessageText 

func (b *Bot) EditMessageText(params *models.EditMessageTextParams) (*models.Message, error)
func (b *Bot) ExportChatInviteLink(chatID interface{}) (string, error)

func (*Bot) ForwardMessage 

func (b *Bot) ForwardMessage(params *models.ForwardMessageParams) (*models.Message, error)

func (*Bot) ForwardMessages 

func (b *Bot) ForwardMessages(params models.ForwardMessagesParams) ([]models.MessageID, error)

func (*Bot) GetChat 

func (b *Bot) GetChat(chatID interface{}) (*models.Chat, error)

func (*Bot) GetChatAdministrators 

func (b *Bot) GetChatAdministrators(chatID interface{}) ([]models.ChatMember, error)

func (*Bot) GetChatMember 

func (b *Bot) GetChatMember(params *models.GetChatMemberParams) (*models.ChatMember, error)

func (*Bot) GetChatMemberCount 

func (b *Bot) GetChatMemberCount(chatID interface{}) (int, error)

func (*Bot) GetChatMenuButton 

func (b *Bot) GetChatMenuButton(params models.GetChatMenuButtonParams) (*models.MenuButton, error)

func (*Bot) GetCustomEmojiStickers 

func (b *Bot) GetCustomEmojiStickers(params models.GetCustomEmojiStickersParams) ([]models.Sticker, error)

func (*Bot) GetFile 

func (b *Bot) GetFile(fileID string) (*models.File, error)

func (*Bot) GetGameHighScores 

func (b *Bot) GetGameHighScores(params models.GetGameHighScoresParams) ([]models.GameHighScore, error)

func (*Bot) GetMe 

func (b *Bot) GetMe() (*models.User, error)

func (*Bot) GetMyCommands 

func (b *Bot) GetMyCommands(params models.GetMyCommandsParams) ([]models.BotCommand, error)

func (*Bot) GetMyDescription 

func (b *Bot) GetMyDescription(params models.GetMyDescriptionParams) (*models.BotDescription, error)

func (*Bot) GetMyName 

func (b *Bot) GetMyName(params models.GetMyNameParams) (*models.BotName, error)

func (*Bot) GetMyShortDescription 

func (b *Bot) GetMyShortDescription(params models.GetMyShortDescriptionParams) (*models.BotShortDescription, error)

func (*Bot) GetStickerSet 

func (b *Bot) GetStickerSet(params models.GetStickerSetParams) (*models.StickerSet, error)

func (*Bot) GetUpdates 

func (b *Bot) GetUpdates(params *models.GetUpdatesParams) ([]models.Update, error)

func (*Bot) GetUserProfileAudios 

func (b *Bot) GetUserProfileAudios(params *models.GetUserProfileAudiosParams) (*models.UserProfileAudios, error)

Bot API 9.4: Get user profile audios

func (*Bot) GetUserProfilePhotos 

func (b *Bot) GetUserProfilePhotos(params models.GetUserProfilePhotosParams) (*models.UserProfilePhotos, error)

func (*Bot) GetWebhookInfo 

func (b *Bot) GetWebhookInfo() (*models.WebhookInfo, error)

func (*Bot) HideGeneralForumTopic 

func (b *Bot) HideGeneralForumTopic(params models.HideGeneralForumTopicParams) (bool, error)

func (*Bot) LeaveChat 

func (b *Bot) LeaveChat(chatID interface{}) (bool, error)

func (*Bot) OnBadRequest 

func (b *Bot) OnBadRequest(handler ErrorHandlerFunc)

OnBadRequest registers a handler for bad request errors (400)

func (*Bot) OnBotBlocked 

func (b *Bot) OnBotBlocked(handler ErrorHandlerFunc)

OnBotBlocked registers a handler for bot was blocked by user errors

func (*Bot) OnBotKicked 

func (b *Bot) OnBotKicked(handler ErrorHandlerFunc)

OnBotKicked registers a handler for bot was kicked from chat errors

func (*Bot) OnButtonDataInvalid 

func (b *Bot) OnButtonDataInvalid(handler ErrorHandlerFunc)

OnButtonDataInvalid registers a handler for invalid button data errors

func (*Bot) OnChatNotFound 

func (b *Bot) OnChatNotFound(handler ErrorHandlerFunc)

OnChatNotFound registers a handler for chat not found errors

func (*Bot) OnError 

func (b *Bot) OnError(filter ErrorFilter, handler ErrorHandlerFunc)

OnError registers an error handler with optional filter Pass nil as filter to handle all errors

func (*Bot) OnForbiddenError 

func (b *Bot) OnForbiddenError(handler ErrorHandlerFunc)

OnForbiddenError registers a handler for forbidden errors (403)

func (*Bot) OnInvalidFileID 

func (b *Bot) OnInvalidFileID(handler ErrorHandlerFunc)

OnInvalidFileID registers a handler for invalid file_id errors

func (*Bot) OnMessageCantBeDeleted 

func (b *Bot) OnMessageCantBeDeleted(handler ErrorHandlerFunc)

OnMessageCantBeDeleted registers a handler for message can't be deleted errors

func (*Bot) OnMessageCantBeEdited 

func (b *Bot) OnMessageCantBeEdited(handler ErrorHandlerFunc)

OnMessageCantBeEdited registers a handler for message can't be edited errors

func (*Bot) OnMessageNotFound 

func (b *Bot) OnMessageNotFound(handler ErrorHandlerFunc)

OnMessageNotFound registers a handler for message not found errors

func (*Bot) OnMessageTextEmpty 

func (b *Bot) OnMessageTextEmpty(handler ErrorHandlerFunc)

OnMessageTextEmpty registers a handler for empty message text errors

func (*Bot) OnMessageTooLong 

func (b *Bot) OnMessageTooLong(handler ErrorHandlerFunc)

OnMessageTooLong registers a handler for message too long errors

func (*Bot) OnRateLimitError 

func (b *Bot) OnRateLimitError(handler ErrorHandlerFunc)

OnRateLimitError registers a handler for rate limit errors (429)

func (*Bot) OnTelegramError 

func (b *Bot) OnTelegramError(handler ErrorHandlerFunc)

OnTelegramError registers a handler for Telegram API errors

func (*Bot) PinChatMessage 

func (b *Bot) PinChatMessage(params *models.PinChatMessageParams) (bool, error)

func (*Bot) PromoteChatMember 

func (b *Bot) PromoteChatMember(params *models.PromoteChatMemberParams) (bool, error)

func (*Bot) RegisterGroup 

func (b *Bot) RegisterGroup(group *HandlerGroup)

RegisterGroup registers all handlers from a handler group

func (*Bot) RemoveMyProfilePhoto 

func (b *Bot) RemoveMyProfilePhoto() (bool, error)

Bot API 9.4: Remove bot profile photo

func (*Bot) ReopenForumTopic 

func (b *Bot) ReopenForumTopic(params models.ReopenForumTopicParams) (bool, error)

func (*Bot) ReopenGeneralForumTopic 

func (b *Bot) ReopenGeneralForumTopic(params models.ReopenGeneralForumTopicParams) (bool, error)

func (*Bot) RestrictChatMember 

func (b *Bot) RestrictChatMember(params *models.RestrictChatMemberParams) (bool, error)
func (b *Bot) RevokeChatInviteLink(params models.RevokeChatInviteLinkParams) (*models.ChatInviteLink, error)

func (*Bot) SendAnimation 

func (b *Bot) SendAnimation(params models.SendAnimationParams) (*models.Message, error)

func (*Bot) SendAudio 

func (b *Bot) SendAudio(params *models.SendAudioParams) (*models.Message, error)

func (*Bot) SendChatAction 

func (b *Bot) SendChatAction(chatID interface{}, action string) (bool, error)

func (*Bot) SendChecklist 

func (b *Bot) SendChecklist(params models.SendChecklistParams) (*models.Message, error)

func (*Bot) SendContact 

func (b *Bot) SendContact(params *models.SendContactParams) (*models.Message, error)

func (*Bot) SendDice 

func (b *Bot) SendDice(params models.SendDiceParams) (*models.Message, error)

func (*Bot) SendDocument 

func (b *Bot) SendDocument(params *models.SendDocumentParams) (*models.Message, error)

func (*Bot) SendGame 

func (b *Bot) SendGame(params models.SendGameParams) (*models.Message, error)

func (*Bot) SendInvoice 

func (b *Bot) SendInvoice(params models.SendInvoiceParams) (*models.Message, error)

func (*Bot) SendLocation 

func (b *Bot) SendLocation(params *models.SendLocationParams) (*models.Message, error)

func (*Bot) SendMediaGroup 

func (b *Bot) SendMediaGroup(params models.SendMediaGroupParams) ([]models.Message, error)

func (*Bot) SendMessage 

func (b *Bot) SendMessage(params *models.SendMessageParams) (*models.Message, error)

func (*Bot) SendMessageDraft 

func (b *Bot) SendMessageDraft(params models.SendMessageDraftParams) (bool, error)

func (*Bot) SendPaidMedia 

func (b *Bot) SendPaidMedia(params models.SendPaidMediaParams) (*models.Message, error)

func (*Bot) SendPhoto 

func (b *Bot) SendPhoto(params *models.SendPhotoParams) (*models.Message, error)

func (*Bot) SendPoll 

func (b *Bot) SendPoll(params *models.SendPollParams) (*models.Message, error)

func (*Bot) SendSticker 

func (b *Bot) SendSticker(params models.SendStickerParams) (*models.Message, error)

func (*Bot) SendVenue 

func (b *Bot) SendVenue(params models.SendVenueParams) (*models.Message, error)

func (*Bot) SendVideo 

func (b *Bot) SendVideo(params *models.SendVideoParams) (*models.Message, error)

func (*Bot) SendVideoNote 

func (b *Bot) SendVideoNote(params models.SendVideoNoteParams) (*models.Message, error)

func (*Bot) SendVoice 

func (b *Bot) SendVoice(params models.SendVoiceParams) (*models.Message, error)

func (*Bot) SetChatAdministratorCustomTitle 

func (b *Bot) SetChatAdministratorCustomTitle(params *models.SetChatAdministratorCustomTitleParams) (bool, error)

func (*Bot) SetChatDescription 

func (b *Bot) SetChatDescription(params models.SetChatDescriptionParams) (bool, error)

func (*Bot) SetChatMenuButton 

func (b *Bot) SetChatMenuButton(params models.SetChatMenuButtonParams) (bool, error)

func (*Bot) SetChatPermissions 

func (b *Bot) SetChatPermissions(params models.SetChatPermissionsParams) (bool, error)

func (*Bot) SetChatPhoto 

func (b *Bot) SetChatPhoto(params models.SetChatPhotoParams) (bool, error)

func (*Bot) SetChatStickerSet 

func (b *Bot) SetChatStickerSet(params models.SetChatStickerSetParams) (bool, error)

func (*Bot) SetChatTitle 

func (b *Bot) SetChatTitle(params models.SetChatTitleParams) (bool, error)

func (*Bot) SetFallbackErrorHandler 

func (b *Bot) SetFallbackErrorHandler(handler ErrorHandlerFunc)

SetFallbackErrorHandler sets a fallback error handler for all unhandled errors

func (*Bot) SetGameScore 

func (b *Bot) SetGameScore(params models.SetGameScoreParams) (*models.Message, error)

func (*Bot) SetMessageReaction 

func (b *Bot) SetMessageReaction(params models.SetMessageReactionParams) (bool, error)

func (*Bot) SetMyCommands 

func (b *Bot) SetMyCommands(params models.SetMyCommandsParams) (bool, error)

func (*Bot) SetMyDescription 

func (b *Bot) SetMyDescription(params models.SetMyDescriptionParams) (bool, error)

func (*Bot) SetMyName 

func (b *Bot) SetMyName(params models.SetMyNameParams) (bool, error)

func (*Bot) SetMyProfilePhoto 

func (b *Bot) SetMyProfilePhoto(photo *models.InputProfilePhoto) (bool, error)

Bot API 9.4: Set bot profile photo

func (*Bot) SetMyShortDescription 

func (b *Bot) SetMyShortDescription(params models.SetMyShortDescriptionParams) (bool, error)

func (*Bot) SetStickerPositionInSet 

func (b *Bot) SetStickerPositionInSet(params models.SetStickerPositionInSetParams) (bool, error)

func (*Bot) SetStickerSetThumbnail 

func (b *Bot) SetStickerSetThumbnail(params models.SetStickerSetThumbnailParams) (bool, error)

func (*Bot) SetStorage 

func (b *Bot) SetStorage(store storage.BaseStorage)

SetStorage sets a custom storage backend for state management

func (*Bot) SetWebhook 

func (b *Bot) SetWebhook(params models.SetWebhookParams) (bool, error)

func (*Bot) StartPolling 

func (b *Bot) StartPolling(options *PollingOptions)

StartPolling starts polling for updates Pass nil to use default settings, or pass *PollingOptions to customize

func (*Bot) StopMessageLiveLocation 

func (b *Bot) StopMessageLiveLocation(params *models.StopMessageLiveLocationParams) (*models.Message, error)

func (*Bot) StopPoll 

func (b *Bot) StopPoll(params *models.StopPollParams) (*models.Poll, error)

func (*Bot) UnbanChatMember 

func (b *Bot) UnbanChatMember(params *models.UnbanChatMemberParams) (bool, error)

func (*Bot) UnbanChatSenderChat 

func (b *Bot) UnbanChatSenderChat(params models.UnbanChatSenderChatParams) (bool, error)

func (*Bot) UnhideGeneralForumTopic 

func (b *Bot) UnhideGeneralForumTopic(params models.UnhideGeneralForumTopicParams) (bool, error)

func (*Bot) UnpinAllChatMessages 

func (b *Bot) UnpinAllChatMessages(chatID interface{}) (bool, error)

func (*Bot) UnpinAllForumTopicMessages 

func (b *Bot) UnpinAllForumTopicMessages(params models.UnpinAllForumTopicMessagesParams) (bool, error)

func (*Bot) UnpinChatMessage 

func (b *Bot) UnpinChatMessage(params *models.UnpinChatMessageParams) (bool, error)

func (*Bot) UploadStickerFile 

func (b *Bot) UploadStickerFile(params models.UploadStickerFileParams) (*models.File, error)

type CallbackData added in v0.2.0 

type CallbackData struct {
	Prefix    string
	Separator string
	Keys      []string
}

CallbackData helps build and parse callback data strings. Format: prefix + separator + values Example: NewCallbackData("order", "action", "id").Pack("view", "42") => "order:view:42"

func NewCallbackData added in v0.2.0 

func NewCallbackData(prefix string, keys ...string) *CallbackData

NewCallbackData creates a new CallbackData instance with default separator ":".

func NewCallbackDataFromStruct added in v0.2.0 

func NewCallbackDataFromStruct(model interface{}) (*CallbackData, error)

NewCallbackDataFromStruct builds a CallbackData definition from a struct model. The model must embed tools.CallbackData (anonymous field) to opt in. Optional tags on the embedded marker field:

  • prefix:"admin" to set prefix (default: derived from struct name)
  • separator:"|" to set separator (default: ":")

Exported fields (excluding embedded fields) are used as callback keys in order.

func (*CallbackData) Filter added in v0.2.0 

func (c *CallbackData) Filter() FilterFunc

Filter creates a filter for callback queries that match this CallbackData.

func (*CallbackData) Pack added in v0.2.0 

func (c *CallbackData) Pack(values ...string) (string, error)

Pack builds callback data from values in the same order as Keys.

func (*CallbackData) PackStruct added in v0.2.0 

func (c *CallbackData) PackStruct(v interface{}) (string, error)

PackStruct builds callback data from an exported struct's fields. The field names must match Keys in order. Supports string, bool, ints, and types implementing fmt.Stringer or encoding.TextMarshaler.

func (*CallbackData) Parse added in v0.2.0 

func (c *CallbackData) Parse(data string) (map[string]string, bool)

Parse parses callback data and returns a map of key/value pairs. Returns false if prefix or part count does not match.

func (*CallbackData) ParseToStruct added in v0.2.0 

func (c *CallbackData) ParseToStruct(data string, v interface{}) bool

ParseToStruct parses callback data into an exported struct's fields. The field names must match Keys in order. Supports string, bool, ints, and types implementing encoding.TextUnmarshaler.

func (*CallbackData) WithSeparator added in v0.2.0 

func (c *CallbackData) WithSeparator(separator string) *CallbackData

WithSeparator sets a custom separator (ignored if empty).

type Context added in v0.1.1 

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

Context provides a way to store and retrieve data during request processing It allows middlewares to pass data to handlers

func NewContext added in v0.1.1 

func NewContext() *Context

NewContext creates a new Context instance

func (*Context) Clear added in v0.1.1 

func (c *Context) Clear()

Clear removes all data from the context

func (*Context) Delete added in v0.1.1 

func (c *Context) Delete(key string)

Delete removes a key from the context

func (*Context) Get added in v0.1.1 

func (c *Context) Get(key string) interface{}

Get retrieves a value from the context Returns nil if the key doesn't exist

func (*Context) GetBool added in v0.1.1 

func (c *Context) GetBool(key string) bool

GetBool retrieves a bool value from the context Returns false if the key doesn't exist or value is not a bool

func (*Context) GetCallbackData added in v0.2.0 

func (c *Context) GetCallbackData() interface{}

GetCallbackData returns parsed callback payload stored by OnCallbackStruct.

func (*Context) GetInt added in v0.1.1 

func (c *Context) GetInt(key string) int

GetInt retrieves an int value from the context Returns 0 if the key doesn't exist or value is not an int

func (*Context) GetInt64 added in v0.1.1 

func (c *Context) GetInt64(key string) int64

GetInt64 retrieves an int64 value from the context Returns 0 if the key doesn't exist or value is not an int64

func (*Context) GetStateData added in v0.2.0 

func (c *Context) GetStateData() map[string]interface{}

GetStateData returns the user's state data as a map Returns nil if no data exists

func (*Context) GetStateName added in v0.2.0 

func (c *Context) GetStateName() string

GetStateName returns the user's current state name Returns empty string if no state exists

func (*Context) GetString added in v0.1.1 

func (c *Context) GetString(key string) string

GetString retrieves a string value from the context Returns empty string if the key doesn't exist or value is not a string

func (*Context) Has added in v0.1.1 

func (c *Context) Has(key string) bool

Has checks if a key exists in the context

func (*Context) Keys added in v0.1.1 

func (c *Context) Keys() []string

Keys returns all keys in the context

func (*Context) LoadCallbackData added in v0.2.0 

func (c *Context) LoadCallbackData(out interface{}) bool

LoadCallbackData loads parsed callback payload from context into out. out must be a non-nil pointer to struct.

func (*Context) MatchCallbackData added in v0.2.0 

func (c *Context) MatchCallbackData(expect interface{}) bool

MatchCallbackData checks whether parsed callback payload in context matches non-zero exported fields of expect.

expect must be a struct (or pointer to struct) of the same type as payload. Zero-value fields in expect are ignored.

func (*Context) Set added in v0.1.1 

func (c *Context) Set(key string, value interface{})

Set stores a value in the context

type ErrorFilter 

type ErrorFilter func(error) bool

ErrorFilter filters errors based on a condition

func AllErrorsFilter 

func AllErrorsFilter() ErrorFilter

AllErrorsFilter creates a filter that matches all errors

func BadRequestErrorFilter 

func BadRequestErrorFilter() ErrorFilter

BadRequestErrorFilter creates a filter for bad request errors (400)

func BotBlockedFilter 

func BotBlockedFilter() ErrorFilter

BotBlockedFilter creates a filter for bot was blocked by user errors

func BotKickedFilter 

func BotKickedFilter() ErrorFilter

BotKickedFilter creates a filter for bot was kicked from chat errors

func ButtonDataInvalidFilter 

func ButtonDataInvalidFilter() ErrorFilter

ButtonDataInvalidFilter creates a filter for invalid button data errors

func ChatNotFoundFilter 

func ChatNotFoundFilter() ErrorFilter

ChatNotFoundFilter creates a filter for chat not found errors

func ConflictErrorFilter 

func ConflictErrorFilter() ErrorFilter

ConflictErrorFilter creates a filter for conflict errors (409)

func ErrorCodeFilter 

func ErrorCodeFilter(code int) ErrorFilter

ErrorCodeFilter creates a filter for specific error codes

func ForbiddenErrorFilter 

func ForbiddenErrorFilter() ErrorFilter

ForbiddenErrorFilter creates a filter for forbidden errors (403)

func InvalidFileIDFilter 

func InvalidFileIDFilter() ErrorFilter

InvalidFileIDFilter creates a filter for invalid file_id errors

func MessageCantBeDeletedFilter 

func MessageCantBeDeletedFilter() ErrorFilter

MessageCantBeDeletedFilter creates a filter for message can't be deleted errors

func MessageCantBeEditedFilter 

func MessageCantBeEditedFilter() ErrorFilter

MessageCantBeEditedFilter creates a filter for message can't be edited errors

func MessageNotFoundFilter 

func MessageNotFoundFilter() ErrorFilter

MessageNotFoundFilter creates a filter for message not found errors

func MessageTextEmptyFilter 

func MessageTextEmptyFilter() ErrorFilter

MessageTextEmptyFilter creates a filter for empty message text errors

func MessageTooLongFilter 

func MessageTooLongFilter() ErrorFilter

MessageTooLongFilter creates a filter for message too long errors

func RateLimitErrorFilter 

func RateLimitErrorFilter() ErrorFilter

RateLimitErrorFilter creates a filter for rate limit errors (429)

func ServerErrorFilter 

func ServerErrorFilter() ErrorFilter

ServerErrorFilter creates a filter for server errors (5xx)

func TelegramErrorFilter 

func TelegramErrorFilter() ErrorFilter

TelegramErrorFilter creates a filter for Telegram API errors

func UnauthorizedErrorFilter 

func UnauthorizedErrorFilter() ErrorFilter

UnauthorizedErrorFilter creates a filter for unauthorized errors (401)

type ErrorHandler 

type ErrorHandler struct {
	Filter  ErrorFilter      // Optional filter to match specific errors
	Handler ErrorHandlerFunc // Handler function
}

ErrorHandler represents an error handler with optional filter

type ErrorHandlerFunc 

type ErrorHandlerFunc func(*Bot, *models.Update, error) error

ErrorHandlerFunc represents a function that handles errors

type ErrorHandlerRegistrar 

type ErrorHandlerRegistrar interface {
	OnError(filter ErrorFilter, handler ErrorHandlerFunc)
	OnTelegramError(handler ErrorHandlerFunc)
	OnRateLimitError(handler ErrorHandlerFunc)
	OnBadRequest(handler ErrorHandlerFunc)
	OnForbiddenError(handler ErrorHandlerFunc)
	SetFallbackErrorHandler(handler ErrorHandlerFunc)
}

ErrorHandlerRegistrar is an interface for types that can register error handlers

type ErrorHandlers 

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

ErrorHandlers holds all registered error handlers

func NewErrorHandlers 

func NewErrorHandlers() *ErrorHandlers

NewErrorHandlers creates a new ErrorHandlers instance

func (*ErrorHandlers) AddHandler 

func (eh *ErrorHandlers) AddHandler(filter ErrorFilter, handler ErrorHandlerFunc)

AddHandler adds a new error handler

func (*ErrorHandlers) Process 

func (eh *ErrorHandlers) Process(bot *Bot, update *models.Update, err error) error

Process processes an error through all registered handlers

func (*ErrorHandlers) SetFallbackHandler 

func (eh *ErrorHandlers) SetFallbackHandler(handler ErrorHandlerFunc)

SetFallbackHandler sets a fallback error handler that runs when no other handler matches

type FilterFunc 

type FilterFunc func(*models.Update) bool

FilterFunc represents a function that filters updates

func AndFilter 

func AndFilter(filters ...FilterFunc) FilterFunc

AndFilter combines multiple filters with AND logic

func AudioFilter 

func AudioFilter() FilterFunc

AudioFilter filters audio messages

func CallbackDataFilter 

func CallbackDataFilter(data string) FilterFunc

CallbackDataFilter filters callback queries with specific data

func CallbackDataPrefixFilter 

func CallbackDataPrefixFilter(prefix string) FilterFunc

CallbackDataPrefixFilter filters callback queries with data starting with prefix

func CallbackQueryFilter 

func CallbackQueryFilter() FilterFunc

CallbackQueryFilter filters callback queries

func ChannelChatFilter 

func ChannelChatFilter() FilterFunc

ChannelChatFilter filters channel chat messages

func ChannelPostFilter 

func ChannelPostFilter() FilterFunc

ChannelPostFilter filters channel posts

func ChatTypeFilter 

func ChatTypeFilter(chatType models.ChatType) FilterFunc

ChatTypeFilter filters messages by chat type (private, group, supergroup, channel)

func CommandFilter 

func CommandFilter(command string) FilterFunc

CommandFilter filters commands (messages starting with /)

func ContactFilter 

func ContactFilter() FilterFunc

ContactFilter filters contact messages

func DocumentFilter 

func DocumentFilter() FilterFunc

DocumentFilter filters document messages

func EditedChannelPostFilter 

func EditedChannelPostFilter() FilterFunc

EditedChannelPostFilter filters edited channel posts

func EditedMessageFilter 

func EditedMessageFilter() FilterFunc

EditedMessageFilter filters edited messages

func GroupChatFilter 

func GroupChatFilter() FilterFunc

GroupChatFilter filters group chat messages

func InlineQueryFilter 

func InlineQueryFilter() FilterFunc

InlineQueryFilter filters inline queries

func LocationFilter 

func LocationFilter() FilterFunc

LocationFilter filters location messages

func MessageFilter 

func MessageFilter() FilterFunc

MessageFilter filters messages only

func NotFilter 

func NotFilter(filter FilterFunc) FilterFunc

NotFilter inverts a filter

func OrFilter 

func OrFilter(filters ...FilterFunc) FilterFunc

OrFilter combines multiple filters with OR logic

func PhotoFilter 

func PhotoFilter() FilterFunc

PhotoFilter filters photo messages

func PrivateChatFilter 

func PrivateChatFilter() FilterFunc

PrivateChatFilter filters private chat messages

func StickerFilter 

func StickerFilter() FilterFunc

StickerFilter filters sticker messages

func SupergroupChatFilter 

func SupergroupChatFilter() FilterFunc

SupergroupChatFilter filters supergroup chat messages

func TextContainsFilter 

func TextContainsFilter(substring string) FilterFunc

TextContainsFilter filters text messages containing specific text

func TextFilter 

func TextFilter() FilterFunc

TextFilter filters text messages (non-command)

func VideoFilter 

func VideoFilter() FilterFunc

VideoFilter filters video messages

func VoiceFilter 

func VoiceFilter() FilterFunc

VoiceFilter filters voice messages

type Handler 

type Handler struct {
	Filter      FilterFunc
	Handler     HandlerFunc
	Middlewares []MiddlewareFunc
	StateFilter *state.Filter // Optional state filter
}

Handler represents a handler with its filter and handler function

type HandlerFunc 

type HandlerFunc func(*Bot, *models.Update, *Context) error

HandlerFunc represents a function that handles an update

type HandlerGroup 

type HandlerGroup struct {
	*RegisterCommands
	// contains filtered or unexported fields
}

HandlerGroup represents a group of related handlers

func NewHandlerGroup 

func NewHandlerGroup(name string) *HandlerGroup

NewHandlerGroup creates a new handler group

func (*HandlerGroup) AddHandler 

func (g *HandlerGroup) AddHandler(filter FilterFunc, handler HandlerFunc, opts ...interface{})

AddHandler adds a custom handler with a filter to the group

func (*HandlerGroup) Handlers 

func (g *HandlerGroup) Handlers() []Handler

Handlers returns all handlers in this group

func (*HandlerGroup) Name 

func (g *HandlerGroup) Name() string

Name returns the name of this group

func (*HandlerGroup) UseMiddleware 

func (g *HandlerGroup) UseMiddleware(middlewares ...MiddlewareFunc) *HandlerGroup

UseMiddleware adds middleware(s) to this group All handlers in this group will use these middlewares

func (*HandlerGroup) WithFilter 

func (g *HandlerGroup) WithFilter(filter FilterFunc) *HandlerGroup

WithFilter sets a filter for all handlers in this group

type HandlerRegistrar 

type HandlerRegistrar interface {
	AddHandler(filter FilterFunc, handler HandlerFunc, opts ...interface{})
}

HandlerRegistrar is an interface for types that can register handlers

type Handlers 

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

Handlers holds all registered handlers

func NewHandlers 

func NewHandlers() *Handlers

NewHandlers creates a new Handlers instance

func (*Handlers) AddHandler 

func (h *Handlers) AddHandler(filter FilterFunc, handler HandlerFunc, middlewares ...MiddlewareFunc)

AddHandler adds a new handler

func (*Handlers) AddHandlerWithState 

func (h *Handlers) AddHandlerWithState(filter FilterFunc, stateFilter *state.Filter, handler HandlerFunc, middlewares ...MiddlewareFunc)

AddHandlerWithState adds a new handler with state filter

func (*Handlers) Process 

func (h *Handlers) Process(bot *Bot, update *models.Update)

Process processes an update through all handlers

type MiddlewareChain 

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

MiddlewareChain manages a chain of middlewares

func NewMiddlewareChain 

func NewMiddlewareChain(handler HandlerFunc, middlewares ...MiddlewareFunc) *MiddlewareChain

NewMiddlewareChain creates a new middleware chain

func NewMiddlewareChainWithContext added in v0.2.0 

func NewMiddlewareChainWithContext(handler HandlerFunc, ctx *Context, middlewares ...MiddlewareFunc) *MiddlewareChain

NewMiddlewareChainWithContext creates a new middleware chain with a pre-populated context

func (*MiddlewareChain) Execute 

func (mc *MiddlewareChain) Execute(bot *Bot, update *models.Update) error

Execute executes the middleware chain

type MiddlewareFunc 

type MiddlewareFunc func(*Bot, *models.Update, *Context, NextFunc)

MiddlewareFunc represents a middleware function It receives the bot, update, context, and a next function Call next() to continue to the next middleware or handler Return without calling next() to stop the chain

type NextFunc 

type NextFunc func()

NextFunc is the function to call the next middleware or handler in the chain

type PollingOptions 

type PollingOptions struct {
	Timeout        int         // Timeout in seconds for long polling (default: 30)
	Limit          int         // Maximum number of updates to retrieve (default: 100)
	AllowedUpdates []string    // List of update types to receive (default: all)
	Async          bool        // Process updates asynchronously in goroutines (default: true)
	RetryDelay     int         // Delay in seconds before retrying after error (default: 3)
	OnStart        func()      // Callback when polling starts
	OnError        func(error) // Callback when error occurs
}

PollingOptions represents configuration options for polling

type RegisterCommands 

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

RegisterCommands provides convenience methods for registering handlers

func NewRegisterCommands 

func NewRegisterCommands(registrar HandlerRegistrar) *RegisterCommands

NewRegisterCommands creates a new RegisterCommands instance

func (*RegisterCommands) OnAudio 

func (r *RegisterCommands) OnAudio(handler HandlerFunc, opts ...interface{})

OnAudio registers a handler for audio messages

func (*RegisterCommands) OnCallbackData 

func (r *RegisterCommands) OnCallbackData(data string, handler HandlerFunc, opts ...interface{})

OnCallbackData registers a handler for callback queries with specific data

func (*RegisterCommands) OnCallbackDataModel added in v0.2.0 

func (r *RegisterCommands) OnCallbackDataModel(data *CallbackData, handler HandlerFunc, opts ...interface{})

OnCallbackDataModel registers a handler for callback queries matching a CallbackData definition

func (*RegisterCommands) OnCallbackDataPrefix 

func (r *RegisterCommands) OnCallbackDataPrefix(prefix string, handler HandlerFunc, opts ...interface{})

OnCallbackDataPrefix registers a handler for callback queries with data starting with prefix

func (*RegisterCommands) OnCallbackQuery 

func (r *RegisterCommands) OnCallbackQuery(handler HandlerFunc, opts ...interface{})

OnCallbackQuery registers a handler for all callback queries

func (*RegisterCommands) OnCallbackStruct added in v0.2.0 

func (r *RegisterCommands) OnCallbackStruct(model interface{}, handler HandlerFunc, opts ...interface{})

OnCallbackStruct registers a handler for callback queries based on a struct model. The model must embed tools.CallbackData.

Non-zero exported fields in model act as a filter pattern. This allows using the same callback struct type across multiple handlers.

Parsed payload is stored in context and can be retrieved with:

  • ctx.LoadCallbackData(&payload)
  • GetCallbackStruct[T](ctx)

func (*RegisterCommands) OnChannelPost 

func (r *RegisterCommands) OnChannelPost(handler HandlerFunc, opts ...interface{})

OnChannelPost registers a handler for channel posts

func (*RegisterCommands) OnCommand 

func (r *RegisterCommands) OnCommand(command string, handler HandlerFunc, opts ...interface{})

OnCommand registers a handler for a specific command

func (*RegisterCommands) OnContact 

func (r *RegisterCommands) OnContact(handler HandlerFunc, opts ...interface{})

OnContact registers a handler for contact messages

func (*RegisterCommands) OnDocument 

func (r *RegisterCommands) OnDocument(handler HandlerFunc, opts ...interface{})

OnDocument registers a handler for document messages

func (*RegisterCommands) OnEditedMessage 

func (r *RegisterCommands) OnEditedMessage(handler HandlerFunc, opts ...interface{})

OnEditedMessage registers a handler for edited messages

func (*RegisterCommands) OnInlineQuery 

func (r *RegisterCommands) OnInlineQuery(handler HandlerFunc, opts ...interface{})

OnInlineQuery registers a handler for inline queries

func (*RegisterCommands) OnLocation 

func (r *RegisterCommands) OnLocation(handler HandlerFunc, opts ...interface{})

OnLocation registers a handler for location messages

func (*RegisterCommands) OnMessage 

func (r *RegisterCommands) OnMessage(handler HandlerFunc, opts ...interface{})

OnMessage registers a handler for all messages

func (*RegisterCommands) OnPhoto 

func (r *RegisterCommands) OnPhoto(handler HandlerFunc, opts ...interface{})

OnPhoto registers a handler for photo messages

func (*RegisterCommands) OnSticker 

func (r *RegisterCommands) OnSticker(handler HandlerFunc, opts ...interface{})

OnSticker registers a handler for sticker messages

func (*RegisterCommands) OnText 

func (r *RegisterCommands) OnText(handler HandlerFunc, opts ...interface{})

OnText registers a handler for text messages (non-command)

func (*RegisterCommands) OnVideo 

func (r *RegisterCommands) OnVideo(handler HandlerFunc, opts ...interface{})

OnVideo registers a handler for video messages

func (*RegisterCommands) OnVoice 

func (r *RegisterCommands) OnVoice(handler HandlerFunc, opts ...interface{})

OnVoice registers a handler for voice messages

type ResponseParameters 

type ResponseParameters struct {
	MigrateToChatID int64 // The group has been migrated to a supergroup with the specified identifier
	RetryAfter      int   // In case of exceeding flood control, the number of seconds left to wait
}

ResponseParameters contains information about why a request was unsuccessful

type TelegramError 

type TelegramError struct {
	ErrorCode   int
	Description string
	Parameters  *ResponseParameters
	Update      *models.Update
}

TelegramError represents an error from the Telegram Bot API

func NewTelegramError 

func NewTelegramError(code int, description string, update *models.Update) *TelegramError

NewTelegramError creates a new TelegramError

func NewTelegramErrorWithParams 

func NewTelegramErrorWithParams(code int, description string, params *ResponseParameters, update *models.Update) *TelegramError

NewTelegramErrorWithParams creates a new TelegramError with ResponseParameters

func (*TelegramError) Error 

func (e *TelegramError) Error() string

Error implements the error interface for TelegramError

func (*TelegramError) IsBadRequest 

func (e *TelegramError) IsBadRequest() bool

IsBadRequest checks if the error is a bad request (400)

func (*TelegramError) IsBotKicked 

func (e *TelegramError) IsBotKicked() bool

IsBotKicked checks if the bot was kicked from chat

func (*TelegramError) IsBotWasBlocked 

func (e *TelegramError) IsBotWasBlocked() bool

IsBotWasBlocked checks if the bot was blocked by user

func (*TelegramError) IsButtonDataInvalid 

func (e *TelegramError) IsButtonDataInvalid() bool

IsButtonDataInvalid checks if callback data is invalid

func (*TelegramError) IsChatNotFound 

func (e *TelegramError) IsChatNotFound() bool

IsChatNotFound checks if error is about chat not being found

func (*TelegramError) IsConflict 

func (e *TelegramError) IsConflict() bool

IsConflict checks if the error is a conflict error (409)

func (*TelegramError) IsForbidden 

func (e *TelegramError) IsForbidden() bool

IsForbidden checks if the error is a forbidden error (403)

func (*TelegramError) IsInvalidFileID 

func (e *TelegramError) IsInvalidFileID() bool

IsInvalidFileID checks if the file_id is invalid

func (*TelegramError) IsMessageCantBeDeleted 

func (e *TelegramError) IsMessageCantBeDeleted() bool

IsMessageCantBeDeleted checks if error is about message that can't be deleted

func (*TelegramError) IsMessageCantBeEdited 

func (e *TelegramError) IsMessageCantBeEdited() bool

IsMessageCantBeEdited checks if error is about message that can't be edited

func (*TelegramError) IsMessageNotFound 

func (e *TelegramError) IsMessageNotFound() bool

IsMessageNotFound checks if error is about message not being found

func (*TelegramError) IsMessageTextEmpty 

func (e *TelegramError) IsMessageTextEmpty() bool

Message-specific error checks IsMessageTextEmpty checks if error is about empty message text

func (*TelegramError) IsMessageTooLong 

func (e *TelegramError) IsMessageTooLong() bool

IsMessageTooLong checks if error is about message being too long

func (*TelegramError) IsNotFound 

func (e *TelegramError) IsNotFound() bool

IsNotFound checks if the error is a not found error (404)

func (*TelegramError) IsRateLimitError 

func (e *TelegramError) IsRateLimitError() bool

IsRateLimitError checks if the error is a rate limit error (429)

func (*TelegramError) IsServerError 

func (e *TelegramError) IsServerError() bool

IsServerError checks if the error is a server error (5xx)

func (*TelegramError) IsUnauthorized 

func (e *TelegramError) IsUnauthorized() bool

IsUnauthorized checks if the error is an unauthorized error (401)

Source Files

View all Source files

Directories

Path Synopsis

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.