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