We're happy to finally announce V4 of Telebot. It took a while: the first V4 beta was tagged back in 2024, and Telegram has shipped well over a dozen Bot API versions since. This release catches up with all of them, up to Bot API 10.4, and we now check every method and type against the published Bot API spec on every test run, so nothing slips through again (see COVERAGE.md).
Especial thanks to everyone who sent pull requests, reported bugs and kept using the betas in production while we got here.
Changelog
gopkg.in/telebot.v4is the new import path- Bot API 7.9 up to 10.4
- Rich messages, ephemeral messages and streamed drafts
- Stories, gifts, business account management, checklists, suggested posts, managed bots and widgets
- Replies stay in the topic they answer by default
- Bot tokens and other secrets never show up in errors or logs
- Lots of fixes found by checking every request against the Bot API
Coming straight from V3.3? Read the V3.4 notes first, its breaking changes apply here as well.
Topics and threads by default
Replying through the Context now keeps you in the forum topic, or the thread of a private chat, the message came from. No more passing the thread ID around by hand (#745):
b.Handle("/ping", func(c tele.Context) error {
// 1. Replies in the same topic
c.Send("pong")
// 2. Use IgnoreThread to post to the main chat instead
return c.Send("pong in the main chat", tele.IgnoreThread)
})Bot API 10.1-10.4: Rich messages
Rich messages are Telegram's new long-form format with headings, lists, tables, quotes, media and buttons. Send one from HTML or Markdown, or build it block by block:
// 1. From HTML or Markdown
b.Send(chat, &tele.InputRichMessage{HTML: "<b>Hello</b>, rich world"})
// 2. From blocks
b.Send(chat, &tele.InputRichMessage{Blocks: []tele.InputRichBlock{
tele.InputRichBlockSectionHeading{Text: tele.RichText{Plain: "Release notes"}, Size: 1},
tele.InputRichBlockParagraph{Text: tele.RichText{Parts: []tele.RichText{
{Plain: "telebot is now "},
{Type: tele.RichBold, Text: &tele.RichText{Plain: "stable"}},
}}},
}})Incoming rich messages are in Message.RichMessage.
Bot API 10.2, 10.3: Ephemeral messages
Messages in a group that only one user can see:
msg, err := b.Send(group, "only you can see this", &tele.EphemeralMessageParameters{
ReceiverUserID: user.ID,
})
if err != nil {
return err
}
b.EditEphemeral(msg, "still only you")
b.DeleteEphemeral(msg)Streamed drafts
Show the answer while it's being generated, which is handy for LLM bots. Since Bot API 10.3 the user can also stop it:
stop := &tele.SendOptions{CanStop: true, KeepOnStop: true}
// 1. An empty text shows "Thinking…"
b.SendDraft(user, 1, "", stop)
// 2. Update the draft with the same ID as the answer grows
b.SendDraft(user, 1, "Generating the answer…", stop)
// 3. Send the final message once it's done
b.Send(user, "Here is the answer.")
// 4. Find out when the user pressed stop
b.Handle(tele.OnGenerationStopped, func(c tele.Context) error {
...
})SendRichDraft does the same for rich messages.
Bot API 8.0-10.4: Gifts and stories
// 1. Send a gift with a note
gifts, err := b.AvailableGifts()
if err != nil {
return err
}
b.SendGift(user, gifts[0].ID, "Happy birthday!")
// 2. Look through the gifts a user received
owned, err := b.UserGifts(user, tele.GiftQuery{Limit: 10})
// 3. Post a story on behalf of a business account
story, err := b.PostStory(connID, tele.StoryParams{
Content: &tele.InputStoryContentPhoto{Photo: tele.FromDisk("story.jpg")},
ActivePeriod: 86400,
Caption: "Fresh from the bot",
})Business accounts can also be fully managed now: name, username, bio, profile photo, gift settings, Stars balance and messages.
Other Features
- Reactions finally reach their handlers:
b.Handle(tele.OnReaction, func(c tele.Context) error {
r := c.MessageReaction()
r.OldReaction
r.NewReaction
...
})b.RawFilescalls any method with file uploads, for whenever telebot lags behind Telegram:
b.RawFiles("sendDocument", map[string]string{"chat_id": "42"}, map[string]tele.File{
"document": tele.FromDisk("report.pdf"),
})Offlinebots take their ID from the token, so tests can rely onb.Me.ID(#815)- Checklists, channel direct messages and suggested posts, communities, join request queries, chat share themes, live photos, poll media, managed bots, guest mode, widgets, TON transfers, subscription invite links and Telegram Passport are all there too. The whole list is in
COVERAGE.md.
Backward incompatible changes
V4 is a major version, so we took the chance to fix a few signatures that couldn't grow with the Bot API:
NotifyandUnpintake options instead of a bare thread ID:b.Notify(chat, tele.Typing, &tele.Topic{ThreadID: 42})ProfilePhotosOf(user, offset, limit)supports pagingAdminsOf(chat, true)can include bots, andEditReplyMarkupaccepts optionsSendPaidis calledSendPaidMedia, after the Bot API methodMessage.TopicClosed,GeneralTopicHiddenandGeneralTopicUnhiddenhave named types, nil checks work as beforeUser.IsForumis removed, it was never on theUser(Chat.IsForumis still there)ArticleResult.HideURLis removed, Telegram dropped it
If you're on one of the betas, a few names changed late in the cycle:
GetAvailableGiftsisAvailableGifts, andSavePreparedInlineMessageisPrepareMessageVerifyUserandVerifyChatbecame a singleVerifyTransactionPartner.Chatis a*Chat
Fixes and Improvements
- The bot token, webhook secret and provider tokens are redacted from errors and verbose logs
- Graceful shutdown of the webhook poller
ReplyParamsis sent asreply_parameters(#821)- Spoiler and caption-above flags are sent for each photo, video or animation (#822)
BanandLenusebanChatMemberandgetChatMemberCountinstead of the deprecated namesForwardManyandCopyManyforward from the right chat- Uploaded files are named after the file on disk
Location.AlertRadiusis sent asproximity_alert_radius- Business message handlers get their message
OnLivePhotofires for live photos, checklists no longer triggerOnMedia- No more panic when Telegram returns a different media kind than the one sent
io/ioutilis gone (#814)