Basics

Telegram Bot Basics

Register a Bot

First of all, you need to create a bot in Telegram. There is a special bot for this purpose - @BotFather. Open chat with BotFather and press “Start” to start chat with it. It will show you help message to guide through the steps:

  • Click /newbot link in the help message, or send /newbot message to chat.
  • Then BotFather will ask you for the name of your bot. You can choose anything you like, for example, MyTest.
  • After the name, BotFather will ask for a username of the bot. It must end with “bot”, so users can differentiate it from real people.

You’re done! BotFather will provide authentication token for the bot, just provide it to tbot on initialization with tbot.New().

Get Updates from Telegram

Telegram bots can interact with Telegram servers in two different ways: using long polling or webhooks. In this section we will review both ways and how to implement them in tbot.

Long polling

In long polling setup tbot act as a client, asking to Telegram server for updates and waiting when they're available. Example scenario in following diagram:

sequenceDiagram tbot->>Telegram: Hello Telegram, any updates for me? Telegram-->>tbot: Yes, here they are! tbot->>Telegram: Great! And now? activate Telegram Note right of Telegram: Hm... Wait a min... Telegram-->>tbot: Found one! deactivate Telegram

tbot will use long polling by default, when you create new instance of Bot:

bot := tbot.New(token)

This kind of setup is really handful during development and for moderate load bots. If your bot is suppose to be highly interactive or be used by a lot of users, the best production grade setup is using webhooks.

Webhooks

In the webhooks setup tbot acts like a server, listening for a requests from Telegram with updates.

It looks like on the following diagram:

sequenceDiagram tbot->>Telegram: Hi! I'm listening on https://example.com activate Telegram Telegram->>tbot: User is typing! Telegram->>tbot: User sent you a message! Telegram->>tbot: User sent you a picture! Telegram->>tbot: User pressed the button! deactivate Telegram

To setup webhook just pass it's configuration on initializing:

bot := tbot.New(token, tbot.WithWebhook("https://example.com", ":8080"))

tbot.WithWebhook function takes two parms:

  • public URL of web service
  • address for server to listen on
Note: you need HTTPS endpoint with a valid certificate. You may want to use service like LetsEncrypt to get one.

Use Telegram Bots API Client

To send messages, files, buttons, actions to the User we use API client. You can get preconfigured client from bot using Client() method:

bot := tbot.New(token)
client := bot.Client()

This client provides wrappers for all API methods available on Telegram Bots API platform like SendMessage, SendAction, etc.

client.SendMessage(chatID, "hello from tbot!")

Handling Updates

To handle updates from Telegram tbot use concept of Handlers. Each Handler type corresponds to different event type happening in Telegram, so we can handle it properly. The most popular things that we want to handle are Messages, Callbacks from buttons, Poll updates.

To set handler to bot there are several methods:

bot.HandleMessage(pattern string, handler func(*tbot.Message))

Set handler for messages. Messages may include not only text, but all different kinds of data: Videos, Images, Documents, etc. First parameter is a regular expression to filter only relevant messages, by default its .*.

bot.HandleChannelPost(handler func(*tbot.Message))

Similar to previous one, but for handling messages in channels.

bot.HandleCallback(handler func(*tbot.CallbackQuery))

Handle callback queries from Inline buttons.

bot.HandlePollUpdate(handler func(*tbot.Poll))

Handle polls updates, just gets updated poll state.

Full list of supported Handlers you can find in reference.