gotgbot

README

Go Telegram Bot

This library is WIP; it does not currently support all of the telegram api methods.

This library attempts to create a user-friendly wrapper around the telegram bot api.

Heavily inspired by the python-telegram-bot library, this aims to create a simple way to manage a concurrent and scalable bot.

Getting started

Install it as you would install your usual go library: go get github.com/PaulSonOfLars/gotgbot

A sample bot can be found in sampleBot/. This bot covers the basics of adding a command, a filter, and a regex handler.

An interesting feature to take note of is that due to go's handling of exceptions, if you choose not to handle an exception, your bot will simply keep on going happily and ignore any issues.

All handlers are async; they're all executed in their own go routine, so can communicate accross channels if needed. The reason for the error return for the methods is to allow for passing gotgbot.ContinueGroups{} or gotgbot.EndGroups{}; which will determine whether or not to keep handling methods in that handler group, or stop handling further groups entirely.

Message sending

As seen in the example, message sending can be done in two ways; via each received message's ReplyText() function, or by building your own; and calling msg.Send(). This allows for ease of use by having the most commonly used shortcuts readily available, while retaining the flexibility of building each message yourself, which wouldnt be available otherwise.

Documentation

Index

• Constants
• type ContinueGroups
  • func (eg ContinueGroups) Error() string
• type Dispatcher
  • func NewDispatcher(bot *ext.Bot, updates chan *RawUpdate) *Dispatcher
  • func (d Dispatcher) AddHandler(handler Handler)
  • func (d Dispatcher) AddHandlerToGroup(handler Handler, group int)
  • func (d Dispatcher) Start()
• type EndGroups
  • func (eg EndGroups) Error() string
• type Handler
• type RawUpdate
• type Update
• type Updater
  • func NewUpdater(token string) (*Updater, error)
  • func (u Updater) GetWebhookInfo() (*WebhookInfo, error)
  • func (u Updater) Idle()
  • func (u Updater) RemoveWebhook() (bool, error)
  • func (u Updater) SetWebhook(path string, webhook Webhook) (bool, error)
  • func (u Updater) StartCleanPolling() error
  • func (u Updater) StartPolling() error
  • func (u Updater) StartWebhook(webhook Webhook)
• type Webhook
  • func (w Webhook) GetListenUrl() string
• type WebhookInfo

Constants

const DefaultMaxDispatcherRoutines = 50

Types

type ContinueGroups

type ContinueGroups struct{}

func (ContinueGroups) Error

func (eg ContinueGroups) Error() string

type Dispatcher

type Dispatcher struct {
	Bot         *ext.Bot
	MaxRoutines int
	// contains filtered or unexported fields
}

Dispatcher Store data for the dispatcher to work as expected; such as the incoming update channel, handler mappings and maximum number of goroutines allowed to be run at once

func NewDispatcher

func NewDispatcher(bot *ext.Bot, updates chan *RawUpdate) *Dispatcher

func (Dispatcher) AddHandler

func (d Dispatcher) AddHandler(handler Handler)

AddHandler adds a new handler to the dispatcher. The dispatcher will call CheckUpdate() to see whether the handler should be executed, and then HandleUpdate() to execute it.

func (Dispatcher) AddHandlerToGroup

func (d Dispatcher) AddHandlerToGroup(handler Handler, group int)

AddHandlerToGroup adds a handler to a specific group; lowest number will be processed first.

func (Dispatcher) Start

func (d Dispatcher) Start()

Start Begin dispatching updates

type EndGroups

type EndGroups struct{}

func (EndGroups) Error

func (eg EndGroups) Error() string

type Handler

type Handler interface {
	// HandleUpdate processes the update. The error return can be used to return either EndGroups{} or ContinueGroups{}
	// errors, which allows for either continuing execution of the current group, or stopping all further execution.
	HandleUpdate(u *Update, d Dispatcher) error
	// CheckUpdate checks whether the update should be processes or not.
	CheckUpdate(u *Update) (bool, error)
	// GetName gets the handler name; used to differentiate handlers programmatically.
	GetName() string
}

type RawUpdate

type RawUpdate json.RawMessage

RawUpdate alias to json.RawMessage

type Update

type Update struct {
	UpdateId           int                     `json:"update_id"`
	Message            *ext.Message            `json:"message"`
	EditedMessage      *ext.Message            `json:"edited_message"`
	ChannelPost        *ext.Message            `json:"channel_post"`
	EditedChannelPost  *ext.Message            `json:"edited_channel_post"`
	InlineQuery        *ext.Message            `json:"inline_query"`
	ChosenInlineResult *ext.ChosenInlineResult `json:"chosen_inline_result"`
	CallbackQuery      *ext.CallbackQuery      `json:"callback_query"`
	ShippingQuery      *ext.ShippingQuery      `json:"shipping_query"`
	PreCheckoutQuery   *ext.PreCheckoutQuery   `json:"pre_checkout_query"`
	Poll               *ext.Poll               `json:"poll"`

	// Self added type
	EffectiveMessage *ext.Message `json:"effective_message"`
	EffectiveChat    *ext.Chat    `json:"effective_chat"`
	EffectiveUser    *ext.User    `json:"effective_user"`
	Data             map[string]string
}

Update Incoming updates from telegram servers (including extra, internally used fields added for convenience)

type Updater

type Updater struct {
	Bot          *ext.Bot
	Updates      chan *RawUpdate
	Dispatcher   *Dispatcher
	UpdateGetter *ext.TgBotGetter
}

Updater The main updater process. Receives incoming updates, then sends them to the dispatcher goroutine via an update channel for them to be handled.

func NewUpdater

func NewUpdater(token string) (*Updater, error)

NewUpdater Creates a new updater struct, paired with the necessary dispatcher and bot structs.

func (Updater) GetWebhookInfo

func (u Updater) GetWebhookInfo() (*WebhookInfo, error)

GetWebhookInfo Get webhook info from telegram servers

func (Updater) Idle

func (u Updater) Idle()

Idle sets the main thread to idle, allowing the background processes to run as expected (dispatcher and update handlers)

func (Updater) RemoveWebhook

func (u Updater) RemoveWebhook() (bool, error)

RemoveWebhook remove the webhook url from telegram servers

func (Updater) SetWebhook

func (u Updater) SetWebhook(path string, webhook Webhook) (bool, error)

SetWebhook Set the webhook url for telegram to contact with updates

func (Updater) StartCleanPolling

func (u Updater) StartCleanPolling() error

StartCleanPolling Starts clean polling (ignoring stale updates)

func (Updater) StartPolling

func (u Updater) StartPolling() error

StartPolling Starts the polling logic

func (Updater) StartWebhook

func (u Updater) StartWebhook(webhook Webhook)

StartWebhook Start the webhook server

type Webhook

type Webhook struct {
	Serve     string // base url to where you listen
	ServePath string // path you listen to
	ServePort int    // port you listen on
	URL       string // where you set the webhook to send to
	// CertPath       string   // TODO
	MaxConnections int      // max connections; max 100, default 40
	AllowedUpdates []string // which updates to allow
}

func (Webhook) GetListenUrl

func (w Webhook) GetListenUrl() string

type WebhookInfo

type WebhookInfo struct {
	URL                  string   `json:"url"`
	HasCustomCertificate bool     `json:"has_custom_certificate"`
	PendingUpdateCount   int      `json:"pending_update_count"`
	LastErrorDate        int      `json:"last_error_date"`
	LastErrorMessage     int      `json:"last_error_message"`
	MaxConnections       int      `json:"max_connections"`
	AllowedUpdates       []string `json:"allowed_updates"`
}