Skip to main content
The Bot struct is the central object in Telebot. It holds your token, poller, registered handlers, and exposes every method you need to interact with the Telegram Bot API.

Constructor

NewBot

func NewBot(pref Settings) (*Bot, error)
Creates and returns a new Bot instance. It calls getMe to verify the token with Telegram unless Settings.Offline is true.
pref
Settings
required
Configuration for the bot. See Settings for all fields.
Returns (*Bot, error) — a ready-to-use bot, or an error if the token is invalid or the Telegram API is unreachable.
b, err := tele.NewBot(tele.Settings{
    Token:  os.Getenv("TOKEN"),
    Poller: &tele.LongPoller{Timeout: 10 * time.Second},
})
if err != nil {
    log.Fatal(err)
}

Bot Fields

The following fields on *Bot are exported and safe to read after construction.
FieldTypeDescription
Me*UserThe bot’s own Telegram user object, populated by getMe on startup.
TokenstringThe bot API token.
URLstringThe Telegram API base URL (defaults to https://api.telegram.org).
Updateschan UpdateBuffered channel receiving incoming updates from the poller.
PollerPollerThe active update provider.

Lifecycle

b.Start()

func (b *Bot) Start()
Starts the bot by launching the poller and entering the update dispatch loop. This call blocks until b.Stop() is called.
Start panics if b.Poller is nil. Always set a poller in Settings before calling Start.
b.Start() // blocks until Stop() is called

b.Stop()

func (b *Bot) Stop()
Gracefully shuts down the poller and waits for it to finish. Unblocks b.Start().
go b.Start()
// ... later:
b.Stop()

Routing

b.Handle()

func (b *Bot) Handle(endpoint interface{}, h HandlerFunc, m ...MiddlewareFunc)
Registers a handler for a given endpoint. The endpoint can be a slash command string ("/start"), a Telebot event constant (tele.OnText), or any type that implements CallbackEndpoint (e.g. *InlineButton).
endpoint
interface{}
required
A string command/event name or a CallbackEndpoint (e.g. *InlineButton, *Btn).
h
HandlerFunc
required
The handler function with signature func(tele.Context) error.
m
...MiddlewareFunc
Optional per-handler middleware applied only to this route.
// Command
b.Handle("/start", func(c tele.Context) error {
    return c.Reply("Hello!")
})

// Event
b.Handle(tele.OnText, func(c tele.Context) error {
    return c.Send("You said: " + c.Text())
})

// Inline button
var btn tele.InlineButton
b.Handle(&btn, func(c tele.Context) error {
    return c.Respond(&tele.CallbackResponse{Text: "Clicked!"})
}, myMiddleware)
Panics with "telebot: unsupported endpoint" if the endpoint type is not recognized.

b.Use()

func (b *Bot) Use(middleware ...MiddlewareFunc)
Adds one or more middleware functions to the global bot middleware chain. Global middleware runs for every handler.
middleware
...MiddlewareFunc
required
Middleware functions with signature func(HandlerFunc) HandlerFunc.
b.Use(myLogger, myAuthChecker)

b.Group()

func (b *Bot) Group() *Group
Creates and returns a new *Group that shares the bot’s handler registry. Middleware added to a group applies only to handlers registered on that group.
admin := b.Group()
admin.Use(adminOnly)
admin.Handle("/ban", onBan)
admin.Handle("/kick", onKick)

b.Trigger()

func (b *Bot) Trigger(endpoint interface{}, c Context) error
Executes the registered handler for the given endpoint directly, bypassing the update loop. Useful for manual dispatch or testing.
endpoint
interface{}
required
The same endpoint value used in Handle.
c
Context
required
The context to pass to the handler.

Sending Messages

b.Send()

func (b *Bot) Send(to Recipient, what interface{}, opts ...interface{}) (*Message, error)
Sends a message to any Recipient. The what argument can be a plain string or any type implementing the Sendable interface (e.g. *Photo, *Document, *Audio, etc.).
to
Recipient
required
Destination chat. Any type implementing Recipient (*Chat, *User, etc.).
what
interface{}
required
A string for text messages, or a Sendable media object.
opts
...interface{}
Optional send options: *SendOptions, *ReplyMarkup, Option flags (tele.Silent, tele.NoPreview, …), or a ParseMode.
*Message
*Message
The sent message on success.
error
error
ErrBadRecipient if to is nil; a Telegram API error otherwise.
msg, err := b.Send(chat, "Hello, world!")

// With parse mode
msg, err := b.Send(chat, "<b>Bold</b>", tele.ModeHTML)

// Silent with markup
msg, err := b.Send(chat, "Pick one:", tele.Silent, &markup)

// Send a photo
msg, err := b.Send(chat, &tele.Photo{File: tele.FromDisk("img.png")})

b.SendAlbum()

func (b *Bot) SendAlbum(to Recipient, a Album, opts ...interface{}) ([]Message, error)
Sends multiple media items as a single grouped message (media album). Captions should be set on the first Inputtable item. Only tele.Silent is supported from the option set.
to
Recipient
required
Destination chat.
a
Album
required
A slice of Inputtable media items (e.g. []tele.Inputtable{&photo, &video}).
opts
...interface{}
Optional send options (only tele.Silent is applied).
[]Message
[]Message
The sent messages.
album := tele.Album{
    &tele.Photo{File: tele.FromDisk("a.jpg"), Caption: "My album"},
    &tele.Photo{File: tele.FromDisk("b.jpg")},
}
msgs, err := b.SendAlbum(chat, album)

b.SendPaidMedia()

func (b *Bot) SendPaidMedia(to Recipient, stars int, a PaidAlbum, opts ...interface{}) (*Message, error)
Sends multiple paid media items (requiring Telegram Stars) as a single message.
to
Recipient
required
Destination chat.
stars
int
required
Number of Telegram Stars required to view the media.
a
PaidAlbum
required
A slice of PaidInputtable items.
opts
...interface{}
Optional send options.

b.Reply()

func (b *Bot) Reply(to *Message, what interface{}, opts ...interface{}) (*Message, error)
Behaves like Send() but marks the outgoing message as a reply to to. Panics if to is nil.
to
*Message
required
The message to reply to.
what
interface{}
required
Content to send (same as Send).
opts
...interface{}
Optional send options.
b.Handle(tele.OnText, func(c tele.Context) error {
    return b.Reply(c.Message(), "Got it!")
})

b.Forward()

func (b *Bot) Forward(to Recipient, msg Editable, opts ...interface{}) (*Message, error)
Forwards an existing message to a recipient. Supports the tele.Silent option. Panics if msg is nil.
to
Recipient
required
Destination chat.
msg
Editable
required
The message to forward.
opts
...interface{}
Optional: tele.Silent, and optionally an int64 video start timestamp (Bot API 8.3).

b.ForwardMany()

func (b *Bot) ForwardMany(to Recipient, msgs []Editable, opts ...*SendOptions) ([]Message, error)
Forwards multiple messages simultaneously. Skips messages that cannot be found or forwarded. Album grouping is preserved.

b.Copy()

func (b *Bot) Copy(to Recipient, msg Editable, opts ...interface{}) (*Message, error)
Like Forward(), but the copied message does not include a link back to the original. Panics if msg is nil.

b.CopyMany()

func (b *Bot) CopyMany(to Recipient, msgs []Editable, opts ...*SendOptions) ([]Message, error)
Copies multiple messages without a link to the originals. Album grouping is preserved.

Editing Messages

b.Edit()

func (b *Bot) Edit(msg Editable, what interface{}, opts ...interface{}) (*Message, error)
Edits a previously sent message. The what argument determines the edit mode:
  • string → edits the message text (editMessageText)
  • Location → updates a live location (editMessageLiveLocation)
  • *ReplyMarkup → delegates to EditReplyMarkup
  • Inputtable → delegates to EditMedia
If the message was sent by the bot, returns the updated *Message; otherwise returns nil and ErrTrueResult.
msg
Editable
required
The message to edit. Panics if nil.
what
interface{}
required
New content: string, Location, *ReplyMarkup, or Inputtable.
opts
...interface{}
Optional send options (parse mode, entities, etc.).
b.Edit(m, "Updated text")
b.Edit(m, "New <b>bold</b> text", tele.ModeHTML)
b.Edit(m, &tele.ReplyMarkup{}) // clears inline keyboard
b.Edit(m, &tele.Photo{File: tele.FromDisk("new.jpg")})

b.EditCaption()

func (b *Bot) EditCaption(msg Editable, caption string, opts ...interface{}) (*Message, error)
Edits the caption of a media message. Panics if msg is nil.
msg
Editable
required
The media message whose caption to edit.
caption
string
required
New caption text.
opts
...interface{}
Optional: parse mode, entities.

b.EditReplyMarkup()

func (b *Bot) EditReplyMarkup(msg Editable, markup *ReplyMarkup) (*Message, error)
Replaces the inline keyboard of a message. Pass nil or an empty *ReplyMarkup to remove the keyboard entirely.
msg
Editable
required
The message whose reply markup to edit.
markup
*ReplyMarkup
required
New inline keyboard markup. Pass nil to delete.

b.EditMedia()

func (b *Bot) EditMedia(msg Editable, media Inputtable, opts ...interface{}) (*Message, error)
Replaces the media content (photo, video, audio, document, animation) of a message.
msg
Editable
required
The media message to edit.
media
Inputtable
required
The new media item.
b.EditMedia(m, &tele.Photo{File: tele.FromDisk("chicken.jpg")})
b.EditMedia(m, &tele.Video{File: tele.FromURL("http://example.com/v.mp4")})

Deleting Messages

b.Delete()

func (b *Bot) Delete(msg Editable) error
Deletes a message. Panics if msg is nil. Constraints:
  • Messages can only be deleted within 48 hours of sending.
  • Bots can delete their own outgoing messages in private chats, groups, and supergroups.
  • Bots can delete incoming messages in private chats.
  • Admins can delete any message in the groups/channels they manage.
msg
Editable
required
The message to delete.

b.DeleteMany()

func (b *Bot) DeleteMany(msgs []Editable) error
Deletes multiple messages simultaneously. Skips messages that cannot be found.
msgs
[]Editable
required
Messages to delete. All must belong to the same chat.

Chat Actions

b.Notify()

func (b *Bot) Notify(to Recipient, action ChatAction, threadID ...int) error
Broadcasts a typing/upload indicator to the chat. The indicator disappears after 5 seconds or when the bot sends its next message.
to
Recipient
required
The target chat.
action
ChatAction
required
One of the ChatAction constants:
ConstantValue
tele.Typing"typing"
tele.UploadingPhoto"upload_photo"
tele.UploadingVideo"upload_video"
tele.UploadingAudio"upload_audio"
tele.UploadingDocument"upload_document"
tele.UploadingVNote"upload_video_note"
tele.RecordingVideo"record_video"
tele.RecordingAudio"record_audio"
tele.RecordingVNote"record_video_note"
tele.FindingLocation"find_location"
tele.ChoosingSticker"choose_sticker"
threadID
...int
Optional message thread ID for forum supergroups.
b.Notify(chat, tele.Typing)

File Operations

b.FileByID()

func (b *Bot) FileByID(fileID string) (File, error)
Fetches a full File object (including FilePath) from Telegram’s servers using the file’s ID. Telegram-provided File objects usually lack FilePath until this is called.
fileID
string
required
The Telegram file ID.
File
File
Full file object with FilePath populated.

b.File()

func (b *Bot) File(file *File) (io.ReadCloser, error)
Downloads the content of a file from Telegram servers and returns a readable stream. The caller must close the returned io.ReadCloser.
file
*File
required
A file object with a valid FileID. FilePath will be populated on this object after the call.
io.ReadCloser
io.ReadCloser
Open HTTP response body. Must be closed by the caller.

b.Download()

func (b *Bot) Download(file *File, localFilename string) error
Downloads a file from Telegram servers and saves it to disk. Maximum file size is 20 MB. Sets file.FileLocal to localFilename on success.
file
*File
required
File to download. Must have a valid FileID.
localFilename
string
required
Destination path on the local filesystem.
file, _ := b.FileByID(msg.Document.FileID)
err := b.Download(&file, "/tmp/doc.pdf")

Commands

b.SetCommands()

func (b *Bot) SetCommands(opts ...interface{}) error
Updates the bot’s command list shown in the Telegram client. Accepts a combination of []Command, CommandScope, and string (language code).
opts
...interface{}
Any of:
  • []Command — the new command list
  • CommandScope — scope to apply the commands to
  • string — BCP-47 language code (e.g. "en")
err := b.SetCommands([]tele.Command{
    {Text: "start", Description: "Start the bot"},
    {Text: "help",  Description: "Show help"},
})

// Scoped to a specific chat
err = b.SetCommands(
    []tele.Command{{Text: "ban", Description: "Ban a user"}},
    tele.CommandScope{Type: tele.CommandScopeChat, ChatID: adminChatID},
    "en",
)

b.DeleteCommands()

func (b *Bot) DeleteCommands(opts ...interface{}) error
Deletes the bot’s command list for the given scope and language. Accepts the same optional arguments as SetCommands (without []Command).
opts
...interface{}
Optional CommandScope and/or string language code.

b.Commands()

func (b *Bot) Commands(opts ...interface{}) ([]Command, error)
Returns the current list of bot commands for the given scope and language.
opts
...interface{}
Optional CommandScope and/or string language code.
[]Command
[]Command
The list of registered commands.

Polls & Live Locations

b.StopPoll()

func (b *Bot) StopPoll(msg Editable, opts ...interface{}) (*Poll, error)
Stops a poll sent by the bot. Returns the final *Poll object with results. Supports *ReplyMarkup. Panics if msg is nil.

b.StopLiveLocation()

func (b *Bot) StopLiveLocation(msg Editable, opts ...interface{}) (*Message, error)
Stops broadcasting a live location before Location.LivePeriod expires. Supports *ReplyMarkup. Panics if msg is nil.

Chat Management

b.Pin()

func (b *Bot) Pin(msg Editable, opts ...interface{}) error
Pins a message in a supergroup or channel. Supports tele.Silent. Panics if msg is nil.

b.Unpin()

func (b *Bot) Unpin(chat Recipient, messageID ...int) error
Unpins a message (or the most recently pinned message if no messageID is given) in a supergroup or channel.

b.UnpinAll()

func (b *Bot) UnpinAll(chat Recipient) error
Unpins all pinned messages in a supergroup or channel.

b.Leave()

func (b *Bot) Leave(chat Recipient) error
Makes the bot leave a group, supergroup, or channel.

b.ChatByID()

func (b *Bot) ChatByID(id int64) (*Chat, error)
Fetches chat info by numeric ID.

b.ChatByUsername()

func (b *Bot) ChatByUsername(name string) (*Chat, error)
Fetches chat info by @username or numeric ID string.

b.ChatFullInfo()

func (b *Bot) ChatFullInfo(chat Recipient) (*ChatFullInfo, error)
Fetches full information about a chat using getChat.

b.ChatMemberOf()

func (b *Bot) ChatMemberOf(chat, user Recipient) (*ChatMember, error)
Returns information about a specific member of a chat.

b.ProfilePhotosOf()

func (b *Bot) ProfilePhotosOf(user *User) ([]Photo, error)
Returns the list of profile photos for a user.
func (b *Bot) InviteLink(chat *Chat) (string, error)
Exports the primary invite link for a chat. Returns the invite link URL.
func (b *Bot) CreateInviteLink(chat Recipient, link *ChatInviteLink) (*ChatInviteLink, error)
Creates an additional invite link for a chat. The link parameter can specify a Name, ExpireUnixtime, MemberLimit, or JoinRequest flag.
func (b *Bot) EditInviteLink(chat Recipient, link *ChatInviteLink) (*ChatInviteLink, error)
Edits a non-primary invite link created by the bot.
func (b *Bot) RevokeInviteLink(chat Recipient, link string) (*ChatInviteLink, error)
Revokes an invite link created by the bot. The revoked link can no longer be used.

b.ApproveJoinRequest()

func (b *Bot) ApproveJoinRequest(chat Recipient, user *User) error
Approves a pending join request (requires OnChatJoinRequest handler).

b.DeclineJoinRequest()

func (b *Bot) DeclineJoinRequest(chat Recipient, user *User) error
Declines a pending join request.

Callbacks & Queries

b.Respond()

func (b *Bot) Respond(c *Callback, resp ...*CallbackResponse) error
Answers a callback query. A callback can only be answered once; subsequent attempts will return an error.
c
*Callback
required
The callback to respond to.
resp
...*CallbackResponse
Optional response parameters. Defaults to an empty acknowledgment.
b.Handle(tele.OnCallback, func(c tele.Context) error {
    return b.Respond(c.Callback(), &tele.CallbackResponse{
        Text:      "Done!",
        ShowAlert: true,
    })
})

b.Answer()

func (b *Bot) Answer(query *Query, resp *QueryResponse) error
Responds to an inline query with a list of results. Each query can only be answered once.

b.AnswerWebApp()

func (b *Bot) AnswerWebApp(query *Query, r Result) (*WebAppMessage, error)
Sends a response to a query originating from a Web App. Returns information about the sent inline message.

Payments

b.Ship()

func (b *Bot) Ship(query *ShippingQuery, what ...interface{}) error
Answers a shipping query. Pass nothing or shipping options for success; pass a string to indicate an error.
b.Ship(query)                    // OK, no shipping options
b.Ship(query, opt1, opt2)        // OK with options
b.Ship(query, "Address invalid") // Error response

b.Accept()

func (b *Bot) Accept(query *PreCheckoutQuery, errorMessage ...string) error
Finalizes a pre-checkout query. Pass no arguments to confirm, or pass an error message string to reject.

b.StarTransactions()

func (b *Bot) StarTransactions(offset, limit int) ([]StarTransaction, error)
Returns Telegram Star transactions for the bot.

Admin Methods

These methods require the bot to have appropriate administrator rights.

b.Ban()

func (b *Bot) Ban(chat *Chat, member *ChatMember, revokeMessages ...bool) error
Bans a user from a chat until member.RestrictedUntil. Pass revokeMessages: true to also delete all messages sent by the user in the chat.
chat
*Chat
required
The chat to ban the user from.
member
*ChatMember
required
The member to ban. Uses member.RestrictedUntil as the ban expiry Unix timestamp. Use tele.Forever() for a permanent ban.
revokeMessages
...bool
If true, deletes all messages from this user in the chat.
member := &tele.ChatMember{
    User:            targetUser,
    RestrictedUntil: tele.Forever(),
}
b.Ban(chat, member)

b.Unban()

func (b *Bot) Unban(chat *Chat, user *User, forBanned ...bool) error
Unbans a user. By default, kicks non-banned users to ensure they are not chat members but can still rejoin. Pass forBanned: true to only act on actually banned users.
chat
*Chat
required
The chat to unban from.
user
*User
required
The user to unban.
forBanned
...bool
If true, only unbans users that are currently banned (ignores others).

b.Restrict()

func (b *Bot) Restrict(chat *Chat, member *ChatMember) error
Restricts a member’s permissions until member.RestrictedUntil. Use tele.NoRestrictions() to lift all restrictions.
chat
*Chat
required
The target chat.
member
*ChatMember
required
Member with updated Rights and RestrictedUntil set. Set Rights.Independent = true to use independent permission evaluation.
member.Rights = tele.NoRestrictions()
b.Restrict(chat, member)

b.Promote()

func (b *Bot) Promote(chat *Chat, member *ChatMember) error
Updates a member’s administrator privileges. Use tele.AdminRights() to grant full admin access, or tele.NoRights() to demote.
chat
*Chat
required
The target chat.
member
*ChatMember
required
Member with the desired Rights and optionally Anonymous: true.
member.Rights = tele.AdminRights()
b.Promote(chat, member)

b.AdminsOf()

func (b *Bot) AdminsOf(chat *Chat) ([]ChatMember, error)
Returns all administrators of a chat (excluding other bots). If no admins were appointed in a group, only the creator is returned.

b.Len()

func (b *Bot) Len(chat *Chat) (int, error)
Returns the number of members in the chat.

b.SetAdminTitle()

func (b *Bot) SetAdminTitle(chat *Chat, user *User, title string) error
Sets a custom title for an administrator. The title must be 0–16 characters, no emoji.

b.BanSenderChat()

func (b *Bot) BanSenderChat(chat *Chat, sender Recipient) error
Bans a channel from posting in a supergroup or channel. The owner of the banned channel will not be able to send messages on behalf of any of their channels.

b.UnbanSenderChat()

func (b *Bot) UnbanSenderChat(chat *Chat, sender Recipient) error
Unbans a previously banned sender chat.

b.DefaultRights()

func (b *Bot) DefaultRights(forChannels bool) (*Rights, error)
Returns the bot’s current default administrator rights.
forChannels
bool
required
If true, returns rights for channels; otherwise for groups.

b.SetDefaultRights()

func (b *Bot) SetDefaultRights(rights Rights, forChannels bool) error
Updates the bot’s default administrator rights for groups or channels.

b.MenuButton()

func (b *Bot) MenuButton(chat *User) (*MenuButton, error)
Returns the current menu button for a private chat, or the default menu button if not set.

b.SetMenuButton()

func (b *Bot) SetMenuButton(chat *User, mb interface{}) error
Changes the bot’s menu button. Accepts a MenuButtonType for simple buttons or a full *MenuButton struct for Web App buttons. Pass nil for chat to set the default.

Bot Identity

b.SetMyName()

func (b *Bot) SetMyName(name, language string) error
Changes the bot’s display name for the given language code.

b.MyName()

func (b *Bot) MyName(language string) (*BotInfo, error)
Returns the bot’s current name for the given language.

b.SetMyDescription()

func (b *Bot) SetMyDescription(desc, language string) error
Changes the bot’s description (shown in empty chats) for the given language.

b.MyDescription()

func (b *Bot) MyDescription(language string) (*BotInfo, error)
Returns the bot’s current description for the given language.

b.SetMyShortDescription()

func (b *Bot) SetMyShortDescription(desc, language string) error
Changes the bot’s short description (shown on the profile page) for the given language.

b.MyShortDescription()

func (b *Bot) MyShortDescription(language string) (*BotInfo, error)
Returns the bot’s current short description for the given language.

Server Control

b.Logout()

func (b *Bot) Logout() (bool, error)
Logs the bot out of the cloud Bot API server. Use before switching to a local server.

b.Close()

func (b *Bot) Close() (bool, error)
Closes the bot instance. Use before moving the bot from one local server to another.

Manual Processing

b.ProcessUpdate()

func (b *Bot) ProcessUpdate(u Update)
Processes a single Update by creating a context and dispatching it through the registered handlers. Useful for webhook or custom poller implementations where you feed updates manually.
u
Update
required
The incoming update to process.
// In a webhook handler:
var u tele.Update
json.NewDecoder(r.Body).Decode(&u)
b.ProcessUpdate(u)

b.NewContext()

func (b *Bot) NewContext(u Update) Context
Creates a new Context wrapping the given Update. Useful when implementing custom pollers or testing handlers directly.

Error Handling

b.OnError()

func (b *Bot) OnError(err error, c Context)
Invokes the configured error handler (Settings.OnError). Called automatically when a handler returns an error. c may be nil for non-handler errors. The default implementation logs to log.Println. Override it via Settings.OnError:
tele.Settings{
    OnError: func(err error, c tele.Context) {
        log.Printf("[%d] handler error: %v", c.Update().ID, err)
    },
}

Miscellaneous

b.SetUserEmojiStatus()

func (b *Bot) SetUserEmojiStatus(user Recipient, emojiStatusCustomEmojiID string, expirationDate ...int64) error
Changes the emoji status for a user who previously granted the bot permission to manage their emoji status via a Mini App.

b.NewMarkup()

func (b *Bot) NewMarkup() *ReplyMarkup
Returns a new, empty *ReplyMarkup instance.

b.Raw()

See bot_raw.go. Sends a raw request to the Telegram Bot API by method name and returns the raw JSON response body.

Build docs developers (and LLMs) love