telegram

README

Joe Bot - Telegram Adapter

Connecting joe with the Telegram chat application. https://github.com/go-joe/joe

---

This repository contains a module for the Joe Bot library. Built using telegram-bot-api.

Getting Started

This library is packaged using Go modules. You can get it via:

go get github.com/robertgzr/joe-telegram-adapter

Example usage

In order to connect your bot to telegram you can simply pass it as module when creating a new bot:

package main

import (
	"github.com/go-joe/joe"
	"github.com/robertgzr/joe-telegram-adapter"
)

func main() {
	b := joe.New("example-bot",
		telegram.Adapter(os.Getenv("TELEGRAM_BOT_TOKEN")),
		…
	)
	
	b.Respond("ping", Pong)

	err := b.Run()
	if err != nil {
		b.Logger.Fatal(err.Error())
	}
}

For how to create a telegram bot and connect to it, see here.

This adapter will emit the following events to the robot brain:

• joe.ReceiveMessageEvent
• ReceiveCommandEvent

A common use-case is handling Telegram bot commands, /command. To make this easy a custom event type is emitted:

package main

import (
	"github.com/go-joe/joe"
	"github.com/robertgzr/joe-telegram-adapter"
)

type ExampleBot {
    *joe.Bot
}

func main() {
	b := &ExampleBot{
	    Bot: joe.New("example-bot",
		    telegram.Adapter(os.Getenv("TELEGRAM_BOT_TOKEN")),
		    …
	    ),
	}

	b.Brain.RegisterHandler(b.HandleTelegramCommands)
	b.Respond("ping", Pong)

	err := b.Run()
	if err != nil {
		b.Logger.Fatal(err.Error())
	}
}

func (b *ExampleBot) HandleTelegramCommands(ev telegram.ReceiveCommandEvent) error {
	switch ev.Arg0 {
	case "command":
		b.Say(ev.Channel(), "Hello, world!")
		return nil
	default:
		return errors.New("unknown command")
	}
}

Additional features

Some features available via the Bot API is nice to have when writing bots:

tg, ok := Bot.Adapter.(*telegram.TelegramAdapter)

tg.BotAPI allows full access to the Bot API interface.

This package also provides some abstractions for ease of use:

// photo/gif/sticker can be file, FileReader, or FileBytes which will upload a
// new instance; or a string which assumes a telegram fileID
tg.SendPhoto(msg.Channel, photo, "caption")
tg.SendGif(msg.Channel, gif, "caption")
tg.SendSticker(msg.Channel, sticker)

License

BSD-3-Clause

Documentation

Overview

Package telegram implements a joe-bot adapter for the Telegram BotAPI

Index

• func Adapter(token string, opts ...Option) joe.Module
• type Button
• type Callback
• type Config
• type Option
  • func WithLogger(logger *zap.Logger) Option
  • func WithParseMode(mode string) Option
  • func WithUpdateResumeFrom(id int) Option
  • func WithUpdateTimeout(secs int) Option
• type ReceiveCommandEvent
  • func (e ReceiveCommandEvent) Channel() string
• type TelegramAdapter
  • func NewAdapter(ctx context.Context, conf Config) (*TelegramAdapter, error)
  • func (a *TelegramAdapter) Close() error
  • func (a *TelegramAdapter) NewButton(label string, cb Callback) Button
  • func (a *TelegramAdapter) RegisterAt(brain *joe.Brain)
  • func (a *TelegramAdapter) Send(txt, chatIDString string) error
  • func (a *TelegramAdapter) SendButtons(channel, text string, buttons ...Button) error
  • func (a *TelegramAdapter) SendGIF(channel string, gif interface{}, caption string) error
  • func (a *TelegramAdapter) SendPhoto(channel string, photo interface{}, caption string) error
  • func (a *TelegramAdapter) SendSticker(channel string, sticker interface{}) error

Functions

func Adapter

func Adapter(token string, opts ...Option) joe.Module

Adapter returns a joe.Module of the TelegramAdapter

Types

type Button

type Button struct {
	// contains filtered or unexported fields
}

type Callback

type Callback = func(channel string) error

type Config

type Config struct {
	// Token is the token issued by botfather
	// https://core.telegram.org/bots/api#authorizing-your-bot
	Token string
	// UpdateTimeoutSec configures the UpdateCofnig.Timout option of the
	// telegram-bot-api client
	UpdateTimeoutSec int
	// UpdateResumeFrom is the last Update ID to resume from
	// https://core.telegram.org/bots/api#update
	UpdateResumeFrom int
	// ParseMode sets the formatting style for messages the bot sends
	// https://core.telegram.org/bots/api#formatting-options
	ParseMode string

	Logger *zap.Logger
}

Config holds the options pased to the Telegram adapter

type Option

type Option func(*Config) error

func WithLogger

func WithLogger(logger *zap.Logger) Option

WithLogger allows configuring a custom zap.Logger for the adapter to use

func WithParseMode

func WithParseMode(mode string) Option

WithParseMode allows setting the message formatting used by Send

func WithUpdateResumeFrom

func WithUpdateResumeFrom(id int) Option

WithUpdateResumeFrom allows setting the starting Update ID from which to process updates froms.

func WithUpdateTimeout

func WithUpdateTimeout(secs int) Option

WithUpdateTimeout allows configuring the update loop timeout (in seconds)

type ReceiveCommandEvent

type ReceiveCommandEvent struct {
	Arg0 string
	Args []string
	From *tgbotapi.User
	Chat *tgbotapi.Chat
	Data *tgbotapi.Message
}

func (ReceiveCommandEvent) Channel

func (e ReceiveCommandEvent) Channel() string

type TelegramAdapter

type TelegramAdapter struct {
	BotAPI *tgbotapi.BotAPI
	// contains filtered or unexported fields
}

TelegramAdapter is a joe-bot adapter for the Telegram BotAPI

func NewAdapter

func NewAdapter(ctx context.Context, conf Config) (*TelegramAdapter, error)

NewAdapter creates a new instance of the TelegramAdapter

func (*TelegramAdapter) Close

func (a *TelegramAdapter) Close() error

Close finishes processing updates

func (*TelegramAdapter) NewButton

func (a *TelegramAdapter) NewButton(label string, cb Callback) Button

func (*TelegramAdapter) RegisterAt

func (a *TelegramAdapter) RegisterAt(brain *joe.Brain)

RegisterAt implements the joe.Adapter interface by emitting the telegram API events to the given brain

func (*TelegramAdapter) Send

func (a *TelegramAdapter) Send(txt, chatIDString string) error

Send sends a messages (formatted using Config.ParseMode) via the Telegram BotAPI

func (*TelegramAdapter) SendButtons

func (a *TelegramAdapter) SendButtons(channel, text string, buttons ...Button) error

func (*TelegramAdapter) SendGIF

func (a *TelegramAdapter) SendGIF(channel string, gif interface{}, caption string) error

func (*TelegramAdapter) SendPhoto

func (a *TelegramAdapter) SendPhoto(channel string, photo interface{}, caption string) error

func (*TelegramAdapter) SendSticker

func (a *TelegramAdapter) SendSticker(channel string, sticker interface{}) error