github tucnak/telebot v4.0.0
Telebot V4

latest release: v3.4.2-beta
one hour ago

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.v4 is 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.RawFiles calls 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"),
})
  • Offline bots take their ID from the token, so tests can rely on b.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:

  • Notify and Unpin take options instead of a bare thread ID: b.Notify(chat, tele.Typing, &tele.Topic{ThreadID: 42})
  • ProfilePhotosOf(user, offset, limit) supports paging
  • AdminsOf(chat, true) can include bots, and EditReplyMarkup accepts options
  • SendPaid is called SendPaidMedia, after the Bot API method
  • Message.TopicClosed, GeneralTopicHidden and GeneralTopicUnhidden have named types, nil checks work as before
  • User.IsForum is removed, it was never on the User (Chat.IsForum is still there)
  • ArticleResult.HideURL is removed, Telegram dropped it

If you're on one of the betas, a few names changed late in the cycle:

  • GetAvailableGifts is AvailableGifts, and SavePreparedInlineMessage is PrepareMessage
  • VerifyUser and VerifyChat became a single Verify
  • TransactionPartner.Chat is 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
  • ReplyParams is sent as reply_parameters (#821)
  • Spoiler and caption-above flags are sent for each photo, video or animation (#822)
  • Ban and Len use banChatMember and getChatMemberCount instead of the deprecated names
  • ForwardMany and CopyMany forward from the right chat
  • Uploaded files are named after the file on disk
  • Location.AlertRadius is sent as proximity_alert_radius
  • Business message handlers get their message
  • OnLivePhoto fires for live photos, checklists no longer trigger OnMedia
  • No more panic when Telegram returns a different media kind than the one sent
  • io/ioutil is gone (#814)

Discussion

Discuss on Telegram

Don't miss a new telebot release

NewReleases is sending notifications on new releases.