Merge pull request #434 from go-telegram-bot-api/develop-docs

Add improved documentation

Author: Syfaro

.gitignore

@@ -1,3 +1,4 @@
 .idea/
 coverage.out
 tmp/
+book/

book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["Syfaro"]
+language = "en"
+multilingual = false
+src = "docs"
+title = "Go Telegram Bot API"
+
+[output.html]
+git-repository-url = "https://github.com/go-telegram-bot-api/telegram-bot-api"

docs/SUMMARY.md

@@ -0,0 +1,17 @@
+# Summary
+
+- [Getting Started](./getting-started/README.md)
+  - [Library Structure](./getting-started/library-structure.md)
+  - [Files](./getting-started/files.md)
+  - [Important Notes](./getting-started/important-notes.md)
+- [Examples](./examples/README.md)
+  - [Command Handling](./examples/command-handling.md)
+  - [Keyboard](./examples/keyboard.md)
+  - [Inline Keyboard](./examples/inline-keyboard.md)
+- [Change Log](./changelog.md)
+
+# Contributing
+
+- [Internals](./internals/README.md)
+  - [Adding Endpoints](./internals/adding-endpoints.md)
+  - [Uploading Files](./internals/uploading-files.md)

docs/changelog.md

@@ -0,0 +1,19 @@
+# Change Log
+
+## v5
+
+**Work In Progress**
+
+- Remove all methods that return `(APIResponse, error)`.
+  - Use the `Request` method instead.
+  - For more information, see [Library Structure][library-structure].
+- Remove all `New*Upload` and `New*Share` methods, replace with `New*`.
+  - Use different [file types][files] to specify if upload or share.
+- Rename `UploadFile` to `UploadFiles`, accept `[]RequestFile` instead of a
+  single fieldname and file.
+- Fix methods returning `APIResponse` and errors to always use pointers.
+- Update user IDs to `int64` because of Bot API changes.
+- Add missing Bot API features.
+
+[library-structure]: ./getting-started/library-structure.md#methods
+[files]: ./getting-started/files.md

docs/examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+With a better understanding of how the library works, let's look at some more
+examples showing off some of Telegram's features.

docs/examples/command-handling.md

@@ -0,0 +1,60 @@
+# Command Handling
+
+This is a simple example of changing behavior based on a provided command.
+
+```go
+package main
+
+import (
+	"log"
+	"os"
+
+	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+)
+
+func main() {
+	bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
+	if err != nil {
+		log.Panic(err)
+	}
+
+	bot.Debug = true
+
+	log.Printf("Authorized on account %s", bot.Self.UserName)
+
+	u := tgbotapi.NewUpdate(0)
+	u.Timeout = 60
+
+	updates := bot.GetUpdatesChan(u)
+
+	for update := range updates {
+		if update.Message == nil { // ignore any non-Message updates
+			continue
+		}
+
+		if !update.Message.IsCommand() { // ignore any non-command Messages
+			continue
+		}
+
+		// Create a new MessageConfig. We don't have text yet,
+		// so we leave it empty.
+		msg := tgbotapi.NewMessage(update.Message.Chat.ID, "")
+
+		// Extract the command from the Message.
+		switch update.Message.Command() {
+		case "help":
+			msg.Text = "I understand /sayhi and /status."
+		case "sayhi":
+			msg.Text = "Hi :)"
+		case "status":
+			msg.Text = "I'm ok."
+		default:
+			msg.Text = "I don't know that command"
+		}
+
+		if _, err := bot.Send(msg); err != nil {
+			log.Panic(err)
+		}
+	}
+}
+```

docs/examples/inline-keyboard.md

@@ -0,0 +1,80 @@
+# Inline Keyboard
+
+This bot waits for you to send it the message "open" before sending you an
+inline keyboard containing a URL and some numbers. When a number is clicked, it
+sends you a message with your selected number.
+
+```go
+package main
+
+import (
+	"log"
+	"os"
+
+	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+)
+
+var numericKeyboard = tgbotapi.NewInlineKeyboardMarkup(
+	tgbotapi.NewInlineKeyboardRow(
+		tgbotapi.NewInlineKeyboardButtonURL("1.com", "http://1.com"),
+		tgbotapi.NewInlineKeyboardButtonData("2", "2"),
+		tgbotapi.NewInlineKeyboardButtonData("3", "3"),
+	),
+	tgbotapi.NewInlineKeyboardRow(
+		tgbotapi.NewInlineKeyboardButtonData("4", "4"),
+		tgbotapi.NewInlineKeyboardButtonData("5", "5"),
+		tgbotapi.NewInlineKeyboardButtonData("6", "6"),
+	),
+)
+
+func main() {
+	bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
+	if err != nil {
+		log.Panic(err)
+	}
+
+	bot.Debug = true
+
+	log.Printf("Authorized on account %s", bot.Self.UserName)
+
+	u := tgbotapi.NewUpdate(0)
+	u.Timeout = 60
+
+	updates := bot.GetUpdatesChan(u)
+
+	// Loop through each update.
+	for update := range updates {
+		// Check if we've gotten a message update.
+		if update.Message != nil {
+			// Construct a new message from the given chat ID and containing
+			// the text that we received.
+			msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
+
+			// If the message was open, add a copy of our numeric keyboard.
+			switch update.Message.Text {
+			case "open":
+				msg.ReplyMarkup = numericKeyboard
+
+			}
+
+			// Send the message.
+			if _, err = bot.Send(msg); err != nil {
+				panic(err)
+			}
+		} else if update.CallbackQuery != nil {
+			// Respond to the callback query, telling Telegram to show the user
+			// a message with the data received.
+			callback := tgbotapi.NewCallback(update.CallbackQuery.ID, update.CallbackQuery.Data)
+			if _, err := bot.Request(callback); err != nil {
+				panic(err)
+			}
+
+			// And finally, send a message containing the data received.
+			msg := tgbotapi.NewMessage(update.CallbackQuery.Message.Chat.ID, update.CallbackQuery.Data)
+			if _, err := bot.Send(msg); err != nil {
+				panic(err)
+			}
+		}
+	}
+}
+```

docs/examples/keyboard.md

@@ -0,0 +1,63 @@
+# Keyboard
+
+This bot shows a numeric keyboard when you send a "open" message and hides it
+when you send "close" message.
+
+```go
+package main
+
+import (
+	"log"
+	"os"
+
+	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+)
+
+var numericKeyboard = tgbotapi.NewReplyKeyboard(
+	tgbotapi.NewKeyboardButtonRow(
+		tgbotapi.NewKeyboardButton("1"),
+		tgbotapi.NewKeyboardButton("2"),
+		tgbotapi.NewKeyboardButton("3"),
+	),
+	tgbotapi.NewKeyboardButtonRow(
+		tgbotapi.NewKeyboardButton("4"),
+		tgbotapi.NewKeyboardButton("5"),
+		tgbotapi.NewKeyboardButton("6"),
+	),
+)
+
+func main() {
+	bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
+	if err != nil {
+		log.Panic(err)
+	}
+
+	bot.Debug = true
+
+	log.Printf("Authorized on account %s", bot.Self.UserName)
+
+	u := tgbotapi.NewUpdate(0)
+	u.Timeout = 60
+
+	updates := bot.GetUpdatesChan(u)
+
+	for update := range updates {
+		if update.Message == nil { // ignore non-Message updates
+			continue
+		}
+
+		msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
+
+		switch update.Message.Text {
+		case "open":
+			msg.ReplyMarkup = numericKeyboard
+		case "close":
+			msg.ReplyMarkup = tgbotapi.NewRemoveKeyboard(true)
+		}
+
+		if _, err := bot.Send(msg); err != nil {
+			log.Panic(err)
+		}
+	}
+}
+```

docs/getting-started/README.md

@@ -0,0 +1,112 @@
+# Getting Started
+
+This library is designed as a simple wrapper around the Telegram Bot API.
+It's encouraged to read [Telegram's docs][telegram-docs] first to get an
+understanding of what Bots are capable of doing. They also provide some good
+approaches to solve common problems.
+
+[telegram-docs]: https://core.telegram.org/bots
+
+## Installing
+
+```bash
+go get -u github.com/go-telegram-bot-api/telegram-bot-api/v5@develop
+```
+
+It's currently suggested to use the develop branch. While there may be breaking
+changes, it has a number of features not yet available on master.
+
+## A Simple Bot
+
+To walk through the basics, let's create a simple echo bot that replies to your
+messages repeating what you said. Make sure you get an API token from
+[@Botfather][botfather] before continuing.
+
+Let's start by constructing a new [BotAPI][bot-api-docs].
+
+[botfather]: https://t.me/Botfather
+[bot-api-docs]: https://pkg.go.dev/github.com/go-telegram-bot-api/telegram-bot-api/v5?tab=doc#BotAPI
+
+```go
+package main
+
+import (
+	"os"
+
+	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+)
+
+func main() {
+	bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
+	if err != nil {
+		panic(err)
+	}
+
+	bot.Debug = true
+}
+```
+
+Instead of typing the API token directly into the file, we're using
+environment variables. This makes it easy to configure our Bot to use the right
+account and prevents us from leaking our real token into the world. Anyone with
+your token can send and receive messages from your Bot!
+
+We've also set `bot.Debug = true` in order to get more information about the
+requests being sent to Telegram. If you run the example above, you'll see
+information about a request to the [`getMe`][get-me] endpoint. The library
+automatically calls this to ensure your token is working as expected. It also
+fills in the `Self` field in your `BotAPI` struct with information about the
+Bot.
+
+Now that we've connected to Telegram, let's start getting updates and doing
+things. We can add this code in right after the line enabling debug mode.
+
+[get-me]: https://core.telegram.org/bots/api#getme
+
+```go
+	// Create a new UpdateConfig struct with an offset of 0. Offsets are used
+	// to make sure Telegram knows we've handled previous values and we don't
+	// need them repeated.
+	updateConfig := tgbotapi.NewUpdate(0)
+
+	// Tell Telegram we should wait up to 30 seconds on each request for an
+	// update. This way we can get information just as quickly as making many
+	// frequent requests without having to send nearly as many.
+	updateConfig.Timeout = 30
+
+	// Start polling Telegram for updates.
+	updates := bot.GetUpdatesChan(updateConfig)
+
+	// Let's go through each update that we're getting from Telegram.
+	for update := range updates {
+		// Telegram can send many types of updates depending on what your Bot
+		// is up to. We only want to look at messages for now, so we can
+		// discard any other updates.
+		if update.Message == nil {
+			continue
+		}
+
+		// Now that we know we've gotten a new message, we can construct a
+		// reply! We'll take the Chat ID and Text from the incoming message
+		// and use it to create a new message.
+		msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
+		// We'll also say that this message is a reply to the previous message.
+		// For any other specifications than Chat ID or Text, you'll need to
+		// set fields on the `MessageConfig`.
+		msg.ReplyToMessageID = update.Message.MessageID
+
+		// Okay, we're sending our message off! We don't care about the message
+		// we just sent, so we'll discard it.
+		if _, err := bot.Send(msg); err != nil {
+			// Note that panics are a bad way to handle errors. Telegram can
+			// have service outages or network errors, you should retry sending
+			// messages or more gracefully handle failures.
+			panic(err)
+		}
+	}
+```
+
+Congradulations! You've made your very own bot!
+
+Now that you've got some of the basics down, we can start talking about how the
+library is structured and more advanced features.