echotron
       |
|---|
Echotron is a concurrent library for telegram bots written in pure Go.
Fetch with
go get github.com/NicoNex/echotron/v3
Design
Echotron is heavily based on concurrency: for example, every call to the Update method of each bot is executed on a different goroutine. This makes sure that, even if one instance of the bot is deadlocked, the other ones keep running just fine, making the bot work for other users without any issues and/or slowdowns.
Echotron is designed to be as similar to the official Telegram API as possible, but there are some things to take into account before starting to work with this library.
- The methods have the exact same name, but with a capital first letter, since in Go methods have to start with a capital letter to be exported. Example:
sendMessagebecomesSendMessage - The order of the parameters in some methods is different than in the official Telegram API, so refer to the docs for the correct one.
- The only
chat_id(or, in this case,chatID) type supported isint64, instead of the "Integer or String" requirement of the official API. That's because numeric IDs can't change in any way, which isn't the case with text-based usernames. - In some methods, you might find a
InputFiletype parameter.InputFileis a struct with unexported fields, since only three combination of fields are valid, which can be obtained through the methodsNewInputFileID,NewInputFilePathandNewInputFileBytes. - In some methods, you might find a
MessageIDOptionstype parameter.MessageIDOptionsis another struct with unexported fields, since only two combination of field are valid, which can be obtained through the methodsNewMessageIDandNewInlineMessageID. - Optional parameters can be added by passing the correct struct to each method that might request optional parameters. If you don't want to pass any optional parameter,
nilis more than enough. Refer to the docs to check for each method's optional parameters struct: it's the type of theoptsparameter. - Some parameters are hardcoded to avoid putting random stuff which isn't recognized by the Telegram API. Some notable examples are
ParseMode,ChatActionandInlineQueryType. For a full list of custom hardcoded parameters, refer to the docs for each custom type: by clicking on the type's name, you'll get the source which contains the possible values for that type.
Usage
Long Polling
A very simple implementation:
package main
import (
"log"
"github.com/NicoNex/echotron/v3"
)
type bot struct {
chatID int64
echotron.API
}
const token = "YOUR TELEGRAM TOKEN"
func newBot(chatID int64) echotron.Bot {
return &bot{
chatID,
echotron.NewAPI(token),
}
}
func (b *bot) Update(update *echotron.Update) {
if update.Message.Text == "/start" {
b.SendMessage("Hello world", b.chatID, nil)
}
}
func main() {
dsp := echotron.NewDispatcher(token, newBot)
log.Println(dsp.Poll())
}
Proof of concept with self destruction for low RAM usage:
package main
import (
"log"
"time"
"github.com/NicoNex/echotron/v3"
)
type bot struct {
chatID int64
echotron.API
}
const token = "YOUR TELEGRAM TOKEN"
var dsp echotron.Dispatcher
func newBot(chatID int64) echotron.Bot {
var bot = &bot{
chatID,
echotron.NewAPI(token),
}
go bot.selfDestruct(time.After(time.Hour))
return bot
}
func (b *bot) selfDestruct(timech <- chan time.Time) {
select {
case <-timech:
b.SendMessage("goodbye", b.chatID, nil)
dsp.DelSession(b.chatID)
}
}
func (b *bot) Update(update *echotron.Update) {
if update.Message.Text == "/start" {
b.SendMessage("Hello world", b.chatId, nil)
}
}
func main() {
dsp := echotron.NewDispatcher(token, newBot)
log.Println(dsp.Poll())
}
Webhook
package main
import "github.com/NicoNex/echotron/v3"
type bot struct {
chatID int64
echotron.API
}
const token = "YOUR TELEGRAM TOKEN"
func newBot(chatID int64) echotron.Bot {
return &bot{
chatID,
echotron.NewAPI(token),
}
}
func (b *bot) Update(update *echotron.Update) {
if update.Message.Text == "/start" {
b.SendMessage("Hello world", b.chatID, nil)
}
}
func main() {
dsp := echotron.NewDispatcher(token, newBot)
dsp.ListenWebhook("https://example.com:443/my_bot_token")
}
Webhook with a custom http.Server
This is an example for a custom http.Server which handles your own specified routes and also the webhook route which is specified by ListenWebhook.
package main
import (
"github.com/NicoNex/echotron/v3"
"context"
"log"
"net/http"
)
type bot struct {
chatID int64
echotron.API
}
const token = "YOUR TELEGRAM TOKEN"
func newBot(chatID int64) echotron.Bot {
return &bot{
chatID,
echotron.NewAPI(token),
}
}
func (b *bot) Update(update *echotron.Update) {
if update.Message.Text == "/start" {
b.SendMessage("Hello world", b.chatID, nil)
}
}
func main() {
termChan := make(chan os.Signal, 1) // Channel for terminating the app via os.Interrupt signal
signal.Notify(termChan, syscall.SIGINT, syscall.SIGTERM)
mux := http.NewServeMux()
mux.HandleFunc("/login", func(w http.ResponseWriter, r *http.Request) {
// Handle user login
})
mux.HandleFunc("/logout", func(w http.ResponseWriter, r *http.Request) {
// Handle user logout
})
mux.HandleFunc("/about", func(w http.ResponseWriter, r *http.Request) {
// Tell something about your awesome telegram bot
})
// Set custom http.Server
server := &http.Server{Addr: ":8080", Handler: mux}
go func() {
<-termChan
// Perform some cleanup..
if err := server.Shutdown(context.Background()); err != nil {
log.Print(err)
}
}()
// Capture the interrupt signal for app termination handling
dsp := echotron.NewDispatcher(token, newBot)
dsp.SetHTTPServer(server)
// Start your custom http.Server with a registered /my_bot_token handler.
log.Println(dsp.ListenWebhook("https://example.com/my_bot_token"))
}
