1# Getting Started
  2
  3This library is designed as a simple wrapper around the Telegram Bot API.
  4It's encouraged to read [Telegram's docs][telegram-docs] first to get an
  5understanding of what Bots are capable of doing. They also provide some good
  6approaches to solve common problems.
  7
  8[telegram-docs]: https://core.telegram.org/bots
  9
 10## Installing
 11
 12```bash
 13go get -u github.com/go-telegram-bot-api/telegram-bot-api@develop
 14```
 15
 16It's currently suggested to use the develop branch. While there may be breaking
 17changes, it has a number of features not yet available on master.
 18
 19## A Simple Bot
 20
 21To walk through the basics, let's create a simple echo bot that replies to your
 22messages repeating what you said. Make sure you get an API token from
 23[@Botfather][botfather] before continuing.
 24
 25Let's start by constructing a new [BotAPI][bot-api-docs].
 26
 27[botfather]: https://t.me/Botfather
 28[bot-api-docs]: https://pkg.go.dev/github.com/go-telegram-bot-api/telegram-bot-api/v5?tab=doc#BotAPI
 29
 30```go
 31package main
 32
 33import (
 34    "os"
 35
 36    "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 37)
 38
 39func main() {
 40    bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
 41    if err != nil {
 42        panic(err)
 43    }
 44
 45    bot.Debug = true
 46}
 47```
 48
 49Instead of typing the API token directly into the file, we're using
 50environment variables. This makes it easy to configure our Bot to use the right
 51account and prevents us from leaking our real token into the world. Anyone with
 52your token can send and receive messages from your Bot!
 53
 54We've also set `bot.Debug = true` in order to get more information about the
 55requests being sent to Telegram. If you run the example above, you'll see
 56information about a request to the [`getMe`][get-me] endpoint. The library
 57automatically calls this to ensure your token is working as expected. It also
 58fills in the `Self` field in your `BotAPI` struct with information about the
 59Bot.
 60
 61Now that we've connected to Telegram, let's start getting updates and doing
 62things. We can add this code in right after the line enabling debug mode.
 63
 64[get-me]: https://core.telegram.org/bots/api#getme
 65
 66```go
 67    // Create a new UpdateConfig struct with an offset of 0. Offsets are used
 68    // to make sure Telegram knows we've handled previous values and we don't
 69    // need them repeated.
 70    updateConfig := tgbotapi.NewUpdate(0)
 71
 72    // Tell Telegram we should wait up to 30 seconds on each request for an
 73    // update. This way we can get information just as quickly as making many
 74    // frequent requests without having to send nearly as many.
 75    updateConfig.Timeout = 30
 76
 77    // Start polling Telegram for updates.
 78    updates := bot.GetUpdatesChan(updateConfig)
 79
 80    // Let's go through each update that we're getting from Telegram.
 81    for update := range updates {
 82        // Telegram can send many types of updates depending on what your Bot
 83        // is up to. We only want to look at messages for now, so we can
 84        // discard any other updates.
 85        if update.Message == nil {
 86            continue
 87        }
 88
 89        // Now that we know we've gotten a new message, we can construct a
 90        // reply! We'll take the Chat ID and Text from the incoming message
 91        // and use it to create a new message.
 92        msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
 93        // We'll also say that this message is a reply to the previous message.
 94        // For any other specifications than Chat ID or Text, you'll need to
 95        // set fields on the `MessageConfig`.
 96        msg.ReplyToMessageID = update.Message.MessageID
 97
 98        // Okay, we're sending our message off! We don't care about the message
 99        // we just sent, so we'll discard it.
100        if _, err := bot.Send(msg); err != nil {
101            // Note that panics are a bad way to handle errors. Telegram can
102            // have service outages or network errors, you should retry sending
103            // messages or more gracefully handle failures.
104            panic(err)
105        }
106    }
107```
108
109Congradulations! You've made your very own bot!
110
111Now that you've got some of the basics down, we can start talking about how the
112library is structured and more advanced features.