Flexible message router add-on for go-telegram-bot-api library.

Overview

telemux

Flexible message router add-on for go-telegram-bot-api library.

GitHub tag Go Reference Build Status Maintainability Go Report Card stability-unstable

Screenshot

Table of contents

Motivation

This library serves as an addition to the go-telegram-bot-api library. I strongly recommend you to take a look at it since telemux is mostly an extension to it.

Patterns such as handlers, persistence & filters were inspired by a wonderful python-telegram-bot library.

This project is in early beta stage. Contributions are welcome! Feel free to submit an issue if you have any questions, suggestions or simply want to help.

Features

Minimal example

package main

import (
    tm "github.com/and3rson/telemux"
    tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api"
    "log"
    "os"
)

func main() {
    // This part is a boilerplate from go-telegram-bot-api library.
    bot, _ := tgbotapi.NewBotAPI(os.Getenv("TG_TOKEN"))
    bot.Debug = true
    u := tgbotapi.NewUpdate(0)
    u.Timeout = 60
    updates, _ := bot.GetUpdatesChan(u)

    // Create a multiplexer with two handlers: one for command and one for all messages.
    // If a handler cannot handle the update (fails the filter),
    // multiplexer will proceed to the next handler.
    mux := tm.NewMux().
        AddHandler(tm.NewHandler(
            tm.IsCommandMessage("start"),
            func(u *tm.Update) {
                bot.Send(tgbotapi.NewMessage(u.Message.Chat.ID, "Hello! Say something. :)"))
            },
        )).
        AddHandler(tm.NewHandler(
            tm.Any(),
            func(u *tm.Update) {
                bot.Send(tgbotapi.NewMessage(u.Message.Chat.ID, "You said: "+u.Message.Text))
            },
        ))
    // Dispatch all telegram updates to multiplexer
    for update := range updates {
        mux.Dispatch(update)
    }
}

Documentation

The documentation is available here.

Examples are available here.

Changelog

Changelog is available here.

Terminology

Mux

Mux (multiplexer) is a "router" for instances of tgbotapi.Update.

It allows you to register handlers and will take care to choose an appropriate handler based on the incoming update.

In order to work, you must dispatch messages (that come from go-telegram-bot-api channel):

mux := tm.NewMux()
// ...
// add handlers to mux here
// ...
updates, _ := bot.GetUpdatesChan(u)
for update := range updates {
    mux.Dispatch(update)
}

Handlers & filters

Handler consists of filter and handle-function.

Handler's filter decides whether this handler can handle the incoming update. If so, handle-function is called. Otherwise multiplexer will proceed to the next handler.

Filters are divided in two groups: content filters (starting with "Has", such as HasPhoto(), HasAudio(), HasSticker() etc) and update type filters (starting with "Is", such as IsEditedMessage(), IsInlineQuery() or IsGroupOrSuperGroup()).

There is also a special filter Any() which makes handler accept all updates.

Filters can be chained using And, Or, and Not meta-filters. For example:

mux := tm.NewMux()

// Add handler that accepts photos sent to the bot in a private chat:
mux.AddHandler(And(tm.IsPrivate(), tm.HasPhoto()), func(u *tm.Update) { /* ... */ })

// Add handler that accepts photos and text messages:
mux.AddHandler(Or(tm.HasText(), tm.HasPhoto()), func(u *tm.Update) { /* ... */ })

// Since filters are plain functions, you can easily implement them yourself.
// Below we add handler that allows onle a specific user to call "/restart" command:
mux.AddHandler(tm.NewHandler(
    tm.And(tm.IsCommandMessage("restart"), func(u *tm.Update) bool {
        return u.Message.From.ID == 3442691337
    }),
    func(u *tm.Update) { /* ... */ },
))

If you want your handler to be executed in a goroutine, use tm.NewAsyncHandler. It's similar to wrapping a handler function in an anonymous goroutine invocation:

mux := tm.NewMux()
// Option 1: using NewAsyncHandler
mux.AddHandler(tm.NewAsyncHandler(
    tm.IsCommandMessage("do_work"),
    func(u *tm.Update) {
        // Slow operation
    },
))
// Option 2: wrapping manually
mus.AddHandler(tm.NewHandler(
    tm.IsCommandMessage("do_work"),
    func(u *tm.Update) {
        go func() {
            // Slow operation
        }
    },
))

Conversations & persistence

Conversations are handlers on steroids based on the finite-state machine pattern.

They allow you to have complex dialog interactions with different handlers.

Persistence interface tells conversation where to store & how to retrieve the current state of the conversation, i. e. which "step" the given user is currently at.

To create a ConversationHandler you need to provide the following:

  • conversationID string - identifier that distinguishes this conversation from the others.

    The main goal of this identifier is to allow persistence to keep track of different conversation states independently without mixing them together.

  • persistence Persistence - defines where to store conversation state & intermediate inputs from the user.

    Without persistence, a conversation would not be able to "remember" what "step" the user is at.

    Persistence is also useful when you want to collect some data from the user step-by-step).

    Two convenient implementations of Persistence are available out of the box: LocalPersistence & FilePersistence.

  • states map[string][]*TransitionHandler - defines which TransitionHandlers to use in what state.

    States are usually strings like "upload_photo", "send_confirmation", "wait_for_text" and describe the "step" the user is currently at. It's recommended to have an empty string ("") as an initial state (i. e. if the conversation has not started yet or has already finished.)

    For each state you can provide a list of at least one TransitionHandler. If none of the handlers can handle the update, the default handlers are attempted (see below).

    In order to switch to a different state your TransitionHandler must call ctx.SetState("STATE_NAME") replacing STATE_NAME with the name of the state you want to switch into.

    Conversation data can be accessed with ctx.GetData() and updated with ctx.SetData(newData).

  • defaults []*TransitionHandler - these handlers are "appended" to every state.

    Useful to handle commands such as "/cancel" or to display some default message.

See ./examples/album_conversation/main.go for a conversation example.

Error handling

By default, panics in handlers are propagated all the way to the top (Dispatch method).

In order to intercept all panics in your handlers globally and handle them gracefully, register your function using SetRecoverer:

mux := tm.NewMux()
# ...
mux.SetRecoverer(func(u *tm.Update, err error) {
    fmt.Printf("An error occured: %s", err)
})

Tips & common pitfalls

tgbotapi.Update vs tm.Update confusion

Since Update struct from go-telegram-bot-api already provides most of the functionality, telemux implements its own Update struct which embeds the Update from go-telegram-bot-api. Main reason for this is to add some extra convenient methods.

Getting user/chat/message object from update

When having handlers for wide filters (e. g. Or(And(HasText(), IsEditedMessage()), IsInlineQuery())) you may often fall in situations when you need to check for multiple user/chat/message attributes. In such situations sender's data may be in one of few places depending on which update has arrived: u.Message.From, u.EditedMessage.From, or u.InlineQuery.From. Similar issue applies to fetching actual chat info or message object from an update.

In such cases it's highly recommended to use functions such as EffectiveChat() (see the update module for more info):

// Bad:
fmt.Println(u.Message.Chat.ID) // u.Message may be nil

// Better, but not so DRY:
chatId int64
if u.Message != nil {
    chatId = u.Message.Chat.ID
} else if u.EditedMessage != nil {
    chatId = u.EditedMessage.Chat.ID
} else if u.CallbackQuery != nil {
    chatId = u.CallbackQuery.Chat.ID
} // And so on... Duh.
fmt.Println(chatId)

// Best:
chat := u.EffectiveChat()
if chat != nil {
    fmt.Println(chat.ID)
}

Properly filtering updates

Keep in mind that using content filters such as HasText(), HasPhoto(), HasLocation(), HasVoice() etc does not guarantee that the Update describes an actual new message. In fact, an Update also happens when a user edits his message! Thus your handler will be executed even if a user just edited one of his messages.

To avoid situations like these, make sure to use filters such as IsMessage(), IsEditedMessage(), IsCallbackQuery() etc in conjunction with content filters. For example:

tm.NewHandler(HasText(), func(u *tm.Update) { /* ... */ }) // Will handle new messages, updated messages, channel posts & channel post edits which contain text
tm.NewHandler(And(IsMessage(), HasText()), func(u *tm.Update) { /* ... */ }) // Will handle new messages that contain text
tm.NewHandler(And(IsEditedMessage(), HasText()), func(u *tm.Update) { /* ... */ }) // Will handle edited that which contain text

The only exceptions are IsCommandMessage("...") and IsAnyCommandMessage() filters. Since it does not make sense to react to edited messages that contain commands, this filter also checks if the update designates a new message and not an edited message, inline query, callback query etc. This means you can safely use IsCommandMessage("my_command") without joining it with the IsMessage() filter:

IsCommandMessage("my_command") // OK: IsCommand() already checks for IsMessage()
And(IsCommandMessage("start"), IsMessage()) // IsMessage() is unnecessary
And(IsCommandMessage("start"), Not(IsEditedMessage())) // Not(IsEditedMessage()) is unnecessary
Issues
Owner
Andrew Dunai
Codin' around.
Andrew Dunai
Telegram Bot Framework for Go

Margelet Telegram Bot Framework for Go is based on telegram-bot-api It uses Redis to store it's states, configs and so on. Any low-level interactions

Gleb Sinyavskiy 63 Jul 27, 2021
easy-peasy wg tg bot

wireguard-telegram-bot Simple-Dimple Telegram Bot for Wireguard VPN config generation Functionality /menu — list available commands /newkeys — create

Sergey Skaredov 12 Sep 17, 2021
Slack Bot Framework

slacker Built on top of the Slack API github.com/slack-go/slack with the idea to simplify the Real-Time Messaging feature to easily create Slack Bots,

Raed Shomali 554 Sep 16, 2021
Golang bindings for the Telegram Bot API

Golang bindings for the Telegram Bot API All methods are fairly self explanatory, and reading the godoc page should explain everything. If something i

null 3.1k Sep 21, 2021
Telebot is a Telegram bot framework in Go.

Telebot "I never knew creating Telegram bots could be so sexy!" go get -u gopkg.in/tucnak/telebot.v2 Overview Getting Started Poller Commands Files Se

Ian P Badtrousers 2.1k Sep 21, 2021
A bot that greets new members on telegram groups with a cute, personalised gif.

Telegram-senko-bot About The Bot This bot greets new members on telegram groups with a cute, personalised gif with Senko-san. In case you're wondering

4kaze 5 Sep 16, 2021
Bot that polls activity API for Github organisation and pushes updates to Telegram.

git-telegram-bot Telegram bot for notifying org events Requirements (for building) Go version 1.16.x Setup If you don't have a telegram bot token yet,

Skycoin 3 May 13, 2021
Instagram to Telegram Channel Bot.

InstaTG Instagram to Telegram Channel Bot. Can access posts from any public Instagram account or an account that you follow. Features Keeps track of e

Anchit Bajaj 4 Sep 11, 2021
Full-native go implementation of Telegram API

MTProto Full-native implementation of MTProto protocol on Golang! english русский 简体中文 Features Full native implementation All code, from sending requ

Xelaj technologies 684 Sep 18, 2021
Chatto is a minimal chatbot framework in Go.

chatto Simple chatbot framework written in Go, with configurations in YAML. The aim of this project is to create very simple text-based chatbots using

Jaime Tenorio 89 Sep 5, 2021
A tip bot and Lightning wallet on Telegram ⚡️

@LightningTipBot ?? A Telegram Lightning ⚡️ Bitcoin wallet and tip bot for group chats. This repository contains everything you need to set up and run

null 9 Sep 14, 2021
A lightweight, universal cloud drive upload tool for all platforms

简体中文 LightUploader MoeClub wrote a very good version, but unfortunately it's not open source and hasn't been updated in a while. This project is a sim

高玩梁 194 Sep 22, 2021
Signum Explorer Telegram Bot - it's a simplified version of the web Signum Explorer

Signum Explorer Telegram Bot - it's a simplified version of the web Signum Explorer. Bot allows you to easily monitor the status of your account and to receive notifications about new transactions and blocks.

Anatoliy Bezgubenko 26 Sep 23, 2021
Golang telegram bot API wrapper, session-based router and middleware

go-tgbot Pure Golang telegram bot API wrapper generated from swagger definition, session-based routing and middlewares. Usage benefits No need to lear

Oleg Lebedev 107 Sep 8, 2021
The modern cryptocurrency trading bot written in Go.

bbgo A trading bot framework written in Go. The name bbgo comes from the BB8 bot in the Star Wars movie. aka Buy BitCoin Go! Current Status Features E

Yo-An Lin 346 Sep 6, 2021
Kelp is a free and open-source trading bot for the Stellar DEX and 100+ centralized exchanges

Kelp Kelp is a free and open-source trading bot for the Stellar universal marketplace and for centralized exchanges such as Binance, Kraken, CoinbaseP

Stellar 748 Sep 23, 2021
A golang implementation of a console-based trading bot for cryptocurrency exchanges

Golang Crypto Trading Bot A golang implementation of a console-based trading bot for cryptocurrency exchanges. Usage Download a release or directly bu

Alessandro Sanino 601 Sep 18, 2021
A telegram bot that fetches multiple RSS cryptocurrency news feeds for sentiment analysis

Crypto News Telegram Bot A simple telegram bot that will help you stay updated on your latest crypto news This bot will help you keep track of the lat

Cha 4 Aug 22, 2021
A Telegram Repo For Bots Under Maintenance Which Gives Faster Response To Users

Maintenance Bot A Telegram Repo For Bots Under Maintenance Which Gives Faster Response To Users Requests » Report a Bug | Request Feature Table of Con

HEIMAN PICTURES 7 Aug 4, 2021