Documentation
¶
Overview ¶
Package tbb provides a base for creating custom Telegram bots. It can be used to spin up a custom bot in one minute which is capable of handling bot users via an implemented sqlite database, but can easily be switched to use mysql or postgres instead.
Index ¶
- Constants
- func BuildInlineKeyboardButtonRow(buttons []InlineKeyboardButton) []echotron.InlineKeyboardButton
- func GetLogLevel(level string) slog.Level
- func GetUserFromUpdate(u *echotron.Update) echotron.User
- func PrintAsJson(v any, indent bool) string
- type App
- func (a *App) API() echotron.API
- func (a *App) DB() *DB
- func (a *App) DeleteBotCommands() error
- func (a *App) GetCurrentTimeOffset(lat, lon float64) int
- func (a *App) GetTimezoneInfo(lat, lon float64) *TZInfo
- func (a *App) SetBotCommands(bc []echotron.BotCommand) error
- func (a *App) Start()
- func (a *App) StartWithWebhook(webhookURL string)
- type AppOption
- type Bot
- func (b *Bot) API() echotron.API
- func (b *Bot) App() *App
- func (b *Bot) ChatID() int64
- func (b *Bot) Command() *Command
- func (b *Bot) DB() *DB
- func (b *Bot) DeleteMessage(q *echotron.CallbackQuery)
- func (b *Bot) DisableUser()
- func (b *Bot) EnableUser()
- func (b *Bot) GetUsernameFromMessage(m *echotron.Message) string
- func (b *Bot) GetUsersTimezoneOffset() (int, error)
- func (b *Bot) IsUserActive() bool
- func (b *Bot) Log() *slog.Logger
- func (b *Bot) ReplaceMessage(q *echotron.CallbackQuery, text string, ...)
- func (b *Bot) Update(u *echotron.Update)
- func (b *Bot) User() *User
- type BotOption
- type Command
- type CommandFunc
- type CommandHandler
- type CommandRegistry
- type Config
- type DB
- type DefaultCommandHandler
- type DefaultUpdateHandler
- func (d *DefaultUpdateHandler) Bot() *Bot
- func (d *DefaultUpdateHandler) HandleCallbackQuery(c echotron.CallbackQuery) StateFn
- func (d *DefaultUpdateHandler) HandleChannelPost(m echotron.Message) StateFn
- func (d *DefaultUpdateHandler) HandleChatJoinRequest(c echotron.ChatJoinRequest) StateFn
- func (d *DefaultUpdateHandler) HandleChatMember(c echotron.ChatMemberUpdated) StateFn
- func (d *DefaultUpdateHandler) HandleChosenInlineResult(c echotron.ChosenInlineResult) StateFn
- func (d *DefaultUpdateHandler) HandleEditedChannelPost(m echotron.Message) StateFn
- func (d *DefaultUpdateHandler) HandleEditedMessage(m echotron.Message) StateFn
- func (d *DefaultUpdateHandler) HandleInlineQuery(i echotron.InlineQuery) StateFn
- func (d *DefaultUpdateHandler) HandleMessage(m echotron.Message) StateFn
- func (d *DefaultUpdateHandler) HandleMyChatMember(c echotron.ChatMemberUpdated) StateFn
- func (d *DefaultUpdateHandler) HandlePreCheckoutQuery(p echotron.PreCheckoutQuery) StateFn
- func (d *DefaultUpdateHandler) HandleShippingQuery(s echotron.ShippingQuery) StateFn
- func (d *DefaultUpdateHandler) SetBot(bot *Bot)
- type InlineKeyboardButton
- type StateFn
- type TZInfo
- type UpdateHandler
- type UpdateHandlerFn
- type User
- type UserInfo
- type UserPhoto
Constants ¶
const ( DB_TYPE_SQLITE = "sqlite" DB_TYPE_MYSQL = "mysql" DB_TYPE_POSTGRES = "postgres" )
Variables ¶
This section is empty.
Functions ¶
func BuildInlineKeyboardButtonRow ¶
func BuildInlineKeyboardButtonRow(buttons []InlineKeyboardButton) []echotron.InlineKeyboardButton
BuildInlineKeyboardButtonRow helper function for creating Telegram inline keyboards
func GetLogLevel ¶
GetLogLevel converts string log levels to slog.Level representation. Can be one of "debug", "info", "warn" or "error".
func GetUserFromUpdate ¶
GetUserFromUpdate returns the echotron.User from a given echotron.Update
func PrintAsJson ¶
PrintAsJson returns the JSON representation of a given go struct.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
func NewApp ¶
NewApp creates a new Telegram bot based on the given configuration. It uses functional options for configuration.
func (*App) DB ¶
DB returns the database handle for the bot, so that the database can easily be adjusted and extended.
func (*App) DeleteBotCommands ¶
DeleteBotCommands removes the registered Telegram commands from your bot.
func (*App) GetCurrentTimeOffset ¶
GetCurrentTimeOffset returns the time offset in seconds for the given coordinates
func (*App) GetTimezoneInfo ¶
GetTimezoneInfo returns the time zone info for the given coordinates if available.
func (*App) SetBotCommands ¶
func (a *App) SetBotCommands(bc []echotron.BotCommand) error
SetBotCommands registers the given command list for your Telegram bot.
func (*App) StartWithWebhook ¶
StartWithWebhook starts the Telegram bot server with a given webhook url.
type AppOption ¶
type AppOption func(*App)
func WithCommands ¶
WithCommands is used for providing and registering custom bot commands. Bot commands always start with a / like /start and a Handler, which implements the CommandHandler interface. If you want a command to be available in the command list on Telegram, the provided Command must contain a Description.
func WithConfig ¶
WithConfig is the only required option, because it provides the config for the app to function properly.
func WithHandlerFunc ¶
func WithHandlerFunc(hFn UpdateHandlerFn) AppOption
WithHandlerFunc option can be used to override the default UpdateHandlerFn for custom echotron.Update message handling.
func WithLogger ¶
WithLogger option can be used to override the default logger with a custom one.
type Bot ¶
type Bot struct {
// contains filtered or unexported fields
}
func (*Bot) DeleteMessage ¶
func (b *Bot) DeleteMessage(q *echotron.CallbackQuery)
DeleteMessage deletes the given CallbackQuery message
func (*Bot) DisableUser ¶
func (b *Bot) DisableUser()
DisableUser disable current user and updates the database
func (*Bot) EnableUser ¶
func (b *Bot) EnableUser()
EnableUser enables current user and updates the database
func (*Bot) GetUsernameFromMessage ¶
GetUsernameFromMessage returns the Firstname or Username from the telegram user of the given message
func (*Bot) GetUsersTimezoneOffset ¶
GetUsersTimezoneOffset returns the time zone offset in seconds if the user has already provided coordinates. This can be used, for example, to calculate the current time of the user.
func (*Bot) IsUserActive ¶
func (*Bot) ReplaceMessage ¶
func (b *Bot) ReplaceMessage(q *echotron.CallbackQuery, text string, buttons [][]echotron.InlineKeyboardButton)
ReplaceMessage replaces the given CallbackQuery message with new Text and Keyboard
type Command ¶
type Command struct {
Name string
Description string
Params []string
Data any
Handler CommandHandler
}
type CommandHandler ¶
type CommandRegistry ¶
type Config ¶
type Config struct {
Admin struct {
BotToken string `yaml:"botToken"`
ChatID int64 `yaml:"chatID"`
} `yaml:"admin"`
Database struct {
Type string `yaml:"type"` // one of sqlite, mysql, postgres
DSN string `yaml:"dsn"` // in case of mysql or postgres
Filename string `yaml:"filename"` // in case of sqlite
} `yaml:"database"`
Debug bool `yaml:"debug"`
BotSessionTimeout int `yaml:"botSessionTimeout"` // Timeout in minutes after which the bot instance will be deleted in order to save memory. Defaults to 15 minutes.
LogLevel string `yaml:"logLevel"`
Telegram struct {
BotToken string `yaml:"botToken"`
} `yaml:"telegram"`
}
func LoadConfig ¶
type DefaultCommandHandler ¶
type DefaultCommandHandler struct {
Bot *Bot
}
func (*DefaultCommandHandler) Handle ¶
func (h *DefaultCommandHandler) Handle(bot *Bot) StateFn
type DefaultUpdateHandler ¶
type DefaultUpdateHandler struct {
// contains filtered or unexported fields
}
DefaultUpdateHandler implements the UpdateHandler interface
func (*DefaultUpdateHandler) Bot ¶
func (d *DefaultUpdateHandler) Bot() *Bot
func (*DefaultUpdateHandler) HandleCallbackQuery ¶
func (d *DefaultUpdateHandler) HandleCallbackQuery(c echotron.CallbackQuery) StateFn
func (*DefaultUpdateHandler) HandleChannelPost ¶
func (d *DefaultUpdateHandler) HandleChannelPost(m echotron.Message) StateFn
func (*DefaultUpdateHandler) HandleChatJoinRequest ¶
func (d *DefaultUpdateHandler) HandleChatJoinRequest(c echotron.ChatJoinRequest) StateFn
func (*DefaultUpdateHandler) HandleChatMember ¶
func (d *DefaultUpdateHandler) HandleChatMember(c echotron.ChatMemberUpdated) StateFn
func (*DefaultUpdateHandler) HandleChosenInlineResult ¶
func (d *DefaultUpdateHandler) HandleChosenInlineResult(c echotron.ChosenInlineResult) StateFn
func (*DefaultUpdateHandler) HandleEditedChannelPost ¶
func (d *DefaultUpdateHandler) HandleEditedChannelPost(m echotron.Message) StateFn
func (*DefaultUpdateHandler) HandleEditedMessage ¶
func (d *DefaultUpdateHandler) HandleEditedMessage(m echotron.Message) StateFn
func (*DefaultUpdateHandler) HandleInlineQuery ¶
func (d *DefaultUpdateHandler) HandleInlineQuery(i echotron.InlineQuery) StateFn
func (*DefaultUpdateHandler) HandleMessage ¶
func (d *DefaultUpdateHandler) HandleMessage(m echotron.Message) StateFn
func (*DefaultUpdateHandler) HandleMyChatMember ¶
func (d *DefaultUpdateHandler) HandleMyChatMember(c echotron.ChatMemberUpdated) StateFn
func (*DefaultUpdateHandler) HandlePreCheckoutQuery ¶
func (d *DefaultUpdateHandler) HandlePreCheckoutQuery(p echotron.PreCheckoutQuery) StateFn
func (*DefaultUpdateHandler) HandleShippingQuery ¶
func (d *DefaultUpdateHandler) HandleShippingQuery(s echotron.ShippingQuery) StateFn
func (*DefaultUpdateHandler) SetBot ¶
func (d *DefaultUpdateHandler) SetBot(bot *Bot)
type InlineKeyboardButton ¶
type UpdateHandler ¶
type UpdateHandler interface {
Bot() *Bot
SetBot(*Bot)
HandleMessage(echotron.Message) StateFn
HandleEditedMessage(echotron.Message) StateFn
HandleChannelPost(echotron.Message) StateFn
HandleEditedChannelPost(echotron.Message) StateFn
HandleInlineQuery(echotron.InlineQuery) StateFn
HandleChosenInlineResult(echotron.ChosenInlineResult) StateFn
HandleCallbackQuery(echotron.CallbackQuery) StateFn
HandleShippingQuery(echotron.ShippingQuery) StateFn
HandlePreCheckoutQuery(echotron.PreCheckoutQuery) StateFn
HandleChatMember(echotron.ChatMemberUpdated) StateFn
HandleMyChatMember(echotron.ChatMemberUpdated) StateFn
HandleChatJoinRequest(echotron.ChatJoinRequest) StateFn
}
type UpdateHandlerFn ¶
type UpdateHandlerFn func() UpdateHandler
type User ¶
type User struct {
ID uint64 `gorm:"primaryKey" json:"-"`
Username string `json:"username"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
IsBot bool `json:"isBot"` // True if user is itself a Bot
ChatID int64 `gorm:"unique" json:"chatID"` // Telegram chatID of the user
LanguageCode string `json:"language_code"` // Language code of the user
IsPremium bool `json:"isPremium"` // True, if this user is a Telegram Premium user
UserInfo *UserInfo `json:"userInfo,omitempty"`
UserPhoto *UserPhoto `json:"-"`
CreatedAt time.Time
UpdatedAt time.Time
}
type UserInfo ¶
type UserInfo struct {
UserID uint64 `gorm:"primaryKey"`
IsActive bool
Status string // Either "member" or "kicked"
Latitude float64 // Latitude the user sends for determining the users current Time zone
Longitude float64 // Longitude the user sends for determining the users current Time zone
Location string // Location of the user's timezone
ZoneName string // Zone name of the user's timezone
TZOffset *int // Time zone offset in seconds
IsDST bool // Whether the TZOffset is in daylight saving time or normal time
CreatedAt time.Time
UpdatedAt time.Time
}
type UserPhoto ¶
type UserPhoto struct {
UserID uint64 `gorm:"primaryKey"` // ID from User table to whom the photo belongs to.
FileID string // Identifier for this file, which can be used to download or reuse the file
FileUniqueID string // Unique identifier for this file, which is supposed to be the same over time and for different bots. Can't be used to download or reuse the file.
FileSize int // Size in bytes of the user photo
FileHash string // The md5 file hash of the user photo
FileData []byte // The binary Data of the user photo
Width int // Photo width
Height int // Photo height
CreatedAt time.Time
UpdatedAt time.Time
}