Skip to main content
Handlers are the core of your bot’s logic. You map an endpoint (a command string, an event constant, or a button reference) to a HandlerFunc, and Telebot calls that function whenever a matching update arrives.

​
HandlerFunc

// HandlerFunc represents a handler function, which is
// used to handle actual endpoints.
type HandlerFunc func(Context) error
Return nil on success. Return a non-nil error to invoke the bot’s OnError callback.

​
b.Handle

// Handle lets you set the handler for some command name or
// one of the supported endpoints. It also applies middleware
// if such passed to the function.
func (b *Bot) Handle(endpoint interface{}, h HandlerFunc, m ...MiddlewareFunc)
​
endpoint
interface{}
required
What triggers this handler. See Endpoint types below.
​
h
HandlerFunc
required
The function to call when the endpoint matches.
​
m
...MiddlewareFunc
Optional per-handler middleware applied only to this endpoint. Combined with any group-level middleware.
Handle panics with "telebot: unsupported endpoint" if the endpoint value cannot be converted to a string key. Always pass a string literal, an event constant, or a pointer to a Btn / InlineButton.

​
Endpoint types

​
String commands

Any string starting with / is treated as a bot command: 
b.Handle("/start", func(c tele.Context) error {
    return c.Send("Welcome!")
})

b.Handle("/help", onHelp)
Telebot strips the @botname suffix automatically and only matches commands directed at your bot.

​
Arbitrary text

You can match exact message text: 
b.Handle("ping", func(c tele.Context) error {
    return c.Send("pong")
})

​
Event constants

All built-in event constants begin with \a (alert character) to prevent collisions with user text: 
b.Handle(tele.OnText, func(c tele.Context) error {
    return c.Reply("Got your message: " + c.Text())
})

b.Handle(tele.OnPhoto, func(c tele.Context) error {
    return c.Reply("Nice photo!")
})

​
Button and markup references

Pass a pointer to an InlineButton or Btn to bind a callback handler directly to that button: 
menu := &tele.ReplyMarkup{}
btnHelp := menu.Text("Help")
btnSettings := menu.Text("Settings")
menu.Reply(menu.Row(btnHelp, btnSettings))

b.Handle(&btnHelp, func(c tele.Context) error {
    return c.Send("Here is the help text.")
})

​
Full event constant reference

​
Messages

ConstantTriggers on
tele.OnTextAny text message
tele.OnForwardForwarded message
tele.OnReplyReply to a message
tele.OnEditedEdited message
tele.OnMediaAny media message
tele.OnPhotoPhoto
tele.OnAudioAudio file
tele.OnAnimationGIF / animation
tele.OnDocumentDocument / file
tele.OnStickerSticker
tele.OnVideoVideo
tele.OnVoiceVoice message
tele.OnVideoNoteVideo note
tele.OnContactContact card
tele.OnLocationLocation
tele.OnVenueVenue
tele.OnDiceDice roll
tele.OnInvoiceInvoice message
tele.OnPaymentSuccessful payment
tele.OnRefundRefunded payment
tele.OnGameGame
tele.OnPollPoll
tele.OnPollAnswerPoll answer
tele.OnPinnedPinned message notification
tele.OnChannelPostNew channel post
tele.OnEditedChannelPostEdited channel post

​
Group / supergroup events

ConstantTriggers on
tele.OnAddedToGroupBot added to group
tele.OnUserJoinedNew member joined
tele.OnUserLeftMember left
tele.OnUserSharedUser shared via button
tele.OnChatSharedChat shared via button
tele.OnNewGroupTitleGroup title changed
tele.OnNewGroupPhotoGroup photo changed
tele.OnGroupPhotoDeletedGroup photo deleted
tele.OnGroupCreatedGroup created
tele.OnSuperGroupCreatedSupergroup created
tele.OnChannelCreatedChannel created
tele.OnMigrationGroup migrated to supergroup

​
Topics (forum)

ConstantTriggers on
tele.OnTopicCreatedTopic created
tele.OnTopicReopenedTopic reopened
tele.OnTopicClosedTopic closed
tele.OnTopicEditedTopic edited
tele.OnGeneralTopicHiddenGeneral topic hidden
tele.OnGeneralTopicUnhiddenGeneral topic unhidden

​
Interactions

ConstantTriggers on
tele.OnCallbackInline keyboard button press
tele.OnQueryInline query
tele.OnInlineResultChosen inline result
tele.OnShippingShipping query
tele.OnCheckoutPre-checkout query
tele.OnWebAppWeb App data
tele.OnWriteAccessAllowedWrite access allowed

​
Chat membership

ConstantTriggers on
tele.OnMyChatMemberBot’s own chat member status changed
tele.OnChatMemberChat member status changed
tele.OnChatJoinRequestJoin request received

​
Video chats

ConstantTriggers on
tele.OnVideoChatStartedVideo chat started
tele.OnVideoChatEndedVideo chat ended
tele.OnVideoChatParticipantsParticipants invited
tele.OnVideoChatScheduledVideo chat scheduled

​
Miscellaneous

ConstantTriggers on
tele.OnProximityAlertProximity alert triggered
tele.OnAutoDeleteTimerAuto-delete timer changed
tele.OnBoostChat boost updated
tele.OnBoostRemovedChat boost removed
tele.OnBusinessConnectionBusiness connection
tele.OnBusinessMessageBusiness message
tele.OnEditedBusinessMessageEdited business message
tele.OnDeletedBusinessMessagesDeleted business messages
tele.OnPurchasedPaidMediaPurchased paid media

​
Routing order

Telebot routes each incoming Update by inspecting its fields in a deterministic order defined in ProcessContext. The key rules are:
  1. Commands take priority over OnText — /start is matched before OnText.
  2. Exact text matches are checked next (e.g. b.Handle("ping", ...)).
  3. Event constants (OnText, OnPhoto, etc.) are the fallback.
  4. Callbacks route first to the specific button endpoint (using the encoded button ID), then fall through to OnCallback.
// Both handlers can coexist: /start is a command, OnText is a fallback
b.Handle("/start", onStart)
b.Handle(tele.OnText, onText) // receives all non-command text messages

​
Triggering handlers programmatically

You can fire a handler manually using b.Trigger: 
// Trigger executes the registered handler by the endpoint.
func (b *Bot) Trigger(endpoint interface{}, c Context) error

err := b.Trigger("/start", c)
This is useful for redirecting from one handler to another, or in tests.

Build docs developers (and LLMs) love

Get started for freeTalk to us