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
Bot instance. It calls getMe to verify the token with Telegram unless Settings.Offline is true.
Returns (*Bot, error) — a ready-to-use bot, or an error if the token is invalid or the Telegram API is unreachable.
Bot Fields
The following fields on*Bot are exported and safe to read after construction.
| Field | Type | Description |
|---|---|---|
Me | *User | The bot’s own Telegram user object, populated by getMe on startup. |
Token | string | The bot API token. |
URL | string | The Telegram API base URL (defaults to https://api.telegram.org). |
Updates | chan Update | Buffered channel receiving incoming updates from the poller. |
Poller | Poller | The active update provider. |
Lifecycle
b.Start()
b.Stop() is called.
Start panics if b.Poller is nil. Always set a poller in Settings before calling Start.b.Stop()
b.Start().
Routing
b.Handle()
"/start"), a Telebot event constant (tele.OnText), or any type that implements CallbackEndpoint (e.g. *InlineButton).
A
string command/event name or a CallbackEndpoint (e.g. *InlineButton, *Btn).The handler function with signature
func(tele.Context) error.Optional per-handler middleware applied only to this route.
Panics with
"telebot: unsupported endpoint" if the endpoint type is not recognized.b.Use()
Middleware functions with signature
func(HandlerFunc) HandlerFunc.b.Group()
*Group that shares the bot’s handler registry. Middleware added to a group applies only to handlers registered on that group.
b.Trigger()
The same endpoint value used in
Handle.The context to pass to the handler.
Sending Messages
b.Send()
Recipient. The what argument can be a plain string or any type implementing the Sendable interface (e.g. *Photo, *Document, *Audio, etc.).
Destination chat. Any type implementing
Recipient (*Chat, *User, etc.).A
string for text messages, or a Sendable media object.Optional send options:
*SendOptions, *ReplyMarkup, Option flags (tele.Silent, tele.NoPreview, …), or a ParseMode.The sent message on success.
ErrBadRecipient if to is nil; a Telegram API error otherwise.b.SendAlbum()
Inputtable item. Only tele.Silent is supported from the option set.
Destination chat.
A slice of
Inputtable media items (e.g. []tele.Inputtable{&photo, &video}).Optional send options (only
tele.Silent is applied).The sent messages.
b.SendPaidMedia()
Destination chat.
Number of Telegram Stars required to view the media.
A slice of
PaidInputtable items.Optional send options.
b.Reply()
Send() but marks the outgoing message as a reply to to. Panics if to is nil.
The message to reply to.
Content to send (same as
Send).Optional send options.
b.Forward()
tele.Silent option. Panics if msg is nil.
Destination chat.
The message to forward.
Optional:
tele.Silent, and optionally an int64 video start timestamp (Bot API 8.3).b.ForwardMany()
b.Copy()
Forward(), but the copied message does not include a link back to the original. Panics if msg is nil.
b.CopyMany()
Editing Messages
b.Edit()
what argument determines the edit mode:
string→ edits the message text (editMessageText)Location→ updates a live location (editMessageLiveLocation)*ReplyMarkup→ delegates toEditReplyMarkupInputtable→ delegates toEditMedia
*Message; otherwise returns nil and ErrTrueResult.
The message to edit. Panics if nil.
New content:
string, Location, *ReplyMarkup, or Inputtable.Optional send options (parse mode, entities, etc.).
b.EditCaption()
msg is nil.
The media message whose caption to edit.
New caption text.
Optional: parse mode, entities.
b.EditReplyMarkup()
nil or an empty *ReplyMarkup to remove the keyboard entirely.
The message whose reply markup to edit.
New inline keyboard markup. Pass
nil to delete.b.EditMedia()
The media message to edit.
The new media item.
Deleting Messages
b.Delete()
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.
The message to delete.
b.DeleteMany()
Messages to delete. All must belong to the same chat.
Chat Actions
b.Notify()
The target chat.
One of the
ChatAction constants:| Constant | Value |
|---|---|
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" |
Optional message thread ID for forum supergroups.
File Operations
b.FileByID()
File object (including FilePath) from Telegram’s servers using the file’s ID. Telegram-provided File objects usually lack FilePath until this is called.
The Telegram file ID.
Full file object with
FilePath populated.b.File()
io.ReadCloser.
A file object with a valid
FileID. FilePath will be populated on this object after the call.Open HTTP response body. Must be closed by the caller.
b.Download()
file.FileLocal to localFilename on success.
File to download. Must have a valid
FileID.Destination path on the local filesystem.
Commands
b.SetCommands()
[]Command, CommandScope, and string (language code).
Any of:
[]Command— the new command listCommandScope— scope to apply the commands tostring— BCP-47 language code (e.g."en")
b.DeleteCommands()
SetCommands (without []Command).
Optional
CommandScope and/or string language code.b.Commands()
Optional
CommandScope and/or string language code.The list of registered commands.
Polls & Live Locations
b.StopPoll()
*Poll object with results. Supports *ReplyMarkup. Panics if msg is nil.
b.StopLiveLocation()
Location.LivePeriod expires. Supports *ReplyMarkup. Panics if msg is nil.
Chat Management
b.Pin()
tele.Silent. Panics if msg is nil.
b.Unpin()
messageID is given) in a supergroup or channel.
b.UnpinAll()
b.Leave()
b.ChatByID()
b.ChatByUsername()
@username or numeric ID string.
b.ChatFullInfo()
getChat.
b.ChatMemberOf()
b.ProfilePhotosOf()
b.InviteLink()
b.CreateInviteLink()
link parameter can specify a Name, ExpireUnixtime, MemberLimit, or JoinRequest flag.
b.EditInviteLink()
b.RevokeInviteLink()
b.ApproveJoinRequest()
OnChatJoinRequest handler).
b.DeclineJoinRequest()
Callbacks & Queries
b.Respond()
The callback to respond to.
Optional response parameters. Defaults to an empty acknowledgment.
b.Answer()
b.AnswerWebApp()
Payments
b.Ship()
string to indicate an error.
b.Accept()
b.StarTransactions()
Admin Methods
These methods require the bot to have appropriate administrator rights.b.Ban()
member.RestrictedUntil. Pass revokeMessages: true to also delete all messages sent by the user in the chat.
The chat to ban the user from.
The member to ban. Uses
member.RestrictedUntil as the ban expiry Unix timestamp. Use tele.Forever() for a permanent ban.If
true, deletes all messages from this user in the chat.b.Unban()
forBanned: true to only act on actually banned users.
The chat to unban from.
The user to unban.
If
true, only unbans users that are currently banned (ignores others).b.Restrict()
member.RestrictedUntil. Use tele.NoRestrictions() to lift all restrictions.
The target chat.
Member with updated
Rights and RestrictedUntil set. Set Rights.Independent = true to use independent permission evaluation.b.Promote()
tele.AdminRights() to grant full admin access, or tele.NoRights() to demote.
The target chat.
Member with the desired
Rights and optionally Anonymous: true.b.AdminsOf()
b.Len()
b.SetAdminTitle()
b.BanSenderChat()
b.UnbanSenderChat()
b.DefaultRights()
If
true, returns rights for channels; otherwise for groups.b.SetDefaultRights()
Menu Buttons
b.MenuButton()
b.SetMenuButton()
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()
b.MyName()
b.SetMyDescription()
b.MyDescription()
b.SetMyShortDescription()
b.MyShortDescription()
Server Control
b.Logout()
b.Close()
Manual Processing
b.ProcessUpdate()
Update by creating a context and dispatching it through the registered handlers. Useful for webhook or custom poller implementations where you feed updates manually.
The incoming update to process.
b.NewContext()
Context wrapping the given Update. Useful when implementing custom pollers or testing handlers directly.
Error Handling
b.OnError()
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:
Miscellaneous
b.SetUserEmojiStatus()
b.NewMarkup()
*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.