Skip to content

Commit a36ca53

Browse files
SyfaroSyfaro
committed
Add to and update docs.
1 parent 5be2526 commit a36ca53

File tree

7 files changed

+244
-97
lines changed

7 files changed

+244
-97
lines changed

‎docs/SUMMARY.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
# Summary
22

33
- [Getting Started](./getting-started/README.md)
4-
* [Library Structure](./getting-started/library-structure.md)
5-
* [Files](./getting-started/files.md)
4+
- [Library Structure](./getting-started/library-structure.md)
5+
- [Files](./getting-started/files.md)
6+
- [Important Notes](./getting-started/important-notes.md)
67
- [Examples](./examples/README.md)
7-
* [Command Handling](./examples/command-handling.md)
8-
* [Keyboard](./examples/keyboard.md)
9-
- [Change Log]()
8+
- [Command Handling](./examples/command-handling.md)
9+
- [Keyboard](./examples/keyboard.md)
10+
- [Inline Keyboard](./examples/inline-keyboard.md)
11+
- [Change Log](./changelog.md)
1012

1113
# Contributing
1214

1315
- [Internals](./internals/README.md)
14-
* [Adding Endpoints](./internals/adding-endpoints.md)
15-
* [Uploading Files](./internals/uploading-files.md)
16+
- [Adding Endpoints](./internals/adding-endpoints.md)
17+
- [Uploading Files](./internals/uploading-files.md)

‎docs/changelog.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Change Log
2+
3+
## v5
4+
5+
**Work In Progress**
6+
7+
- Remove all methods that return `(APIResponse, error)`.
8+
- Use the `Request` method instead.
9+
- For more information, see [Library Structure][library-structure].
10+
- Remove all `New*Upload` and `New*Share` methods, replace with `New*`.
11+
- Use different [file types][files] to specify if upload or share.
12+
- Rename `UploadFile` to `UploadFiles`, accept `[]RequestFile` instead of a
13+
single fieldname and file.
14+
- Fix methods returning `APIResponse` and errors to always use pointers.
15+
- Update user IDs to `int64` because of Bot API changes.
16+
- Add missing Bot API features.
17+
18+
[library-structure]: ./getting-started/library-structure.md#methods
19+
[files]: ./getting-started/files.md

‎docs/examples/command-handling.md‎

Lines changed: 46 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,55 +6,55 @@ This is a simple example of changing behavior based on a provided command.
66
package main
77

88
import (
9-
"log"
10-
"os"
9+
"log"
10+
"os"
1111

12-
"github.com/go-telegram-bot-api/telegram-bot-api"
12+
tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
1313
)
1414

1515
func main() {
16-
bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
17-
if err != nil {
18-
log.Panic(err)
19-
}
20-
21-
bot.Debug = true
22-
23-
log.Printf("Authorized on account %s", bot.Self.UserName)
24-
25-
u := tgbotapi.NewUpdate(0)
26-
u.Timeout = 60
27-
28-
updates := bot.GetUpdatesChan(u)
29-
30-
for update := range updates {
31-
if update.Message == nil { // ignore any non-Message updates
32-
continue
33-
}
34-
35-
if !update.Message.IsCommand() { // ignore any non-command Messages
36-
continue
37-
}
38-
39-
// Create a new MessageConfig. We don't have text yet,
40-
// so we leave it empty.
41-
msg := tgbotapi.NewMessage(update.Message.Chat.ID, "")
42-
43-
// Extract the command from the Message.
44-
switch update.Message.Command() {
45-
case "help":
46-
msg.Text = "I understand /sayhi and /status."
47-
case "sayhi":
48-
msg.Text = "Hi :)"
49-
case "status":
50-
msg.Text = "I'm ok."
51-
default:
52-
msg.Text = "I don't know that command"
53-
}
54-
55-
if _, err := bot.Send(msg); err != nil {
56-
log.Panic(err)
57-
}
58-
}
16+
bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
17+
if err != nil {
18+
log.Panic(err)
19+
}
20+
21+
bot.Debug = true
22+
23+
log.Printf("Authorized on account %s", bot.Self.UserName)
24+
25+
u := tgbotapi.NewUpdate(0)
26+
u.Timeout = 60
27+
28+
updates := bot.GetUpdatesChan(u)
29+
30+
for update := range updates {
31+
if update.Message == nil { // ignore any non-Message updates
32+
continue
33+
}
34+
35+
if !update.Message.IsCommand() { // ignore any non-command Messages
36+
continue
37+
}
38+
39+
// Create a new MessageConfig. We don't have text yet,
40+
// so we leave it empty.
41+
msg := tgbotapi.NewMessage(update.Message.Chat.ID, "")
42+
43+
// Extract the command from the Message.
44+
switch update.Message.Command() {
45+
case "help":
46+
msg.Text = "I understand /sayhi and /status."
47+
case "sayhi":
48+
msg.Text = "Hi :)"
49+
case "status":
50+
msg.Text = "I'm ok."
51+
default:
52+
msg.Text = "I don't know that command"
53+
}
54+
55+
if _, err := bot.Send(msg); err != nil {
56+
log.Panic(err)
57+
}
58+
}
5959
}
6060
```

‎docs/examples/inline-keyboard.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Inline Keyboard
2+
3+
This bot waits for you to send it the message "open" before sending you an
4+
inline keyboard containing a URL and some numbers. When a number is clicked, it
5+
sends you a message with your selected number.
6+
7+
```go
8+
package main
9+
10+
import (
11+
"log"
12+
"os"
13+
14+
tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
15+
)
16+
17+
var numericKeyboard = tgbotapi.NewInlineKeyboardMarkup(
18+
tgbotapi.NewInlineKeyboardRow(
19+
tgbotapi.NewInlineKeyboardButtonURL("1.com", "http://1.com"),
20+
tgbotapi.NewInlineKeyboardButtonData("2", "2"),
21+
tgbotapi.NewInlineKeyboardButtonData("3", "3"),
22+
),
23+
tgbotapi.NewInlineKeyboardRow(
24+
tgbotapi.NewInlineKeyboardButtonData("4", "4"),
25+
tgbotapi.NewInlineKeyboardButtonData("5", "5"),
26+
tgbotapi.NewInlineKeyboardButtonData("6", "6"),
27+
),
28+
)
29+
30+
func main() {
31+
bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
32+
if err != nil {
33+
log.Panic(err)
34+
}
35+
36+
bot.Debug = true
37+
38+
log.Printf("Authorized on account %s", bot.Self.UserName)
39+
40+
u := tgbotapi.NewUpdate(0)
41+
u.Timeout = 60
42+
43+
updates := bot.GetUpdatesChan(u)
44+
45+
// Loop through each update.
46+
for update := range updates {
47+
// Check if we've gotten a message update.
48+
if update.Message != nil {
49+
// Construct a new message from the given chat ID and containing
50+
// the text that we received.
51+
msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
52+
53+
// If the message was open, add a copy of our numeric keyboard.
54+
switch update.Message.Text {
55+
case "open":
56+
msg.ReplyMarkup = numericKeyboard
57+
58+
}
59+
60+
// Send the message.
61+
if _, err = bot.Send(msg); err != nil {
62+
panic(err)
63+
}
64+
} else if update.CallbackQuery != nil {
65+
// Respond to the callback query, telling Telegram to show the user
66+
// a message with the data received.
67+
callback := tgbotapi.NewCallback(update.CallbackQuery.ID, update.CallbackQuery.Data)
68+
if _, err := bot.Request(callback); err != nil {
69+
panic(err)
70+
}
71+
72+
// And finally, send a message containing the data received.
73+
msg := tgbotapi.NewMessage(update.CallbackQuery.Message.Chat.ID, update.CallbackQuery.Data)
74+
if _, err := bot.Send(msg); err != nil {
75+
panic(err)
76+
}
77+
}
78+
}
79+
}
80+
```

‎docs/examples/keyboard.md‎

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -7,57 +7,57 @@ when you send "close" message.
77
package main
88

99
import (
10-
"log"
11-
"os"
10+
"log"
11+
"os"
1212

13-
"github.com/go-telegram-bot-api/telegram-bot-api"
13+
tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
1414
)
1515

1616
var numericKeyboard = tgbotapi.NewReplyKeyboard(
17-
tgbotapi.NewKeyboardButtonRow(
18-
tgbotapi.NewKeyboardButton("1"),
19-
tgbotapi.NewKeyboardButton("2"),
20-
tgbotapi.NewKeyboardButton("3"),
21-
),
22-
tgbotapi.NewKeyboardButtonRow(
23-
tgbotapi.NewKeyboardButton("4"),
24-
tgbotapi.NewKeyboardButton("5"),
25-
tgbotapi.NewKeyboardButton("6"),
26-
),
17+
tgbotapi.NewKeyboardButtonRow(
18+
tgbotapi.NewKeyboardButton("1"),
19+
tgbotapi.NewKeyboardButton("2"),
20+
tgbotapi.NewKeyboardButton("3"),
21+
),
22+
tgbotapi.NewKeyboardButtonRow(
23+
tgbotapi.NewKeyboardButton("4"),
24+
tgbotapi.NewKeyboardButton("5"),
25+
tgbotapi.NewKeyboardButton("6"),
26+
),
2727
)
2828

2929
func main() {
30-
bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
31-
if err != nil {
32-
log.Panic(err)
33-
}
30+
bot, err := tgbotapi.NewBotAPI(os.Getenv("TELEGRAM_APITOKEN"))
31+
if err != nil {
32+
log.Panic(err)
33+
}
3434

35-
bot.Debug = true
35+
bot.Debug = true
3636

37-
log.Printf("Authorized on account %s", bot.Self.UserName)
37+
log.Printf("Authorized on account %s", bot.Self.UserName)
3838

39-
u := tgbotapi.NewUpdate(0)
40-
u.Timeout = 60
39+
u := tgbotapi.NewUpdate(0)
40+
u.Timeout = 60
4141

42-
updates := bot.GetUpdatesChan(u)
42+
updates := bot.GetUpdatesChan(u)
4343

44-
for update := range updates {
45-
if update.Message == nil { // ignore non-Message updates
46-
continue
47-
}
44+
for update := range updates {
45+
if update.Message == nil { // ignore non-Message updates
46+
continue
47+
}
4848

49-
msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
49+
msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
5050

51-
switch update.Message.Text {
52-
case "open":
53-
msg.ReplyMarkup = numericKeyboard
54-
case "close":
55-
msg.ReplyMarkup = tgbotapi.NewRemoveKeyboard(true)
56-
}
51+
switch update.Message.Text {
52+
case "open":
53+
msg.ReplyMarkup = numericKeyboard
54+
case "close":
55+
msg.ReplyMarkup = tgbotapi.NewRemoveKeyboard(true)
56+
}
5757

58-
if _, err := bot.Send(msg); err != nil {
59-
log.Panic(err)
60-
}
61-
}
58+
if _, err := bot.Send(msg); err != nil {
59+
log.Panic(err)
60+
}
61+
}
6262
}
6363
```

‎docs/getting-started/files.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@
33
Telegram supports specifying files in many different formats. In order to
44
accommodate them all, there are multiple structs and type aliases required.
55

6-
| Type | Description |
7-
| ---- | ----------- |
8-
| `string` | Used as a local path to a file |
9-
| `FileID` | Existing file ID on Telegram's servers |
10-
| `FileURL` | URL to file, must be served with expected MIME type |
11-
| `FileReader` | Use an `io.Reader` to provide a file. Lazily read to save memory. |
12-
| `FileBytes` | `[]byte` containing file data. Prefer to use `FileReader` to save memory. |
6+
| Type | Description |
7+
| ------------ | ------------------------------------------------------------------------- |
8+
| `string` | Used as a local path to a file |
9+
| `FileID` | Existing file ID on Telegram's servers |
10+
| `FileURL` | URL to file, must be served with expected MIME type |
11+
| `FileReader` | Use an `io.Reader` to provide a file. Lazily read to save memory. |
12+
| `FileBytes` | `[]byte` containing file data. Prefer to use `FileReader` to save memory. |
1313

1414
## `string`
1515

‎docs/getting-started/important-notes.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Important Notes
2+
3+
The Telegram Bot API has a few potentially unanticipated behaviors. Here are a
4+
few of them. If any behavior was surprising to you, please feel free to open a
5+
pull request!
6+
7+
## Callback Queries
8+
9+
- Every callback query must be answered, even if there is nothing to display to
10+
the user. Failure to do so will show a loading icon on the keyboard until the
11+
operation times out.
12+
13+
## ChatMemberUpdated
14+
15+
- In order to receive `chat_member` and updates, you must explicitly add it to
16+
your `allowed_updates` when getting updates or setting your webhook.
17+
18+
## Entities use UTF16
19+
20+
- When extracting text entities using offsets and lengths, characters can appear
21+
to be in incorrect positions. This is because Telegram uses UTF16 lengths
22+
while Golang uses UTF8. It's possible to convert between the two, see
23+
[issue #231][issue-231] for more details.
24+
25+
[issue-231]: https://github.com/go-telegram-bot-api/telegram-bot-api/issues/231
26+
27+
## GetUpdatesChan
28+
29+
- This method is very basic and likely unsuitable for production use. Consider
30+
creating your own implementation instead, as it's very simple to replicate.
31+
- This method only allows your bot to process one update at a time. You can
32+
spawn goroutines to handle updates concurrently or switch to webhooks instead.
33+
Webhooks are suggested for high traffic bots.
34+
35+
## Nil Updates
36+
37+
- At most one of the fields in an `Update` will be set to a non-nil value. When
38+
evaluating updates, you must make sure you check that the field is not nil
39+
before trying to access any of it's fields.
40+
41+
## User and Chat ID size
42+
43+
- These types require up to 52 significant bits to store correctly, making a
44+
64-bit integer type required in most languages. They are already `int64` types
45+
in this library, but make sure you use correct types when saving them to a
46+
database or passing them to another language.

0 commit comments

Comments
 (0)