telebot

package module
v2.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 8, 2021 License: MIT Imports: 18 Imported by: 475

README

Telebot

"I never knew creating Telegram bots could be so sexy!"

GoDoc Travis codecov.io Discuss on Telegram

go get -u gopkg.in/tucnak/telebot.v2

Overview

Telebot is a bot framework for Telegram Bot API. This package provides the best of its kind API for command routing, inline query requests and keyboards, as well as callbacks. Actually, I went a couple steps further, so instead of making a 1:1 API wrapper I chose to focus on the beauty of API and performance. Some of the strong sides of telebot are:

  • Real concise API
  • Command routing
  • Middleware
  • Transparent File API
  • Effortless bot callbacks

All the methods of telebot API are extremely easy to memorize and get used to. Also, consider Telebot a highload-ready solution. I'll test and benchmark the most popular actions and if necessary, optimize against them without sacrificing API quality.

Getting Started

Let's take a look at the minimal telebot setup:

package main

import (
	"log"
	"time"

	tb "gopkg.in/tucnak/telebot.v2"
)

func main() {
	b, err := tb.NewBot(tb.Settings{
		// You can also set custom API URL.
		// If field is empty it equals to "https://api.telegram.org".
		URL: "http://195.129.111.17:8012",

		Token:  "TOKEN_HERE",
		Poller: &tb.LongPoller{Timeout: 10 * time.Second},
	})

	if err != nil {
		log.Fatal(err)
		return
	}

	b.Handle("/hello", func(m *tb.Message) {
		b.Send(m.Sender, "Hello World!")
	})

	b.Start()
}

Simple, innit? Telebot's routing system takes care of delivering updates to their endpoints, so in order to get to handle any meaningful event, all you got to do is just plug your function to one of the Telebot-provided endpoints. You can find the full list here.

b, _ := tb.NewBot(settings)

b.Handle(tb.OnText, func(m *tb.Message) {
	// all the text messages that weren't
	// captured by existing handlers
})

b.Handle(tb.OnPhoto, func(m *tb.Message) {
	// photos only
})

b.Handle(tb.OnChannelPost, func (m *tb.Message) {
	// channel posts only
})

b.Handle(tb.OnQuery, func (q *tb.Query) {
	// incoming inline queries
})

There's dozens of supported endpoints (see package consts). Let me know if you'd like to see some endpoint or endpoint idea implemented. This system is completely extensible, so I can introduce them without breaking backwards-compatibility.

Poller

Telebot doesn't really care how you provide it with incoming updates, as long as you set it up with a Poller, or call ProcessUpdate for each update (see examples/awslambdaechobot):

// Poller is a provider of Updates.
//
// All pollers must implement Poll(), which accepts bot
// pointer and subscription channel and start polling
// synchronously straight away.
type Poller interface {
	// Poll is supposed to take the bot object
	// subscription channel and start polling
	// for Updates immediately.
	//
	// Poller must listen for stop constantly and close
	// it as soon as it's done polling.
	Poll(b *Bot, updates chan Update, stop chan struct{})
}

Telegram Bot API supports long polling and webhook integration. Poller means you can plug telebot into whatever existing bot infrastructure (load balancers?) you need, if you need to. Another great thing about pollers is that you can chain them, making some sort of middleware:

poller := &tb.LongPoller{Timeout: 15 * time.Second}
spamProtected := tb.NewMiddlewarePoller(poller, func(upd *tb.Update) bool {
	if upd.Message == nil {
		return true
	}

	if strings.Contains(upd.Message.Text, "spam") {
		return false
	}

	return true
})

bot, _ := tb.NewBot(tb.Settings{
	// ...
	Poller: spamProtected,
})

// graceful shutdown
time.AfterFunc(N * time.Second, b.Stop)

// blocks until shutdown
bot.Start()

fmt.Println(poller.LastUpdateID) // 134237

Commands

When handling commands, Telebot supports both direct (/command) and group-like syntax (/command@botname) and will never deliver messages addressed to some other bot, even if privacy mode is off. For simplified deep-linking, telebot also extracts payload:

// Command: /start <PAYLOAD>
b.Handle("/start", func(m *tb.Message) {
	if !m.Private() {
		return
	}

	fmt.Println(m.Payload) // <PAYLOAD>
})

Files

Telegram allows files up to 20 MB in size.

Telebot allows to both upload (from disk / by URL) and download (from Telegram) and files in bot's scope. Also, sending any kind of media with a File created from disk will upload the file to Telegram automatically:

a := &tb.Audio{File: tb.FromDisk("file.ogg")}

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // false

// Will upload the file from disk and send it to recipient
bot.Send(recipient, a)

// Next time you'll be sending this very *Audio, Telebot won't
// re-upload the same file but rather utilize its Telegram FileID
bot.Send(otherRecipient, a)

fmt.Println(a.OnDisk()) // true
fmt.Println(a.InCloud()) // true
fmt.Println(a.FileID) // <telegram file id: ABC-DEF1234ghIkl-zyx57W2v1u123ew11>

You might want to save certain Files in order to avoid re-uploading. Feel free to marshal them into whatever format, File only contain public fields, so no data will ever be lost.

Sendable

Send is undoubtedly the most important method in Telebot. Send() accepts a Recipient (could be user, group or a channel) and a Sendable. Other types other than the telebot-provided media types (Photo, Audio, Video, etc.) are Sendable. If you create composite types of your own, and they satisfy the Sendable interface, Telebot will be able to send them out.

// Sendable is any object that can send itself.
//
// This is pretty cool, since it lets bots implement
// custom Sendables for complex kinds of media or
// chat objects spanning across multiple messages.
type Sendable interface {
	Send(*Bot, Recipient, *SendOptions) (*Message, error)
}

The only type at the time that doesn't fit Send() is Album and there is a reason for that. Albums were added not so long ago, so they are slightly quirky for backwards compatibilities sake. In fact, an Album can be sent, but never received. Instead, Telegram returns a []Message, one for each media object in the album:

p := &tb.Photo{File: tb.FromDisk("chicken.jpg")}
v := &tb.Video{File: tb.FromURL("http://video.mp4")}

msgs, err := b.SendAlbum(user, tb.Album{p, v})
Send options

Send options are objects and flags you can pass to Send(), Edit() and friends as optional arguments (following the recipient and the text/media). The most important one is called SendOptions, it lets you control all the properties of the message supported by Telegram. The only drawback is that it's rather inconvenient to use at times, so Send() supports multiple shorthands:

// regular send options
b.Send(user, "text", &tb.SendOptions{
	// ...
})

// ReplyMarkup is a part of SendOptions,
// but often it's the only option you need
b.Send(user, "text", &tb.ReplyMarkup{
	// ...
})

// flags: no notification && no web link preview
b.Send(user, "text", tb.Silent, tb.NoPreview)

Full list of supported option-flags you can find here.

Editable

If you want to edit some existing message, you don't really need to store the original *Message object. In fact, upon edit, Telegram only requires chat_id and message_id. So you don't really need the Message as the whole. Also you might want to store references to certain messages in the database, so I thought it made sense for any Go struct to be editable as a Telegram message, to implement Editable:

// Editable is an interface for all objects that
// provide "message signature", a pair of 32-bit
// message ID and 64-bit chat ID, both required
// for edit operations.
//
// Use case: DB model struct for messages to-be
// edited with, say two columns: msg_id,chat_id
// could easily implement MessageSig() making
// instances of stored messages editable.
type Editable interface {
	// MessageSig is a "message signature".
	//
	// For inline messages, return chatID = 0.
	MessageSig() (messageID string, chatID int64)
}

For example, Message type is Editable. Here is the implementation of StoredMessage type, provided by telebot:

// StoredMessage is an example struct suitable for being
// stored in the database as-is or being embedded into
// a larger struct, which is often the case (you might
// want to store some metadata alongside, or might not.)
type StoredMessage struct {
	MessageID string `sql:"message_id" json:"message_id"`
	ChatID    int64  `sql:"chat_id" json:"chat_id"`
}

func (x StoredMessage) MessageSig() (string, int64) {
	return x.MessageID, x.ChatID
}

Why bother at all? Well, it allows you to do things like this:

// just two integer columns in the database
var msgs []tb.StoredMessage
db.Find(&msgs) // gorm syntax

for _, msg := range msgs {
	bot.Edit(&msg, "Updated text")
	// or
	bot.Delete(&msg)
}

I find it incredibly neat. Worth noting, at this point of time there exists another method in the Edit family, EditCaption() which is of a pretty rare use, so I didn't bother including it to Edit(), just like I did with SendAlbum() as it would inevitably lead to unnecessary complications.

var m *Message

// change caption of a photo, audio, etc.
bot.EditCaption(m, "new caption")

Keyboards

Telebot supports both kinds of keyboards Telegram provides: reply and inline keyboards. Any button can also act as an endpoints for Handle().

In v2.2 we're introducing a little more convenient way in building keyboards. The main goal is to avoid a lot of boilerplate and to make code clearer.

func main() {
	b, _ := tb.NewBot(tb.Settings{...})

	var (
		// Universal markup builders.
		menu     = &tb.ReplyMarkup{ResizeReplyKeyboard: true}
		selector = &tb.ReplyMarkup{}

		// Reply buttons.
		btnHelp     = menu.Text("ℹ Help")
		btnSettings = menu.Text("⚙ Settings")

		// Inline buttons.
		//
		// Pressing it will cause the client to
		// send the bot a callback.
		//
		// Make sure Unique stays unique as per button kind,
		// as it has to be for callback routing to work.
		//
		btnPrev = selector.Data("⬅", "prev", ...)
		btnNext = selector.Data("➡", "next", ...)
	)

	menu.Reply(
		menu.Row(btnHelp),
		menu.Row(btnSettings),
	)
	selector.Inline(
		selector.Row(btnPrev, btnNext),
	)

	// Command: /start <PAYLOAD>
	b.Handle("/start", func(m *tb.Message) {
		if !m.Private() {
			return
		}

		b.Send(m.Sender, "Hello!", menu)
	})

	// On reply button pressed (message)
	b.Handle(&btnHelp, func(m *tb.Message) {...})

	// On inline button pressed (callback)
	b.Handle(&btnPrev, func(c *tb.Callback) {
		// ...
		// Always respond!
		b.Respond(c, &tb.CallbackResponse{...})
	})

	b.Start()
}

You can use markup constructor for every type of possible buttons:

r := &tb.ReplyMarkup{}

// Reply buttons:
r.Text("Hello!")
r.Contact("Send phone number")
r.Location("Send location")
r.Poll(tb.PollQuiz)

// Inline buttons:
r.Data("Show help", "help") // data is optional
r.Data("Delete item", "delete", item.ID)
r.URL("Visit", "https://google.com")
r.Query("Search", query)
r.QueryChat("Share", query)
r.Login("Login", &tb.Login{...})

Inline mode

So if you want to handle incoming inline queries you better plug the tb.OnQuery endpoint and then use the Answer() method to send a list of inline queries back. I think at the time of writing, telebot supports all of the provided result types (but not the cached ones). This is how it looks like:

b.Handle(tb.OnQuery, func(q *tb.Query) {
	urls := []string{
		"http://photo.jpg",
		"http://photo2.jpg",
	}

	results := make(tb.Results, len(urls)) // []tb.Result
	for i, url := range urls {
		result := &tb.PhotoResult{
			URL: url,

			// required for photos
			ThumbURL: url,
		}

		results[i] = result
		// needed to set a unique string ID for each result
		results[i].SetResultID(strconv.Itoa(i))
	}

	err := b.Answer(q, &tb.QueryResponse{
		Results:   results,
		CacheTime: 60, // a minute
	})

	if err != nil {
		log.Println(err)
	}
})

There's not much to talk about really. It also supports some form of authentication through deep-linking. For that, use fields SwitchPMText and SwitchPMParameter of QueryResponse.

Contributing

  1. Fork it
  2. Clone develop: git clone -b develop https://github.com/tucnak/telebot
  3. Create your feature branch: git checkout -b new-feature
  4. Make changes and add them: git add .
  5. Commit: git commit -m "Add some feature"
  6. Push: git push origin new-feature
  7. Pull request

Donate

I do coding for fun but I also try to search for interesting solutions and optimize them as much as possible. If you feel like it's a good piece of software, I wouldn't mind a tip!

Litecoin: ltc1qskt5ltrtyg7esfjm0ftx6jnacwffhpzpqmerus

Ethereum: 0xB78A2Ac1D83a0aD0b993046F9fDEfC5e619efCAB

License

Telebot is distributed under MIT.

Documentation

Overview

Package telebot is a framework for Telegram bots.

Example: 

package main

import (
	"time"
	tb "gopkg.in/tucnak/telebot.v2"
)

func main() {
	b, err := tb.NewBot(tb.Settings{
		Token: "TOKEN_HERE",
		Poller: &tb.LongPoller{Timeout: 10 * time.Second},
	})

	if err != nil {
		return
	}

	b.Handle(tb.OnText, func(m *tb.Message) {
		b.Send(m.Sender, "hello world")
	})

	b.Start()
}

Index

Constants

View Source 
const (
	// Basic message handlers.
	//
	// Handler: func(*Message)
	OnText              = "\atext"
	OnPhoto             = "\aphoto"
	OnAudio             = "\aaudio"
	OnAnimation         = "\aanimation"
	OnDocument          = "\adocument"
	OnSticker           = "\asticker"
	OnVideo             = "\avideo"
	OnVoice             = "\avoice"
	OnVideoNote         = "\avideo_note"
	OnContact           = "\acontact"
	OnLocation          = "\alocation"
	OnVenue             = "\avenue"
	OnEdited            = "\aedited"
	OnPinned            = "\apinned"
	OnChannelPost       = "\achan_post"
	OnEditedChannelPost = "\achan_edited_post"
	OnDice              = "\adice"
	OnInvoice           = "\ainvoice"
	OnPayment           = "\apayment"
	OnGame              = "\agame"

	// Will fire when bot is added to a group.
	OnAddedToGroup = "\aadded_to_group"

	// Group events:
	OnUserJoined        = "\auser_joined"
	OnUserLeft          = "\auser_left"
	OnNewGroupTitle     = "\anew_chat_title"
	OnNewGroupPhoto     = "\anew_chat_photo"
	OnGroupPhotoDeleted = "\achat_photo_del"
	OnGroupCreated      = "\agroup_created"
	OnSuperGroupCreated = "\asupergroup_created"
	OnChannelCreated    = "\achannel_created"

	// Migration happens when group switches to
	// a supergroup. You might want to update
	// your internal references to this chat
	// upon switching as its ID will change.
	//
	// Handler: func(from, to int64)
	OnMigration = "\amigration"

	// Will fire on callback requests.
	//
	// Handler: func(*Callback)
	OnCallback = "\acallback"

	// Will fire on incoming inline queries.
	//
	// Handler: func(*Query)
	OnQuery = "\aquery"

	// Will fire on chosen inline results.
	//
	// Handler: func(*ChosenInlineResult)
	OnChosenInlineResult = "\achosen_inline_result"

	// Will fire on ShippingQuery.
	//
	// Handler: func(*ShippingQuery)
	OnShipping = "\ashipping_query"

	// Will fire on PreCheckoutQuery.
	//
	// Handler: func(*PreCheckoutQuery)
	OnCheckout = "\apre_checkout_query"

	// Will fire on Poll.
	//
	// Handler: func(*Poll)
	OnPoll = "\apoll"

	// Will fire on PollAnswer.
	//
	// Handler: func(*PollAnswer)
	OnPollAnswer = "\apoll_answer"

	// Will fire on MyChatMember
	//
	// Handler: func(*ChatMemberUpdated)
	OnMyChatMember = "\amy_chat_member"

	// Will fire on ChatMember
	//
	// Handler: func(*ChatMemberUpdated)
	OnChatMember = "\achat_member"

	// Will fire on VoiceChatStarted
	//
	// Handler: func(*Message)
	OnVoiceChatStarted = "\avoice_chat_started"

	// Will fire on VoiceChatEnded
	//
	// Handler: func(*Message)
	OnVoiceChatEnded = "\avoice_chat_ended"

	// Will fire on VoiceChatParticipantsInvited
	//
	// Handler: func(*Message)
	OnVoiceChatParticipantsInvited = "\avoice_chat_participants_invited"

	// Will fire on ProximityAlert
	//
	// Handler: func(*Message)
	OnProximityAlert = "\aproximity_alert_triggered"

	// Will fire on AudoDeleteTimer
	//
	// Handler: func(*Message)
	OnAutoDeleteTimer = "\amessage_auto_delete_timer_changed"

	// Will fire on OnVoiceChatScheduled
	//
	// Handler: func(*Message)
	OnVoiceChatScheduled = "\avoice_chat_scheduled"
)

These are one of the possible events Handle() can deal with.

For convenience, all Telebot-provided endpoints start with an "alert" character \a.

View Source 
const DefaultApiURL = "https://api.telegram.org"

Variables

View Source 
var (
	// General errors
	ErrUnauthorized      = NewAPIError(401, "Unauthorized")
	ErrNotStartedByUser  = NewAPIError(403, "Forbidden: bot can't initiate conversation with a user")
	ErrBlockedByUser     = NewAPIError(401, "Forbidden: bot was blocked by the user")
	ErrUserIsDeactivated = NewAPIError(401, "Forbidden: user is deactivated")
	ErrNotFound          = NewAPIError(404, "Not Found")
	ErrInternal          = NewAPIError(500, "Internal Server Error")

	// Bad request errors
	ErrTooLarge             = NewAPIError(400, "Request Entity Too Large")
	ErrMessageTooLong       = NewAPIError(400, "Bad Request: message is too long")
	ErrToForwardNotFound    = NewAPIError(400, "Bad Request: message to forward not found")
	ErrToReplyNotFound      = NewAPIError(400, "Bad Request: reply message not found")
	ErrToDeleteNotFound     = NewAPIError(400, "Bad Request: message to delete not found")
	ErrEmptyMessage         = NewAPIError(400, "Bad Request: message must be non-empty")
	ErrEmptyText            = NewAPIError(400, "Bad Request: text is empty")
	ErrEmptyChatID          = NewAPIError(400, "Bad Request: chat_id is empty")
	ErrChatNotFound         = NewAPIError(400, "Bad Request: chat not found")
	ErrMessageNotModified   = NewAPIError(400, "Bad Request: message is not modified")
	ErrSameMessageContent   = NewAPIError(400, "Bad Request: message is not modified: specified new message content and reply markup are exactly the same as a current content and reply markup of the message")
	ErrCantEditMessage      = NewAPIError(400, "Bad Request: message can't be edited")
	ErrButtonDataInvalid    = NewAPIError(400, "Bad Request: BUTTON_DATA_INVALID")
	ErrWrongTypeOfContent   = NewAPIError(400, "Bad Request: wrong type of the web page content")
	ErrBadURLContent        = NewAPIError(400, "Bad Request: failed to get HTTP URL content")
	ErrWrongFileID          = NewAPIError(400, "Bad Request: wrong file identifier/HTTP URL specified")
	ErrWrongFileIDSymbol    = NewAPIError(400, "Bad Request: wrong remote file id specified: can't unserialize it. Wrong last symbol")
	ErrWrongFileIDLength    = NewAPIError(400, "Bad Request: wrong remote file id specified: Wrong string length")
	ErrWrongFileIDCharacter = NewAPIError(400, "Bad Request: wrong remote file id specified: Wrong character in the string")
	ErrWrongFileIDPadding   = NewAPIError(400, "Bad Request: wrong remote file id specified: Wrong padding in the string")
	ErrFailedImageProcess   = NewAPIError(400, "Bad Request: IMAGE_PROCESS_FAILED", "Image process failed")
	ErrInvalidStickerSet    = NewAPIError(400, "Bad Request: STICKERSET_INVALID", "Stickerset is invalid")
	ErrBadPollOptions       = NewAPIError(400, "Bad Request: expected an Array of String as options")
	ErrGroupMigrated        = NewAPIError(400, "Bad Request: group chat was upgraded to a supergroup chat")

	// No rights errors
	ErrNoRightsToRestrict     = NewAPIError(400, "Bad Request: not enough rights to restrict/unrestrict chat member")
	ErrNoRightsToSend         = NewAPIError(400, "Bad Request: have no rights to send a message")
	ErrNoRightsToSendPhoto    = NewAPIError(400, "Bad Request: not enough rights to send photos to the chat")
	ErrNoRightsToSendStickers = NewAPIError(400, "Bad Request: not enough rights to send stickers to the chat")
	ErrNoRightsToSendGifs     = NewAPIError(400, "Bad Request: CHAT_SEND_GIFS_FORBIDDEN", "sending GIFS is not allowed in this chat")
	ErrNoRightsToDelete       = NewAPIError(400, "Bad Request: message can't be deleted")
	ErrKickingChatOwner       = NewAPIError(400, "Bad Request: can't remove chat owner")

	// Super/groups errors
	ErrBotKickedFromGroup      = NewAPIError(403, "Forbidden: bot was kicked from the group chat")
	ErrBotKickedFromSuperGroup = NewAPIError(403, "Forbidden: bot was kicked from the supergroup chat")
)
View Source 
var (
	ErrBadRecipient    = errors.New("telebot: recipient is nil")
	ErrUnsupportedWhat = errors.New("telebot: unsupported what argument")
	ErrCouldNotUpdate  = errors.New("telebot: could not fetch new updates")
	ErrTrueResult      = errors.New("telebot: result is True")
)
View Source 
var (
	Cube = &Dice{Type: "🎲"}
	Dart = &Dice{Type: "🎯"}
	Ball = &Dice{Type: "🏀"}
	Goal = &Dice{Type: "⚽"}
	Slot = &Dice{Type: "🎰"}
	Bowl = &Dice{Type: "🎳"}
)
View Source 
var SupportedCurrencies = map[string]Currency{}

Functions

func ErrByDescription added in v2.1.0 

func ErrByDescription(s string) error

ErrByDescription returns APIError instance by given description.

func Forever 

func Forever() int64

Forever is a ExpireUnixtime of "forever" banning.

Types

type APIError added in v2.1.0 

type APIError struct {
	Code        int
	Description string
	Message     string
	Parameters  map[string]interface{}
}

func NewAPIError added in v2.1.0 

func NewAPIError(code int, msgs ...string) *APIError

NewAPIError returns new APIError instance with given description. First element of msgs is Description. The second is optional Message.

func (*APIError) Error added in v2.1.0 

func (err *APIError) Error() string

Error implements error interface.

type Album 

type Album []InputMedia

Album lets you group multiple media (so-called InputMedia) into a single message.

On older clients albums look like N regular messages.

type Animation added in v2.1.0 

type Animation struct {
	File

	Width    int `json:"width"`
	Height   int `json:"height"`
	Duration int `json:"duration,omitempty"`

	// (Optional)
	Caption   string `json:"caption,omitempty"`
	Thumbnail *Photo `json:"thumb,omitempty"`
	MIME      string `json:"mime_type,omitempty"`
	FileName  string `json:"file_name,omitempty"`
}

Animation object represents a animation file.

func (*Animation) MediaFile added in v2.1.0 

func (a *Animation) MediaFile() *File

MediaFile returns &Animation.File

func (*Animation) Send added in v2.1.0 

func (a *Animation) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers animation through bot b to recipient.

type ArticleResult 

type ArticleResult struct {
	ResultBase

	// Title of the result.
	Title string `json:"title"`

	// Message text. Shortcut (and mutually exclusive to) specifying
	// InputMessageContent.
	Text string `json:"message_text,omitempty"`

	// Optional. URL of the result.
	URL string `json:"url,omitempty"`

	// Optional. Pass True, if you don't want the URL to be shown in the message.
	HideURL bool `json:"hide_url,omitempty"`

	// Optional. Short description of the result.
	Description string `json:"description,omitempty"`

	// Optional. URL of the thumbnail for the result.
	ThumbURL string `json:"thumb_url,omitempty"`

	// Optional. Width of the thumbnail for the result.
	ThumbWidth int `json:"thumb_width,omitempty"`

	// Optional. Height of the thumbnail for the result.
	ThumbHeight int `json:"thumb_height,omitempty"`
}

ArticleResult represents a link to an article or web page. See also: https://core.telegram.org/bots/api#inlinequeryresultarticle

type Audio 

type Audio struct {
	File

	// Duration of the recording in seconds as defined by sender.
	Duration int `json:"duration,omitempty"`

	// (Optional)
	Caption   string `json:"caption,omitempty"`
	Thumbnail *Photo `json:"thumb,omitempty"`
	Title     string `json:"title,omitempty"`
	Performer string `json:"performer,omitempty"`
	MIME      string `json:"mime_type,omitempty"`
	FileName  string `json:"file_name,omitempty"`
}

Audio object represents an audio file.

func (*Audio) MediaFile added in v2.1.0 

func (a *Audio) MediaFile() *File

MediaFile returns &Audio.File

func (*Audio) Send 

func (a *Audio) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type AudioResult 

type AudioResult struct {
	ResultBase

	// Title.
	Title string `json:"title"`

	// A valid URL for the audio file.
	URL string `json:"audio_url"`

	// Optional. Performer.
	Performer string `json:"performer,omitempty"`

	// Optional. Audio duration in seconds.
	Duration int `json:"audio_duration,omitempty"`

	// Optional. Caption, 0-1024 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"audio_file_id,omitempty"`
}

AudioResult represents a link to an mp3 audio file.

type Bot 

type Bot struct {
	Me      *User
	Token   string
	URL     string
	Updates chan Update
	Poller  Poller
	// contains filtered or unexported fields
}

Bot represents a separate Telegram bot instance.

func NewBot 

func NewBot(pref Settings) (*Bot, error)

NewBot does try to build a Bot with token `token`, which is a secret API key assigned to particular bot.

func (*Bot) Accept added in v2.1.0 

func (b *Bot) Accept(query *PreCheckoutQuery, errorMessage ...string) error

Accept finalizes the deal.

func (*Bot) AddStickerToSet added in v2.1.0 

func (b *Bot) AddStickerToSet(to Recipient, s StickerSet) error

AddStickerToSet adds new sticker to existing sticker set.

func (*Bot) AdminsOf 

func (b *Bot) AdminsOf(chat *Chat) ([]ChatMember, error)

AdminsOf returns a member list of chat admins.

On success, returns an Array of ChatMember objects that contains information about all chat administrators except other bots. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.

func (*Bot) Answer 

func (b *Bot) Answer(query *Query, resp *QueryResponse) error

Answer sends a response for a given inline query. A query can only be responded to once, subsequent attempts to respond to the same query will result in an error.

func (*Bot) Ban 

func (b *Bot) Ban(chat *Chat, member *ChatMember, revokeMessages ...bool) error

Ban will ban user from chat until `member.RestrictedUntil`.

func (*Bot) ChatByID 

func (b *Bot) ChatByID(id string) (*Chat, error)

ChatByID fetches chat info of its ID.

Including current name of the user for one-on-one conversations, current username of a user, group or channel, etc.

Returns a Chat object on success.

func (*Bot) ChatMemberOf 

func (b *Bot) ChatMemberOf(chat *Chat, user *User) (*ChatMember, error)

ChatMemberOf returns information about a member of a chat.

Returns a ChatMember object on success.

func (*Bot) Close added in v2.4.0 

func (b *Bot) Close() (bool, error)

Close closes the bot instance before moving it from one local server to another.

func (*Bot) Copy added in v2.4.0 

func (b *Bot) Copy(to Recipient, msg Editable, options ...interface{}) (*Message, error)

Copy behaves just like Forward() but the copied message doesn't have a link to the original message (see Bots API).

This function will panic upon nil Editable. 

func (b *Bot) CreateInviteLink(chat *Chat, link *ChatInviteLink) (*ChatInviteLink, error)

CreateInviteLink creates an additional invite link for a chat.

func (*Bot) CreateNewStickerSet added in v2.1.0 

func (b *Bot) CreateNewStickerSet(to Recipient, s StickerSet) error

CreateNewStickerSet creates a new sticker set.

func (*Bot) Delete 

func (b *Bot) Delete(msg Editable) error

Delete removes the message, including service messages, with the following limitations:

  • A message can only be deleted if it was sent less than 48 hours ago.
  • Bots can delete outgoing messages in groups and supergroups.
  • Bots granted can_post_messages permissions can delete outgoing messages in channels.
  • If the bot is an administrator of a group, it can delete any message there.
  • If the bot has can_delete_messages permission in a supergroup or a channel, it can delete any message there.

This function will panic upon nil Editable.

func (*Bot) DeleteGroupPhoto 

func (b *Bot) DeleteGroupPhoto(chat *Chat) error

DeleteGroupPhoto should be used to just remove group photo.

func (*Bot) DeleteGroupStickerSet 

func (b *Bot) DeleteGroupStickerSet(chat *Chat) error

DeleteGroupStickerSet should be used to just remove group sticker set.

func (*Bot) DeleteStickerFromSet added in v2.1.0 

func (b *Bot) DeleteStickerFromSet(sticker string) error

DeleteStickerFromSet deletes sticker from set created by the bot.

func (*Bot) Download 

func (b *Bot) Download(file *File, localFilename string) error

Download saves the file from Telegram servers locally.

Maximum file size to download is 20 MB.

func (*Bot) Edit 

func (b *Bot) Edit(msg Editable, what interface{}, options ...interface{}) (*Message, error)

Edit is magic, it lets you change already sent message.

If edited message is sent by the bot, returns it, otherwise returns nil and ErrTrueResult.

Use cases: 

b.Edit(m, m.Text, newMarkup)
b.Edit(m, "new <b>text</b>", tb.ModeHTML)
b.Edit(m, &tb.ReplyMarkup{...})
b.Edit(m, &tb.Photo{File: ...})
b.Edit(m, tb.Location{42.1337, 69.4242})

This function will panic upon nil Editable.

func (*Bot) EditCaption 

func (b *Bot) EditCaption(msg Editable, caption string, options ...interface{}) (*Message, error)

EditCaption edits already sent photo caption with known recipient and message id.

If edited message is sent by the bot, returns it, otherwise returns nil and ErrTrueResult.

On success, returns edited message object. This function will panic upon nil Editable. 

func (b *Bot) EditInviteLink(chat *Chat, link *ChatInviteLink) (*ChatInviteLink, error)

EditInviteLink edits a non-primary invite link created by the bot.

func (*Bot) EditMedia added in v2.1.0 

func (b *Bot) EditMedia(msg Editable, media InputMedia, options ...interface{}) (*Message, error)

EditMedia edits already sent media with known recipient and message id.

If edited message is sent by the bot, returns it, otherwise returns nil and ErrTrueResult.

Use cases: 

b.EditMedia(m, &tb.Photo{File: tb.FromDisk("chicken.jpg")})
b.EditMedia(m, &tb.Video{File: tb.FromURL("http://video.mp4")})

This function will panic upon nil Editable.

func (*Bot) EditReplyMarkup added in v2.1.0 

func (b *Bot) EditReplyMarkup(msg Editable, markup *ReplyMarkup) (*Message, error)

EditReplyMarkup edits reply markup of already sent message. Pass nil or empty ReplyMarkup to delete it from the message.

If edited message is sent by the bot, returns it, otherwise returns nil and ErrTrueResult.

On success, returns edited message object. This function will panic upon nil Editable.

func (*Bot) FileByID 

func (b *Bot) FileByID(fileID string) (File, error)

FileByID returns full file object including File.FilePath, allowing you to download the file from the server.

Usually, Telegram-provided File objects miss FilePath so you might need to perform an additional request to fetch them.

func (*Bot) FileURLByID 

func (b *Bot) FileURLByID(fileID string) (string, error)

FileURLByID returns direct url for files using FileID which you can get from File object. It returns a file:/// URL when the target file is on the local disk (it happens if you are using a local Bot API server, see https://core.telegram.org/bots/api#using-a-local-bot-api-server for details).

func (*Bot) Forward 

func (b *Bot) Forward(to Recipient, msg Editable, options ...interface{}) (*Message, error)

Forward behaves just like Send() but of all options it only supports Silent (see Bots API).

This function will panic upon nil Editable.

func (*Bot) GetCommands added in v2.1.0 

func (b *Bot) GetCommands() ([]Command, error)

GetCommands returns the current list of the bot's commands.

func (*Bot) GetFile added in v2.1.0 

func (b *Bot) GetFile(file *File) (io.ReadCloser, error)

GetFile gets a file from Telegram servers.

func (*Bot) GetGameScores added in v2.2.0 

func (b *Bot) GetGameScores(user Recipient, msg Editable) ([]GameHighScore, error)

GetGameScores returns the score of the specified user and several of their neighbors in a game.

This method will currently return scores for the target user, plus two of their closest neighbors on each side. Will also return the top three users if the user and his neighbors are not among them.

This function will panic upon nil Editable. 

func (b *Bot) GetInviteLink(chat *Chat) (string, error)

GetInviteLink should be used to export chat's invite link.

func (*Bot) GetStickerSet added in v2.1.0 

func (b *Bot) GetStickerSet(name string) (*StickerSet, error)

GetStickerSet returns a StickerSet on success.

func (*Bot) GetWebhook added in v2.2.0 

func (b *Bot) GetWebhook() (*Webhook, error)

GetWebhook returns current webhook status.

func (*Bot) Handle 

func (b *Bot) Handle(endpoint interface{}, handler interface{})

Handle lets you set the handler for some command name or one of the supported endpoints.

Example: 

b.Handle("/help", func (m *tb.Message) {})
b.Handle(tb.OnText, func (m *tb.Message) {})
b.Handle(tb.OnQuery, func (q *tb.Query) {})

// make a hook for one of your preserved (by-pointer) inline buttons.
b.Handle(&inlineButton, func (c *tb.Callback) {})

func (*Bot) Leave 

func (b *Bot) Leave(chat *Chat) error

Leave makes bot leave a group, supergroup or channel.

func (*Bot) Len 

func (b *Bot) Len(chat *Chat) (int, error)

Len returns the number of members in a chat.

func (*Bot) Logout added in v2.4.0 

func (b *Bot) Logout() (bool, error)

Logout logs out from the cloud Bot API server before launching the bot locally.

func (*Bot) NewMarkup added in v2.2.0 

func (b *Bot) NewMarkup() *ReplyMarkup

func (*Bot) Notify 

func (b *Bot) Notify(to Recipient, action ChatAction) error

Notify updates the chat action for recipient.

Chat action is a status message that recipient would see where you typically see "Harry is typing" status message. The only difference is that bots' chat actions live only for 5 seconds and die just once the client receives a message from the bot.

Currently, Telegram supports only a narrow range of possible actions, these are aligned as constants of this package.

func (*Bot) Pin 

func (b *Bot) Pin(msg Editable, options ...interface{}) error

Pin pins a message in a supergroup or a channel.

It supports tb.Silent option. This function will panic upon nil Editable.

func (*Bot) ProcessUpdate added in v2.2.0 

func (b *Bot) ProcessUpdate(upd Update)

ProcessUpdate processes a single incoming update. A started bot calls this function automatically.

func (*Bot) ProfilePhotosOf 

func (b *Bot) ProfilePhotosOf(user *User) ([]Photo, error)

ProfilePhotosOf returns list of profile pictures for a user.

func (*Bot) Promote 

func (b *Bot) Promote(chat *Chat, member *ChatMember) error

Promote lets you update member's admin rights, such as:

  • can change info
  • can post messages
  • can edit messages
  • can delete messages
  • can invite users
  • can restrict members
  • can pin messages
  • can promote members

func (*Bot) Raw 

func (b *Bot) Raw(method string, payload interface{}) ([]byte, error)

Raw lets you call any method of Bot API manually. It also handles API errors, so you only need to unwrap result field from json data.

func (*Bot) RemoveWebhook added in v2.1.0 

func (b *Bot) RemoveWebhook(dropPending ...bool) error

RemoveWebhook removes webhook integration.

func (*Bot) Reply 

func (b *Bot) Reply(to *Message, what interface{}, options ...interface{}) (*Message, error)

Reply behaves just like Send() with an exception of "reply-to" indicator.

This function will panic upon nil Message.

func (*Bot) Respond 

func (b *Bot) Respond(c *Callback, resp ...*CallbackResponse) error

Respond sends a response for a given callback query. A callback can only be responded to once, subsequent attempts to respond to the same callback will result in an error.

Example: 

bot.Respond(c)
bot.Respond(c, response)

func (*Bot) Restrict 

func (b *Bot) Restrict(chat *Chat, member *ChatMember) error

Restrict lets you restrict a subset of member's rights until member.RestrictedUntil, such as:

  • can send messages
  • can send media
  • can send other
  • can add web page previews
func (b *Bot) RevokeInviteLink(chat *Chat, link string) (*ChatInviteLink, error)

RevokeInviteLink revokes an invite link created by the bot.

func (*Bot) Send 

func (b *Bot) Send(to Recipient, what interface{}, options ...interface{}) (*Message, error)

Send accepts 2+ arguments, starting with destination chat, followed by some Sendable (or string!) and optional send options.

Note: since most arguments are of type interface{}, but have pointer method receivers, make sure to pass them by-pointer, NOT by-value.

What is a send option exactly? It can be one of the following types:

  • *SendOptions (the actual object accepted by Telegram API)
  • *ReplyMarkup (a component of SendOptions)
  • Option (a shortcut flag for popular options)
  • ParseMode (HTML, Markdown, etc)

func (*Bot) SendAlbum 

func (b *Bot) SendAlbum(to Recipient, a Album, options ...interface{}) ([]Message, error)

SendAlbum sends multiple instances of media as a single message.

From all existing options, it only supports tb.Silent.

func (*Bot) SetAdminTitle added in v2.1.0 

func (b *Bot) SetAdminTitle(chat *Chat, user *User, title string) error

SetAdminTitle sets a custom title for an administrator. A title should be 0-16 characters length, emoji are not allowed.

func (*Bot) SetCommands added in v2.1.0 

func (b *Bot) SetCommands(cmds []Command) error

SetCommands changes the list of the bot's commands.

func (*Bot) SetGameScore added in v2.2.0 

func (b *Bot) SetGameScore(user Recipient, msg Editable, score GameHighScore) (*Message, error)

SetGameScore sets the score of the specified user in a game.

If the message was sent by the bot, returns the edited Message, otherwise returns nil and ErrTrueResult.

func (*Bot) SetGroupDescription 

func (b *Bot) SetGroupDescription(chat *Chat, description string) error

SetGroupDescription should be used to update group description.

func (*Bot) SetGroupPermissions added in v2.1.0 

func (b *Bot) SetGroupPermissions(chat *Chat, perms Rights) error

SetGroupPermissions sets default chat permissions for all members.

func (*Bot) SetGroupPhoto 

func (b *Bot) SetGroupPhoto(chat *Chat, p *Photo) error

SetGroupPhoto should be used to update group photo.

func (*Bot) SetGroupStickerSet 

func (b *Bot) SetGroupStickerSet(chat *Chat, setName string) error

SetGroupStickerSet should be used to update group's group sticker set.

func (*Bot) SetGroupTitle 

func (b *Bot) SetGroupTitle(chat *Chat, title string) error

SetGroupTitle should be used to update group title.

func (*Bot) SetStickerPositionInSet added in v2.1.0 

func (b *Bot) SetStickerPositionInSet(sticker string, position int) error

SetStickerPositionInSet moves a sticker in set to a specific position.

func (*Bot) SetStickerSetThumb added in v2.2.0 

func (b *Bot) SetStickerSetThumb(to Recipient, s StickerSet) error

SetStickerSetThumb sets the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker sets only.

Thumbnail must be a PNG image, up to 128 kilobytes in size and have width and height exactly 100px, or a TGS animation up to 32 kilobytes in size.

Animated sticker set thumbnail can't be uploaded via HTTP URL.

func (*Bot) SetWebhook added in v2.1.0 

func (b *Bot) SetWebhook(w *Webhook) error

SetWebhook configures a bot to receive incoming updates via an outgoing webhook.

func (*Bot) Ship added in v2.2.0 

func (b *Bot) Ship(query *ShippingQuery, what ...interface{}) error

Ship replies to the shipping query, if you sent an invoice requesting an address and the parameter is_flexible was specified.

Usage: 

b.Ship(query)          // OK
b.Ship(query, opts...) // OK with options
b.Ship(query, "Oops!") // Error message

func (*Bot) Start 

func (b *Bot) Start()

Start brings bot into motion by consuming incoming updates (see Bot.Updates channel).

func (*Bot) Stop 

func (b *Bot) Stop()

Stop gracefully shuts the poller down.

func (*Bot) StopLiveLocation 

func (b *Bot) StopLiveLocation(msg Editable, options ...interface{}) (*Message, error)

StopLiveLocation stops broadcasting live message location before Location.LivePeriod expires.

If the message is sent by the bot, returns it, otherwise returns nil and ErrTrueResult.

It supports tb.ReplyMarkup. This function will panic upon nil Editable.

func (*Bot) StopPoll added in v2.1.0 

func (b *Bot) StopPoll(msg Editable, options ...interface{}) (*Poll, error)

StopPoll stops a poll which was sent by the bot and returns the stopped Poll object with the final results.

It supports ReplyMarkup. This function will panic upon nil Editable.

func (*Bot) Unban 

func (b *Bot) Unban(chat *Chat, user *User, forBanned ...bool) error

Unban will unban user from chat, who would have thought eh? forBanned does nothing if the user is not banned.

func (*Bot) Unpin 

func (b *Bot) Unpin(chat *Chat, messageID ...int) error

Unpin unpins a message in a supergroup or a channel.

It supports tb.Silent option. MessageID is a specific pinned message

func (*Bot) UnpinAll added in v2.4.0 

func (b *Bot) UnpinAll(chat *Chat) error

UnpinAll unpins all messages in a supergroup or a channel.

It supports tb.Silent option.

func (*Bot) UploadStickerFile added in v2.1.0 

func (b *Bot) UploadStickerFile(to Recipient, png *File) (*File, error)

UploadStickerFile uploads a .PNG file with a sticker for later use.

type Btn added in v2.2.0 

type Btn struct {
	Unique          string
	Text            string
	URL             string
	Data            string
	InlineQuery     string
	InlineQueryChat string
	Contact         bool
	Location        bool
	Poll            PollType
	Login           *Login
}

Btn is a constructor button, which will later become either a reply, or an inline button.

func (*Btn) CallbackUnique added in v2.2.0 

func (t *Btn) CallbackUnique() string

CallbackUnique implements CallbackEndpoint.

func (Btn) Inline added in v2.2.0 

func (b Btn) Inline() *InlineButton

func (Btn) Reply added in v2.2.0 

func (b Btn) Reply() *ReplyButton

type Callback 

type Callback struct {
	ID string `json:"id"`

	// For message sent to channels, Sender may be empty
	Sender *User `json:"from"`

	// Message will be set if the button that originated the query
	// was attached to a message sent by a bot.
	Message *Message `json:"message"`

	// MessageID will be set if the button was attached to a message
	// sent via the bot in inline mode.
	MessageID string `json:"inline_message_id"`

	// Data associated with the callback button. Be aware that
	// a bad client can send arbitrary data in this field.
	Data string `json:"data"`
}

Callback object represents a query from a callback button in an inline keyboard.

func (*Callback) IsInline added in v2.1.0 

func (c *Callback) IsInline() bool

IsInline says whether message is an inline message.

type CallbackEndpoint 

type CallbackEndpoint interface {
	CallbackUnique() string
}

CallbackEndpoint is an interface any element capable of responding to a callback `\f<unique>`.

type CallbackResponse 

type CallbackResponse struct {
	// The ID of the callback to which this is a response.
	//
	// Note: Telebot sets this field automatically!
	CallbackID string `json:"callback_query_id"`

	// Text of the notification. If not specified, nothing will be
	// shown to the user.
	Text string `json:"text,omitempty"`

	// (Optional) If true, an alert will be shown by the client instead
	// of a notification at the top of the chat screen. Defaults to false.
	ShowAlert bool `json:"show_alert,omitempty"`

	// (Optional) URL that will be opened by the user's client.
	// If you have created a Game and accepted the conditions via
	// @BotFather, specify the URL that opens your game.
	//
	// Note: this will only work if the query comes from a game
	// callback button. Otherwise, you may use deep-linking:
	// https://telegram.me/your_bot?start=XXXX
	URL string `json:"url,omitempty"`
}

CallbackResponse builds a response to a Callback query.

See also: https://core.telegram.org/bots/api#answerCallbackQuery

type Chat 

type Chat struct {
	ID int64 `json:"id"`

	// See ChatType and consts.
	Type ChatType `json:"type"`

	// Won't be there for ChatPrivate.
	Title string `json:"title"`

	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
	Username  string `json:"username"`

	// Still shows whether the user is a member
	// of the chat at the moment of the request.
	Still bool `json:"is_member,omitempty"`

	// Returns only in getChat
	Bio              string        `json:"bio,omitempty"`
	Photo            *ChatPhoto    `json:"photo,omitempty"`
	Description      string        `json:"description,omitempty"`
	InviteLink       string        `json:"invite_link,omitempty"`
	PinnedMessage    *Message      `json:"pinned_message,omitempty"`
	Permissions      *Rights       `json:"permissions,omitempty"`
	SlowMode         int           `json:"slow_mode_delay,omitempty"`
	StickerSet       string        `json:"sticker_set_name,omitempty"`
	CanSetStickerSet bool          `json:"can_set_sticker_set,omitempty"`
	LinkedChatID     int64         `json:"linked_chat_id,omitempty"`
	ChatLocation     *ChatLocation `json:"location,omitempty"`
}

Chat object represents a Telegram user, bot, group or a channel.

func (*Chat) Recipient 

func (c *Chat) Recipient() string

Recipient returns chat ID (see Recipient interface).

type ChatAction 

type ChatAction string

ChatAction is a client-side status indicating bot activity. 

const (
	Typing            ChatAction = "typing"
	UploadingPhoto    ChatAction = "upload_photo"
	UploadingVideo    ChatAction = "upload_video"
	UploadingAudio    ChatAction = "upload_audio"
	UploadingDocument ChatAction = "upload_document"
	UploadingVNote    ChatAction = "upload_video_note"
	RecordingVideo    ChatAction = "record_video"
	RecordingAudio    ChatAction = "record_audio"
	RecordingVNote    ChatAction = "record_video_note"
	FindingLocation   ChatAction = "find_location"
)

type ChatID added in v2.2.0 

type ChatID int64

ChatID represents a chat or an user integer ID, which can be used as recipient in bot methods. It is very useful in cases where you have special group IDs, for example in your config, and don't want to wrap it into *tb.Chat every time you send messages.

Example: 

group := tb.ChatID(-100756389456)
b.Send(group, "Hello!")

type Config struct {
	AdminGroup tb.ChatID `json:"admin_group"`
}
b.Send(conf.AdminGroup, "Hello!")

func (ChatID) Recipient added in v2.2.0 

func (i ChatID) Recipient() string

Recipient returns chat ID (see Recipient interface). 

type ChatInviteLink struct {
	// The invite link.
	InviteLink string `json:"invite_link"`

	// The creator of the link.
	Creator *User `json:"creator"`

	// If the link is primary.
	IsPrimary bool `json:"is_primary"`

	// If the link is revoked.
	IsRevoked bool `json:"is_revoked"`

	// (Optional) Point in time when the link will expire, use
	// ChatInviteLink.ExpireDate() to get time.Time
	ExpireUnixtime int64 `json:"expire_date,omitempty"`

	// (Optional) Maximum number of users that can be members of
	// the chat simultaneously.
	MemberLimit int `json:"member_limit,omitempty"`
}

ChatInviteLink object represents an invite for a chat.

func (*ChatInviteLink) ExpireDate added in v2.4.0 

func (c *ChatInviteLink) ExpireDate() time.Time

ExpireDate returns the moment of the link expiration in local time.

type ChatLocation added in v2.4.0 

type ChatLocation struct {
	Location Location `json:"location,omitempty"`
	Address  string   `json:"address,omitempty"`
}

type ChatMember 

type ChatMember struct {
	Rights

	User      *User        `json:"user"`
	Role      MemberStatus `json:"status"`
	Title     string       `json:"custom_title"`
	Anonymous bool         `json:"is_anonymous"`

	// Date when restrictions will be lifted for the user, unix time.
	//
	// If user is restricted for more than 366 days or less than
	// 30 seconds from the current time, they are considered to be
	// restricted forever.
	//
	// Use tb.Forever().
	//
	RestrictedUntil int64 `json:"until_date,omitempty"`
}

ChatMember object represents information about a single chat member.

type ChatMemberUpdated added in v2.4.0 

type ChatMemberUpdated struct {
	// Chat where the user belongs to.
	Chat Chat `json:"chat"`

	// From which user the action was triggered.
	From User `json:"from"`

	// Unixtime, use ChatMemberUpdated.Time() to get time.Time
	Unixtime int64 `json:"date"`

	// Previous information about the chat member.
	OldChatMember *ChatMember `json:"old_chat_member"`

	// New information about the chat member.
	NewChatMember *ChatMember `json:"new_chat_member"`

	// (Optional) InviteLink which was used by the user to
	// join the chat; for joining by invite link events only.
	InviteLink *ChatInviteLink `json:"invite_link"`
}

ChatMemberUpdated object represents changes in the status of a chat member.

func (*ChatMemberUpdated) Time added in v2.4.0 

func (c *ChatMemberUpdated) Time() time.Time

Time returns the moment of the change in local time.

type ChatPhoto added in v2.1.0 

type ChatPhoto struct {
	// File identifiers of small (160x160) chat photo
	SmallFileID       string `json:"small_file_id"`
	SmallFileUniqueID string `json:"small_file_unique_id"`

	// File identifiers of big (640x640) chat photo
	BigFileID       string `json:"big_file_id"`
	BigFileUniqueID string `json:"big_file_unique_id"`
}

ChatPhoto object represents a chat photo.

type ChatType 

type ChatType string

ChatType represents one of the possible chat types. 

const (
	ChatPrivate        ChatType = "private"
	ChatGroup          ChatType = "group"
	ChatSuperGroup     ChatType = "supergroup"
	ChatChannel        ChatType = "channel"
	ChatChannelPrivate ChatType = "privatechannel"
)

type ChosenInlineResult added in v2.1.0 

type ChosenInlineResult struct {
	From      User      `json:"from"`
	Location  *Location `json:"location,omitempty"`
	ResultID  string    `json:"result_id"`
	Query     string    `json:"query"`
	MessageID string    `json:"inline_message_id"` // inline messages only!
}

ChosenInlineResult represents a result of an inline query that was chosen by the user and sent to their chat partner.

type Command added in v2.1.0 

type Command struct {
	// Text is a text of the command, 1-32 characters.
	// Can contain only lowercase English letters, digits and underscores.
	Text string `json:"command"`

	// Description of the command, 3-256 characters.
	Description string `json:"description"`
}

Command represents a bot command.

type Contact 

type Contact struct {
	PhoneNumber string `json:"phone_number"`
	FirstName   string `json:"first_name"`

	// (Optional)
	LastName string `json:"last_name"`
	UserID   int64  `json:"user_id,omitempty"`
}

Contact object represents a contact to Telegram user

type ContactResult 

type ContactResult struct {
	ResultBase

	// Contact's phone number.
	PhoneNumber string `json:"phone_number"`

	// Optional. Additional data about the contact in the form of a vCard, 0-2048 bytes.
	VCard string `json:"vcard,omitempty"`

	// Contact's first name.
	FirstName string `json:"first_name"`

	// Optional. Contact's last name.
	LastName string `json:"last_name,omitempty"`

	// Optional. URL of the thumbnail for the result.
	ThumbURL string `json:"thumb_url,omitempty"`

	// Optional. Width of the thumbnail for the result.
	ThumbWidth int `json:"thumb_width,omitempty"`

	// Optional. Height of the thumbnail for the result.
	ThumbHeight int `json:"thumb_height,omitempty"`
}

ContentResult represents a contact with a phone number. See also: https://core.telegram.org/bots/api#inlinequeryresultcontact

type Currency added in v2.1.0 

type Currency struct {
	Code         string      `json:"code"`
	Title        string      `json:"title"`
	Symbol       string      `json:"symbol"`
	Native       string      `json:"native"`
	ThousandsSep string      `json:"thousands_sep"`
	DecimalSep   string      `json:"decimal_sep"`
	SymbolLeft   bool        `json:"symbol_left"`
	SpaceBetween bool        `json:"space_between"`
	Exp          int         `json:"exp"`
	MinAmount    interface{} `json:"min_amount"`
	MaxAmount    interface{} `json:"max_amount"`
}

Currency contains information about supported currency for payments.

func (Currency) FromTotal added in v2.1.0 

func (c Currency) FromTotal(total int) float64

func (Currency) ToTotal added in v2.1.0 

func (c Currency) ToTotal(total float64) int

type Dice added in v2.1.0 

type Dice struct {
	Type  DiceType `json:"emoji"`
	Value int      `json:"value"`
}

Dice object represents a dice with a random value from 1 to 6 for currently supported base emoji.

func (*Dice) Send added in v2.1.0 

func (d *Dice) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers dice through bot b to recipient.

type DiceType added in v2.1.0 

type DiceType string

type Document 

type Document struct {
	File

	// (Optional)
	Thumbnail *Photo `json:"thumb,omitempty"`
	Caption   string `json:"caption,omitempty"`
	MIME      string `json:"mime_type"`
	FileName  string `json:"file_name,omitempty"`
}

Document object represents a general file (as opposed to Photo or Audio). Telegram users can send files of any type of up to 1.5 GB in size.

func (*Document) MediaFile added in v2.1.0 

func (d *Document) MediaFile() *File

MediaFile returns &Document.File

func (*Document) Send 

func (d *Document) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type DocumentResult 

type DocumentResult struct {
	ResultBase

	// Title for the result.
	Title string `json:"title"`

	// A valid URL for the file
	URL string `json:"document_url"`

	// Mime type of the content of the file, either “application/pdf” or
	// “application/zip”.
	MIME string `json:"mime_type"`

	// Optional. Caption of the document to be sent, 0-200 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// Optional. Short description of the result.
	Description string `json:"description,omitempty"`

	// Optional. URL of the thumbnail (jpeg only) for the file.
	ThumbURL string `json:"thumb_url,omitempty"`

	// Optional. Width of the thumbnail for the result.
	ThumbWidth int `json:"thumb_width,omitempty"`

	// Optional. Height of the thumbnail for the result.
	ThumbHeight int `json:"thumb_height,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"document_file_id,omitempty"`
}

DocumentResult represents a link to a file. See also: https://core.telegram.org/bots/api#inlinequeryresultdocument

type Editable 

type Editable interface {
	// MessageSig is a "message signature".
	//
	// For inline messages, return chatID = 0.
	MessageSig() (messageID string, chatID int64)
}

Editable is an interface for all objects that provide "message signature", a pair of 32-bit message ID and 64-bit chat ID, both required for edit operations.

Use case: DB model struct for messages to-be edited with, say two columns: msg_id,chat_id could easily implement MessageSig() making instances of stored messages editable.

type EntityType 

type EntityType string

EntityType is a MessageEntity type. 

const (
	EntityMention       EntityType = "mention"
	EntityTMention      EntityType = "text_mention"
	EntityHashtag       EntityType = "hashtag"
	EntityCashtag       EntityType = "cashtag"
	EntityCommand       EntityType = "bot_command"
	EntityURL           EntityType = "url"
	EntityEmail         EntityType = "email"
	EntityPhone         EntityType = "phone_number"
	EntityBold          EntityType = "bold"
	EntityItalic        EntityType = "italic"
	EntityUnderline     EntityType = "underline"
	EntityStrikethrough EntityType = "strikethrough"
	EntityCode          EntityType = "code"
	EntityCodeBlock     EntityType = "pre"
	EntityTextLink      EntityType = "text_link"
)

type File 

type File struct {
	FileID   string `json:"file_id"`
	UniqueID string `json:"file_unique_id"`
	FileSize int    `json:"file_size"`

	// file on telegram server https://core.telegram.org/bots/api#file
	FilePath string `json:"file_path"`

	// file on local file system.
	FileLocal string `json:"file_local"`

	// file on the internet
	FileURL string `json:"file_url"`

	// file backed with io.Reader
	FileReader io.Reader `json:"-"`
	// contains filtered or unexported fields
}

File object represents any sort of file.

func FromDisk 

func FromDisk(filename string) File

FromDisk constructs a new local (on-disk) file object.

Note, it returns File, not *File for a very good reason: in telebot, File is pretty much an embeddable struct, so upon uploading media you'll need to set embedded File with something. NewFile() returning File makes it a one-liner. 

photo := &tb.Photo{File: tb.FromDisk("chicken.jpg")}

func FromReader added in v2.1.0 

func FromReader(reader io.Reader) File

FromReader constructs a new file from io.Reader.

Note, it returns File, not *File for a very good reason: in telebot, File is pretty much an embeddable struct, so upon uploading media you'll need to set embedded File with something. NewFile() returning File makes it a one-liner. 

photo := &tb.Photo{File: tb.FromReader(bytes.NewReader(...))}

func FromURL 

func FromURL(url string) File

FromURL constructs a new file on provided HTTP URL.

Note, it returns File, not *File for a very good reason: in telebot, File is pretty much an embeddable struct, so upon uploading media you'll need to set embedded File with something. NewFile() returning File makes it a one-liner. 

photo := &tb.Photo{File: tb.FromURL("https://site.com/picture.jpg")}

func (*File) InCloud 

func (f *File) InCloud() bool

InCloud tells whether the file is present on Telegram servers.

func (*File) OnDisk 

func (f *File) OnDisk() bool

OnDisk will return true if file is present on disk.

type FloodError added in v2.3.5 

type FloodError struct {
	*APIError
	RetryAfter int
}

type Game added in v2.2.0 

type Game struct {
	Name string `json:"game_short_name"`

	Title       string `json:"title"`
	Description string `json:"description"`
	Photo       *Photo `json:"photo"`

	// (Optional)
	Text      string          `json:"text"`
	Entities  []MessageEntity `json:"text_entities"`
	Animation *Animation      `json:"animation"`
}

Game object represents a game. Their short names acts as unique identifiers.

func (*Game) Send added in v2.2.0 

func (g *Game) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers game through bot b to recipient.

type GameHighScore added in v2.2.0 

type GameHighScore struct {
	User     *User `json:"user"`
	Position int   `json:"position"`

	Score  int  `json:"score"`
	Force  bool `json:"force"`
	NoEdit bool `json:"disable_edit_message"`
}

GameHighScore object represents one row of the high scores table for a game.

type GifResult 

type GifResult struct {
	ResultBase

	// A valid URL for the GIF file. File size must not exceed 1MB.
	URL string `json:"gif_url"`

	// Optional. Width of the GIF.
	Width int `json:"gif_width,omitempty"`

	// Optional. Height of the GIF.
	Height int `json:"gif_height,omitempty"`

	// Optional. Duration of the GIF.
	Duration int `json:"gif_duration,omitempty"`

	// URL of the static thumbnail for the result (jpeg or gif).
	ThumbURL string `json:"thumb_url"`

	// Optional. MIME type of the thumbnail, must be one of
	// “image/jpeg”, “image/gif”, or “video/mp4”.
	ThumbMIME string `json:"thumb_mime_type,omitempty"`

	// Optional. Title for the result.
	Title string `json:"title,omitempty"`

	// Optional. Caption of the GIF file to be sent, 0-200 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"gif_file_id,omitempty"`
}

GifResult represents a link to an animated GIF file. See also: https://core.telegram.org/bots/api#inlinequeryresultgif

type InlineButton 

type InlineButton struct {
	// Unique slagish name for this kind of button,
	// try to be as specific as possible.
	//
	// It will be used as a callback endpoint.
	Unique string `json:"unique,omitempty"`

	Text            string `json:"text"`
	URL             string `json:"url,omitempty"`
	Data            string `json:"callback_data,omitempty"`
	InlineQuery     string `json:"switch_inline_query,omitempty"`
	InlineQueryChat string `json:"switch_inline_query_current_chat"`
	Login           *Login `json:"login_url,omitempty"`
}

InlineButton represents a button displayed in the message.

func (*InlineButton) CallbackUnique 

func (t *InlineButton) CallbackUnique() string

CallbackUnique returns InlineButton.Unique.

func (*InlineButton) MarshalJSON added in v2.1.0 

func (t *InlineButton) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface. It needed to avoid InlineQueryChat and Login fields conflict. If you have Login field in your button, InlineQueryChat must be skipped.

func (*InlineButton) With added in v2.2.0 

func (t *InlineButton) With(data string) *InlineButton

With returns a copy of the button with data.

type InlineKeyboardMarkup 

type InlineKeyboardMarkup struct {
	// Array of button rows, each represented by
	// an Array of KeyboardButton objects.
	InlineKeyboard [][]InlineButton `json:"inline_keyboard,omitempty"`
}

InlineKeyboardMarkup represents an inline keyboard that appears right next to the message it belongs to.

type InputContactMessageContent 

type InputContactMessageContent struct {
	// Contact's phone number.
	PhoneNumber string `json:"phone_number"`

	// Contact's first name.
	FirstName string `json:"first_name"`

	// Optional. Contact's last name.
	LastName string `json:"last_name,omitempty"`
}

InputContactMessageContent represents the content of a contact message to be sent as the result of an inline query. See also: https://core.telegram.org/bots/api#inputcontactmessagecontent

func (*InputContactMessageContent) IsInputMessageContent 

func (input *InputContactMessageContent) IsInputMessageContent() bool

type InputLocationMessageContent 

type InputLocationMessageContent struct {
	Lat float32 `json:"latitude"`
	Lng float32 `json:"longitude"`
}

InputLocationMessageContent represents the content of a location message to be sent as the result of an inline query. See also: https://core.telegram.org/bots/api#inputlocationmessagecontent

func (*InputLocationMessageContent) IsInputMessageContent 

func (input *InputLocationMessageContent) IsInputMessageContent() bool

type InputMedia 

type InputMedia interface {
	// As some files must be uploaded (instead of referencing)
	// outer layers of Telebot require it.
	MediaFile() *File
}

InputMedia is a generic type for all kinds of media you can put into an album.

type InputMessageContent 

type InputMessageContent interface {
	IsInputMessageContent() bool
}

InputMessageContent objects represent the content of a message to be sent as a result of an inline query. See also: https://core.telegram.org/bots/api#inputmessagecontent

type InputTextMessageContent 

type InputTextMessageContent struct {
	// Text of the message to be sent, 1-4096 characters.
	Text string `json:"message_text"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in your bot's message.
	ParseMode string `json:"parse_mode,omitempty"`

	// Optional. Disables link previews for links in the sent message.
	DisablePreview bool `json:"disable_web_page_preview"`
}

InputTextMessageContent represents the content of a text message to be sent as the result of an inline query. See also: https://core.telegram.org/bots/api#inputtextmessagecontent

func (*InputTextMessageContent) IsInputMessageContent 

func (input *InputTextMessageContent) IsInputMessageContent() bool

type InputVenueMessageContent 

type InputVenueMessageContent struct {
	Lat float32 `json:"latitude"`
	Lng float32 `json:"longitude"`

	// Name of the venue.
	Title string `json:"title"`

	// Address of the venue.
	Address string `json:"address"`

	// Optional. Foursquare identifier of the venue, if known.
	FoursquareID string `json:"foursquare_id,omitempty"`
}

InputVenueMessageContent represents the content of a venue message to be sent as the result of an inline query. See also: https://core.telegram.org/bots/api#inputvenuemessagecontent

func (*InputVenueMessageContent) IsInputMessageContent 

func (input *InputVenueMessageContent) IsInputMessageContent() bool

type Invoice added in v2.1.0 

type Invoice struct {
	Title       string  `json:"title"`
	Description string  `json:"description"`
	Payload     string  `json:"payload"`
	Currency    string  `json:"currency"`
	Prices      []Price `json:"prices"`
	Token       string  `json:"provider_token"`
	Data        string  `json:"provider_data"`

	Photo     *Photo `json:"photo"`
	PhotoSize int    `json:"photo_size"`

	// Unique deep-linking parameter that can be used to
	// generate this invoice when used as a start parameter (0).
	Start string `json:"start_parameter"`

	// Shows the total price in the smallest units of the currency.
	// For example, for a price of US$ 1.45 pass amount = 145.
	Total int `json:"total_amount"`

	MaxTipAmount        int   `json:"max_tip_amount"`
	SuggestedTipAmounts []int `json:"suggested_tip_amounts"`

	NeedName            bool `json:"need_name"`
	NeedPhoneNumber     bool `json:"need_phone_number"`
	NeedEmail           bool `json:"need_email"`
	NeedShippingAddress bool `json:"need_shipping_address"`
	SendPhoneNumber     bool `json:"send_phone_number_to_provider"`
	SendEmail           bool `json:"send_email_to_provider"`
	Flexible            bool `json:"is_flexible"`
}

Invoice contains basic information about an invoice.

func (*Invoice) Send added in v2.1.0 

func (i *Invoice) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers invoice through bot b to recipient.

type Location 

type Location struct {
	// Latitude
	Lat float32 `json:"latitude"`
	// Longitude
	Lng float32 `json:"longitude"`

	// Horizontal Accuracy
	HorizontalAccuracy *float32 `json:"horizontal_accuracy,omitempty"`

	// Period in seconds for which the location will be updated
	// (see Live Locations, should be between 60 and 86400.)
	LivePeriod int `json:"live_period,omitempty"`

	Heading int `json:"heading,omitempty"`

	ProximityAlertRadius int `json:"proximity_alert_radius,omitempty"`
}

Location object represents geographic position.

func (*Location) Send 

func (x *Location) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type LocationResult 

type LocationResult struct {
	ResultBase

	Location

	// Location title.
	Title string `json:"title"`

	// Optional. Url of the thumbnail for the result.
	ThumbURL string `json:"thumb_url,omitempty"`
}

LocationResult represents a location on a map. See also: https://core.telegram.org/bots/api#inlinequeryresultlocation

type Login added in v2.1.0 

type Login struct {
	URL         string `json:"url"`
	Text        string `json:"forward_text,omitempty"`
	Username    string `json:"bot_username,omitempty"`
	WriteAccess bool   `json:"request_write_access,omitempty"`
}

Login represents a parameter of the inline keyboard button used to automatically authorize a user. Serves as a great replacement for the Telegram Login Widget when the user is coming from Telegram.

type LongPoller 

type LongPoller struct {
	Limit        int
	Timeout      time.Duration
	LastUpdateID int

	// AllowedUpdates contains the update types
	// you want your bot to receive.
	//
	// Possible values:
	//		message
	// 		edited_message
	// 		channel_post
	// 		edited_channel_post
	// 		inline_query
	// 		chosen_inline_result
	// 		callback_query
	// 		shipping_query
	// 		pre_checkout_query
	// 		poll
	// 		poll_answer
	//
	AllowedUpdates []string
}

LongPoller is a classic LongPoller with timeout.

func (*LongPoller) Poll 

func (p *LongPoller) Poll(b *Bot, dest chan Update, stop chan struct{})

Poll does long polling.

type MaskFeature 

type MaskFeature string

MaskFeature defines sticker mask position. 

const (
	FeatureForehead MaskFeature = "forehead"
	FeatureEyes     MaskFeature = "eyes"
	FeatureMouth    MaskFeature = "mouth"
	FeatureChin     MaskFeature = "chin"
)

type MaskPosition 

type MaskPosition struct {
	Feature MaskFeature `json:"point"`
	XShift  float32     `json:"x_shift"`
	YShift  float32     `json:"y_shift"`
	Scale   float32     `json:"scale"`
}

MaskPosition describes the position on faces where a mask should be placed by default.

type MemberStatus 

type MemberStatus string

MemberStatus is one's chat status. 

const (
	Creator       MemberStatus = "creator"
	Administrator MemberStatus = "administrator"
	Member        MemberStatus = "member"
	Restricted    MemberStatus = "restricted"
	Left          MemberStatus = "left"
	Kicked        MemberStatus = "kicked"
)

type Message 

type Message struct {
	ID int `json:"message_id"`

	InlineID string `json:"-"`

	// For message sent to channels, Sender will be nil
	Sender *User `json:"from"`

	// Unixtime, use Message.Time() to get time.Time
	Unixtime int64 `json:"date"`

	// Conversation the message belongs to.
	Chat *Chat `json:"chat"`

	// Sender of the message, sent on behalf of a chat.
	SenderChat *Chat `json:"sender_chat"`

	// For forwarded messages, sender of the original message.
	OriginalSender *User `json:"forward_from"`

	// For forwarded messages, chat of the original message when
	// forwarded from a channel.
	OriginalChat *Chat `json:"forward_from_chat"`

	// For forwarded messages, identifier of the original message
	// when forwarded from a channel.
	OriginalMessageID int `json:"forward_from_message_id"`

	// For forwarded messages, signature of the post author.
	OriginalSignature string `json:"forward_signature"`

	// For forwarded messages, sender's name from users who
	// disallow adding a link to their account.
	OriginalSenderName string `json:"forward_sender_name"`

	// For forwarded messages, unixtime of the original message.
	OriginalUnixtime int `json:"forward_date"`

	// For replies, ReplyTo represents the original message.
	//
	// Note that the Message object in this field will not
	// contain further ReplyTo fields even if it
	// itself is a reply.
	ReplyTo *Message `json:"reply_to_message"`

	// Shows through which bot the message was sent.
	Via *User `json:"via_bot"`

	// (Optional) Time of last edit in Unix
	LastEdit int64 `json:"edit_date"`

	// AlbumID is the unique identifier of a media message group
	// this message belongs to.
	AlbumID string `json:"media_group_id"`

	// Author signature (in channels).
	Signature string `json:"author_signature"`

	// For a text message, the actual UTF-8 text of the message.
	Text string `json:"text"`

	// For registered commands, will contain the string payload:
	//
	// Ex: `/command <payload>` or `/command@botname <payload>`
	Payload string `json:"-"`

	// For text messages, special entities like usernames, URLs, bot commands,
	// etc. that appear in the text.
	Entities []MessageEntity `json:"entities,omitempty"`

	// Some messages containing media, may as well have a caption.
	Caption string `json:"caption,omitempty"`

	// For messages with a caption, special entities like usernames, URLs,
	// bot commands, etc. that appear in the caption.
	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`

	// For an audio recording, information about it.
	Audio *Audio `json:"audio"`

	// For a general file, information about it.
	Document *Document `json:"document"`

	// For a photo, all available sizes (thumbnails).
	Photo *Photo `json:"photo"`

	// For a game, information about it.
	Game *Game `json:"game"`

	// For a sticker, information about it.
	Sticker *Sticker `json:"sticker"`

	// For a voice message, information about it.
	Voice *Voice `json:"voice"`

	// For a video note, information about it.
	VideoNote *VideoNote `json:"video_note"`

	// For a video, information about it.
	Video *Video `json:"video"`

	// For a animation, information about it.
	Animation *Animation `json:"animation"`

	// For a contact, contact information itself.
	Contact *Contact `json:"contact"`

	// For a location, its longitude and latitude.
	Location *Location `json:"location"`

	// For a venue, information about it.
	Venue *Venue `json:"venue"`

	// For a poll, information the native poll.
	Poll *Poll `json:"poll"`

	// For a dice, information about it.
	Dice *Dice `json:"dice"`

	// For a service message, represents a user,
	// that just got added to chat, this message came from.
	//
	// Sender leads to User, capable of invite.
	//
	// UserJoined might be the Bot itself.
	UserJoined *User `json:"new_chat_member"`

	// For a service message, represents a user,
	// that just left chat, this message came from.
	//
	// If user was kicked, Sender leads to a User,
	// capable of this kick.
	//
	// UserLeft might be the Bot itself.
	UserLeft *User `json:"left_chat_member"`

	// For a service message, represents a new title
	// for chat this message came from.
	//
	// Sender would lead to a User, capable of change.
	NewGroupTitle string `json:"new_chat_title"`

	// For a service message, represents all available
	// thumbnails of the new chat photo.
	//
	// Sender would lead to a User, capable of change.
	NewGroupPhoto *Photo `json:"new_chat_photo"`

	// For a service message, new members that were added to
	// the group or supergroup and information about them
	// (the bot itself may be one of these members).
	UsersJoined []User `json:"new_chat_members"`

	// For a service message, true if chat photo just
	// got removed.
	//
	// Sender would lead to a User, capable of change.
	GroupPhotoDeleted bool `json:"delete_chat_photo"`

	// For a service message, true if group has been created.
	//
	// You would receive such a message if you are one of
	// initial group chat members.
	//
	// Sender would lead to creator of the chat.
	GroupCreated bool `json:"group_chat_created"`

	// For a service message, true if supergroup has been created.
	//
	// You would receive such a message if you are one of
	// initial group chat members.
	//
	// Sender would lead to creator of the chat.
	SuperGroupCreated bool `json:"supergroup_chat_created"`

	// For a service message, true if channel has been created.
	//
	// You would receive such a message if you are one of
	// initial channel administrators.
	//
	// Sender would lead to creator of the chat.
	ChannelCreated bool `json:"channel_chat_created"`

	// For a service message, the destination (supergroup) you
	// migrated to.
	//
	// You would receive such a message when your chat has migrated
	// to a supergroup.
	//
	// Sender would lead to creator of the migration.
	MigrateTo int64 `json:"migrate_to_chat_id"`

	// For a service message, the Origin (normal group) you migrated
	// from.
	//
	// You would receive such a message when your chat has migrated
	// to a supergroup.
	//
	// Sender would lead to creator of the migration.
	MigrateFrom int64 `json:"migrate_from_chat_id"`

	// Specified message was pinned. Note that the Message object
	// in this field will not contain further ReplyTo fields even
	// if it is itself a reply.
	PinnedMessage *Message `json:"pinned_message"`

	// Message is an invoice for a payment.
	Invoice *Invoice `json:"invoice"`

	// Message is a service message about a successful payment.
	Payment *Payment `json:"successful_payment"`

	// The domain name of the website on which the user has logged in.
	ConnectedWebsite string `json:"connected_website,omitempty"`

	// Inline keyboard attached to the message.
	ReplyMarkup InlineKeyboardMarkup `json:"reply_markup"`

	VoiceChatSchedule *VoiceChatScheduled `json:"voice_chat_scheduled,omitempty"`

	// For a service message, a voice chat started in the chat.
	VoiceChatStarted *VoiceChatStarted `json:"voice_chat_started,omitempty"`

	// For a service message, a voice chat ended in the chat.
	VoiceChatEnded *VoiceChatEnded `json:"voice_chat_ended,omitempty"`

	// For a service message, some users were invited in the voice chat.
	VoiceChatParticipantsInvited *VoiceChatParticipantsInvited `json:"voice_chat_participants_invited,omitempty"`

	// For a service message, represents the content of a service message,
	// sent whenever a user in the chat triggers a proximity alert set by another user.
	ProximityAlert *ProximityAlertTriggered `json:"proximity_alert_triggered,omitempty"`

	// For a service message, represents about a change in auto-delete timer settings.
	AutoDeleteTimer *MessageAutoDeleteTimerChanged `json:"message_auto_delete_timer_changed,omitempty"`
}

Message object represents a message.

func (*Message) FromChannel 

func (m *Message) FromChannel() bool

FromChannel returns true, if message came from a channel.

func (*Message) FromGroup 

func (m *Message) FromGroup() bool

FromGroup returns true, if message came from a group OR a supergroup.

func (*Message) IsForwarded 

func (m *Message) IsForwarded() bool

IsForwarded says whether message is forwarded copy of another message or not.

func (*Message) IsReply 

func (m *Message) IsReply() bool

IsReply says whether message is a reply to another message.

func (*Message) IsService 

func (m *Message) IsService() bool

IsService returns true, if message is a service message, returns false otherwise.

Service messages are automatically sent messages, which typically occur on some global action. For instance, when anyone leaves the chat or chat title changes.

func (*Message) LastEdited 

func (m *Message) LastEdited() time.Time

LastEdited returns time.Time of last edit.

func (*Message) MessageSig 

func (m *Message) MessageSig() (string, int64)

MessageSig satisfies Editable interface (see Editable.)

func (*Message) Private 

func (m *Message) Private() bool

Private returns true, if it's a personal message.

func (*Message) Time 

func (m *Message) Time() time.Time

Time returns the moment of message creation in local time.

type MessageAutoDeleteTimerChanged added in v2.4.0 

type MessageAutoDeleteTimerChanged struct {
	DeleteTime int `json:"message_auto_delete_time"`
}

MessageAutoDeleteTimerChanged represents a service message about a change in auto-delete timer settings.

type MessageEntity 

type MessageEntity struct {
	// Specifies entity type.
	Type EntityType `json:"type"`

	// Offset in UTF-16 code units to the start of the entity.
	Offset int `json:"offset"`

	// Length of the entity in UTF-16 code units.
	Length int `json:"length"`

	// (Optional) For EntityTextLink entity type only.
	//
	// URL will be opened after user taps on the text.
	URL string `json:"url,omitempty"`

	// (Optional) For EntityTMention entity type only.
	User *User `json:"user,omitempty"`

	// (Optional) For EntityCodeBlock entity type only.
	Language string `json:"language,omitempty"`
}

MessageEntity object represents "special" parts of text messages, including hashtags, usernames, URLs, etc.

type MiddlewarePoller 

type MiddlewarePoller struct {
	Capacity int // Default: 1
	Poller   Poller
	Filter   func(*Update) bool
}

MiddlewarePoller is a special kind of poller that acts like a filter for updates. It could be used for spam handling, banning or whatever.

For heavy middleware, use increased capacity.

func NewMiddlewarePoller 

func NewMiddlewarePoller(original Poller, filter func(*Update) bool) *MiddlewarePoller

NewMiddlewarePoller wait for it... constructs a new middleware poller.

func (*MiddlewarePoller) Poll 

func (p *MiddlewarePoller) Poll(b *Bot, dest chan Update, stop chan struct{})

Poll sieves updates through middleware filter.

type Mpeg4GifResult 

type Mpeg4GifResult struct {
	ResultBase

	// A valid URL for the MP4 file.
	URL string `json:"mpeg4_url"`

	// Optional. Video width.
	Width int `json:"mpeg4_width,omitempty"`

	// Optional. Video height.
	Height int `json:"mpeg4_height,omitempty"`

	// Optional. Video duration.
	Duration int `json:"mpeg4_duration,omitempty"`

	// URL of the static thumbnail (jpeg or gif) for the result.
	ThumbURL string `json:"thumb_url,omitempty"`

	// Optional. MIME type of the thumbnail, must be one of
	// “image/jpeg”, “image/gif”, or “video/mp4”.
	ThumbMIME string `json:"thumb_mime_type,omitempty"`

	// Optional. Title for the result.
	Title string `json:"title,omitempty"`

	// Optional. Caption of the MPEG-4 file to be sent, 0-200 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"mpeg4_file_id,omitempty"`
}

ResultMpeg4Gif represents a link to a video animation (H.264/MPEG-4 AVC video without sound). See also: https://core.telegram.org/bots/api#inlinequeryresultmpeg4gif

type Option 

type Option int

Option is a shortcut flag type for certain message features (so-called options). It means that instead of passing fully-fledged SendOptions* to Send(), you can use these flags instead.

Supported options are defined as iota-constants. 

const (
	// NoPreview = SendOptions.DisableWebPagePreview
	NoPreview Option = iota

	// Silent = SendOptions.DisableNotification
	Silent

	// ForceReply = ReplyMarkup.ForceReply
	ForceReply

	// OneTimeKeyboard = ReplyMarkup.OneTimeKeyboard
	OneTimeKeyboard
)

type Order added in v2.2.0 

type Order struct {
	Name        string          `json:"name"`
	PhoneNumber string          `json:"phone_number"`
	Email       string          `json:"email"`
	Address     ShippingAddress `json:"shipping_address"`
}

Order represents information about an order.

type ParseMode 

type ParseMode = string

ParseMode determines the way client applications treat the text of the message 

const (
	ModeDefault    ParseMode = ""
	ModeMarkdown   ParseMode = "Markdown"
	ModeMarkdownV2 ParseMode = "MarkdownV2"
	ModeHTML       ParseMode = "HTML"
)

type Payment added in v2.2.0 

type Payment struct {
	Currency         string `json:"currency"`
	Total            int    `json:"total_amount"`
	Payload          string `json:"invoice_payload"`
	OptionID         string `json:"shipping_option_id"`
	Order            Order  `json:"order_info"`
	TelegramChargeID string `json:"telegram_payment_charge_id"`
	ProviderChargeID string `json:"provider_payment_charge_id"`
}

Payment contains basic information about a successful payment.

type Photo 

type Photo struct {
	File

	Width   int    `json:"width"`
	Height  int    `json:"height"`
	Caption string `json:"caption,omitempty"`
}

Photo object represents a single photo file.

func (*Photo) MediaFile 

func (p *Photo) MediaFile() *File

MediaFile returns &Photo.File

func (*Photo) Send 

func (p *Photo) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

func (*Photo) UnmarshalJSON 

func (p *Photo) UnmarshalJSON(jsonStr []byte) error

UnmarshalJSON is custom unmarshaller required to abstract away the hassle of treating different thumbnail sizes. Instead, Telebot chooses the hi-res one and just sticks to it.

I really do find it a beautiful solution.

type PhotoResult 

type PhotoResult struct {
	ResultBase

	// A valid URL of the photo. Photo must be in jpeg format.
	// Photo size must not exceed 5MB.
	URL string `json:"photo_url"`

	// Optional. Width of the photo.
	Width int `json:"photo_width,omitempty"`

	// Optional. Height of the photo.
	Height int `json:"photo_height,omitempty"`

	// Optional. Title for the result.
	Title string `json:"title,omitempty"`

	// Optional. Short description of the result.
	Description string `json:"description,omitempty"`

	// Optional. Caption of the photo to be sent, 0-200 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// URL of the thumbnail for the photo.
	ThumbURL string `json:"thumb_url"`

	// If Cache != "", it'll be used instead
	Cache string `json:"photo_file_id,omitempty"`
}

ResultResult represents a link to a photo. See also: https://core.telegram.org/bots/api#inlinequeryresultphoto

type Poll added in v2.1.0 

type Poll struct {
	ID         string       `json:"id"`
	Type       PollType     `json:"type"`
	Question   string       `json:"question"`
	Options    []PollOption `json:"options"`
	VoterCount int          `json:"total_voter_count"`

	// (Optional)
	Closed          bool            `json:"is_closed,omitempty"`
	CorrectOption   int             `json:"correct_option_id,omitempty"`
	MultipleAnswers bool            `json:"allows_multiple_answers,omitempty"`
	Explanation     string          `json:"explanation,omitempty"`
	ParseMode       ParseMode       `json:"explanation_parse_mode,omitempty"`
	Entities        []MessageEntity `json:"explanation_entities"`

	// True by default, shouldn't be omitted.
	Anonymous bool `json:"is_anonymous"`

	// (Mutually exclusive)
	OpenPeriod    int   `json:"open_period,omitempty"`
	CloseUnixdate int64 `json:"close_date,omitempty"`
}

Poll contains information about a poll.

func (*Poll) AddOptions added in v2.1.0 

func (p *Poll) AddOptions(opts ...string)

AddOptions adds text options to the poll.

func (*Poll) CloseDate added in v2.1.0 

func (p *Poll) CloseDate() time.Time

CloseDate returns the close date of poll in local time.

func (*Poll) IsQuiz added in v2.1.0 

func (p *Poll) IsQuiz() bool

IsQuiz says whether poll is a quiz.

func (*Poll) IsRegular added in v2.1.0 

func (p *Poll) IsRegular() bool

IsRegular says whether poll is a regular.

func (*Poll) Send added in v2.1.0 

func (p *Poll) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers poll through bot b to recipient.

type PollAnswer added in v2.1.0 

type PollAnswer struct {
	PollID  string `json:"poll_id"`
	User    User   `json:"user"`
	Options []int  `json:"option_ids"`
}

PollAnswer represents an answer of a user in a non-anonymous poll.

type PollOption added in v2.1.0 

type PollOption struct {
	Text       string `json:"text"`
	VoterCount int    `json:"voter_count"`
}

PollOption contains information about one answer option in a poll.

type PollType added in v2.1.0 

type PollType string

PollType defines poll types. 

const (
	// Despite "any" type isn't described in documentation,
	// it needed for proper KeyboardButtonPollType marshaling.
	PollAny PollType = "any"

	PollQuiz    PollType = "quiz"
	PollRegular PollType = "regular"
)

func (PollType) MarshalJSON added in v2.1.0 

func (pt PollType) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. It allows to pass PollType as keyboard's poll type instead of KeyboardButtonPollType object.

type Poller 

type Poller interface {
	// Poll is supposed to take the bot object
	// subscription channel and start polling
	// for Updates immediately.
	//
	// Poller must listen for stop constantly and close
	// it as soon as it's done polling.
	Poll(b *Bot, updates chan Update, stop chan struct{})
}

Poller is a provider of Updates.

All pollers must implement Poll(), which accepts bot pointer and subscription channel and start polling synchronously straight away.

type PreCheckoutQuery added in v2.1.0 

type PreCheckoutQuery struct {
	Sender   *User  `json:"from"`
	ID       string `json:"id"`
	Currency string `json:"currency"`
	Payload  string `json:"invoice_payload"`
	Total    int    `json:"total_amount"`
	OptionID string `json:"shipping_option_id"`
	Order    Order  `json:"order_info"`
}

PreCheckoutQuery contains information about an incoming pre-checkout query.

type Price added in v2.1.0 

type Price struct {
	Label  string `json:"label"`
	Amount int    `json:"amount"`
}

Price represents a portion of the price for goods or services.

type ProximityAlertTriggered added in v2.4.0 

type ProximityAlertTriggered struct {
	Traveler *User `json:"traveler,omitempty"`
	Watcher  *User `json:"watcher,omitempty"`
	Distance int   `json:"distance"`
}

ProximityAlertTriggered sent whenever a user in the chat triggers a proximity alert set by another user.

type Query 

type Query struct {
	// Unique identifier for this query. 1-64 bytes.
	ID string `json:"id"`

	// Sender.
	From User `json:"from"`

	// Sender location, only for bots that request user location.
	Location *Location `json:"location"`

	// Text of the query (up to 512 characters).
	Text string `json:"query"`

	// Offset of the results to be returned, can be controlled by the bot.
	Offset string `json:"offset"`

	// ChatType of the type of the chat, from which the inline query was sent.
	ChatType string `json:"chat_type"`
}

Query is an incoming inline query. When the user sends an empty query, your bot could return some default or trending results.

type QueryResponse 

type QueryResponse struct {
	// The ID of the query to which this is a response.
	//
	// Note: Telebot sets this field automatically!
	QueryID string `json:"inline_query_id"`

	// The results for the inline query.
	Results Results `json:"results"`

	// (Optional) The maximum amount of time in seconds that the result
	// of the inline query may be cached on the server.
	CacheTime int `json:"cache_time,omitempty"`

	// (Optional) Pass True, if results may be cached on the server side
	// only for the user that sent the query. By default, results may
	// be returned to any user who sends the same query.
	IsPersonal bool `json:"is_personal"`

	// (Optional) Pass the offset that a client should send in the next
	// query with the same text to receive more results. Pass an empty
	// string if there are no more results or if you don‘t support
	// pagination. Offset length can’t exceed 64 bytes.
	NextOffset string `json:"next_offset"`

	// (Optional) If passed, clients will display a button with specified
	// text that switches the user to a private chat with the bot and sends
	// the bot a start message with the parameter switch_pm_parameter.
	SwitchPMText string `json:"switch_pm_text,omitempty"`

	// (Optional) Parameter for the start message sent to the bot when user
	// presses the switch button.
	SwitchPMParameter string `json:"switch_pm_parameter,omitempty"`
}

QueryResponse builds a response to an inline Query. See also: https://core.telegram.org/bots/api#answerinlinequery

type Recipient 

type Recipient interface {
	// Must return legit Telegram chat_id or username
	Recipient() string
}

Recipient is any possible endpoint you can send messages to: either user, group or a channel.

type ReplyButton 

type ReplyButton struct {
	Text string `json:"text"`

	Contact  bool     `json:"request_contact,omitempty"`
	Location bool     `json:"request_location,omitempty"`
	Poll     PollType `json:"request_poll,omitempty"`
}

ReplyButton represents a button displayed in reply-keyboard.

Set either Contact or Location to true in order to request sensitive info, such as user's phone number or current location. (Available in private chats only.)

func (*ReplyButton) CallbackUnique 

func (t *ReplyButton) CallbackUnique() string

CallbackUnique returns KeyboardButton.Text.

type ReplyMarkup 

type ReplyMarkup struct {
	// InlineKeyboard is a grid of InlineButtons displayed in the message.
	//
	// Note: DO NOT confuse with ReplyKeyboard and other keyboard properties!
	InlineKeyboard [][]InlineButton `json:"inline_keyboard,omitempty"`

	// ReplyKeyboard is a grid, consisting of keyboard buttons.
	//
	// Note: you don't need to set HideCustomKeyboard field to show custom keyboard.
	ReplyKeyboard [][]ReplyButton `json:"keyboard,omitempty"`

	// ForceReply forces Telegram clients to display
	// a reply interface to the user (act as if the user
	// has selected the bot‘s message and tapped "Reply").
	ForceReply bool `json:"force_reply,omitempty"`

	// Requests clients to resize the keyboard vertically for optimal fit
	// (e.g. make the keyboard smaller if there are just two rows of buttons).
	//
	// Defaults to false, in which case the custom keyboard is always of the
	// same height as the app's standard keyboard.
	ResizeReplyKeyboard bool `json:"resize_keyboard,omitempty"`

	// Requests clients to hide the reply keyboard as soon as it's been used.
	//
	// Defaults to false.
	OneTimeKeyboard bool `json:"one_time_keyboard,omitempty"`

	// Requests clients to remove the reply keyboard.
	//
	// Defaults to false.
	ReplyKeyboardRemove bool `json:"remove_keyboard,omitempty"`

	// Use this param if you want to force reply from
	// specific users only.
	//
	// Targets:
	// 1) Users that are @mentioned in the text of the Message object;
	// 2) If the bot's message is a reply (has SendOptions.ReplyTo),
	//       sender of the original message.
	Selective bool `json:"selective,omitempty"`
}

ReplyMarkup controls two convenient options for bot-user communications such as reply keyboard and inline "keyboard" (a grid of buttons as a part of the message).

func (*ReplyMarkup) Contact added in v2.2.0 

func (r *ReplyMarkup) Contact(text string) Btn

func (*ReplyMarkup) Data added in v2.2.0 

func (r *ReplyMarkup) Data(text, unique string, data ...string) Btn

func (*ReplyMarkup) Inline added in v2.2.0 

func (r *ReplyMarkup) Inline(rows ...Row)

func (*ReplyMarkup) Location added in v2.2.0 

func (r *ReplyMarkup) Location(text string) Btn

func (*ReplyMarkup) Login added in v2.2.0 

func (r *ReplyMarkup) Login(text string, login *Login) Btn

func (*ReplyMarkup) Poll added in v2.2.0 

func (r *ReplyMarkup) Poll(text string, poll PollType) Btn

func (*ReplyMarkup) Query added in v2.2.0 

func (r *ReplyMarkup) Query(text, query string) Btn

func (*ReplyMarkup) QueryChat added in v2.2.0 

func (r *ReplyMarkup) QueryChat(text, query string) Btn

func (*ReplyMarkup) Reply added in v2.2.0 

func (r *ReplyMarkup) Reply(rows ...Row)

func (*ReplyMarkup) Row added in v2.2.0 

func (r *ReplyMarkup) Row(many ...Btn) Row

Row create a row of buttons

func (*ReplyMarkup) Text added in v2.2.0 

func (r *ReplyMarkup) Text(text string) Btn

func (*ReplyMarkup) URL added in v2.2.0 

func (r *ReplyMarkup) URL(text, url string) Btn

type Result 

type Result interface {
	ResultID() string
	SetResultID(string)
	SetContent(InputMessageContent)
	SetReplyMarkup([][]InlineButton)
	Process()
}

Result represents one result of an inline query.

type ResultBase 

type ResultBase struct {
	// Unique identifier for this result, 1-64 Bytes.
	// If left unspecified, a 64-bit FNV-1 hash will be calculated
	ID string `json:"id"`

	// Ignore. This field gets set automatically.
	Type string `json:"type"`

	// Optional. Content of the message to be sent.
	Content *InputMessageContent `json:"input_message_content,omitempty"`

	// Optional. Inline keyboard attached to the message.
	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
}

ResultBase must be embedded into all IQRs.

func (*ResultBase) Process added in v2.1.0 

func (r *ResultBase) Process()

func (*ResultBase) ResultID 

func (r *ResultBase) ResultID() string

ResultID returns ResultBase.ID.

func (*ResultBase) SetContent added in v2.1.0 

func (r *ResultBase) SetContent(content InputMessageContent)

SetContent sets ResultBase.Content.

func (*ResultBase) SetReplyMarkup added in v2.1.0 

func (r *ResultBase) SetReplyMarkup(keyboard [][]InlineButton)

SetReplyMarkup sets ResultBase.ReplyMarkup.

func (*ResultBase) SetResultID 

func (r *ResultBase) SetResultID(id string)

SetResultID sets ResultBase.ID.

type Results 

type Results []Result

Results is a slice wrapper for convenient marshalling.

func (Results) MarshalJSON 

func (results Results) MarshalJSON() ([]byte, error)

MarshalJSON makes sure IQRs have proper IDs and Type variables set.

type Rights 

type Rights struct {
	CanBeEdited         bool `json:"can_be_edited"`
	CanChangeInfo       bool `json:"can_change_info"`
	CanPostMessages     bool `json:"can_post_messages"`
	CanEditMessages     bool `json:"can_edit_messages"`
	CanDeleteMessages   bool `json:"can_delete_messages"`
	CanInviteUsers      bool `json:"can_invite_users"`
	CanRestrictMembers  bool `json:"can_restrict_members"`
	CanPinMessages      bool `json:"can_pin_messages"`
	CanPromoteMembers   bool `json:"can_promote_members"`
	CanSendMessages     bool `json:"can_send_messages"`
	CanSendMedia        bool `json:"can_send_media_messages"`
	CanSendPolls        bool `json:"can_send_polls"`
	CanSendOther        bool `json:"can_send_other_messages"`
	CanAddPreviews      bool `json:"can_add_web_page_previews"`
	CanManageVoiceChats bool `json:"can_manage_voice_chats"`
	CanManageChat       bool `json:"can_manage_chat"`
}

Rights is a list of privileges available to chat members.

func AdminRights 

func AdminRights() Rights

AdminRights could be used to promote user to admin.

func NoRestrictions 

func NoRestrictions() Rights

NoRestrictions should be used when un-restricting or un-promoting user. 

	   member.Rights = tb.NoRestrictions()
    bot.Restrict(chat, member)

func NoRights 

func NoRights() Rights

NoRights is the default Rights{}.

type Row added in v2.3.5 

type Row []Btn

Row represents an array of buttons, a row

type SendOptions 

type SendOptions struct {
	// If the message is a reply, original message.
	ReplyTo *Message

	// See ReplyMarkup struct definition.
	ReplyMarkup *ReplyMarkup

	// For text messages, disables previews for links in this message.
	DisableWebPagePreview bool

	// Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.
	DisableNotification bool

	// ParseMode controls how client apps render your message.
	ParseMode ParseMode

	// DisableContentDetection abilities to disable server-side file content type detection.
	DisableContentDetection bool

	// AllowWithoutReply allows sending messages not a as reply if the replied-to message has already been deleted.
	AllowWithoutReply bool
}

SendOptions has most complete control over in what way the message must be sent, providing an API-complete set of custom properties and options.

Despite its power, SendOptions is rather inconvenient to use all the way through bot logic, so you might want to consider storing and re-using it somewhere or be using Option flags instead.

type Sendable 

type Sendable interface {
	Send(*Bot, Recipient, *SendOptions) (*Message, error)
}

Sendable is any object that can send itself.

This is pretty cool, since it lets bots implement custom Sendables for complex kind of media or chat objects spanning across multiple messages.

type Settings 

type Settings struct {
	// Telegram API Url
	URL string

	// Telegram token
	Token string

	// Updates channel capacity
	Updates int // Default: 100

	// Poller is the provider of Updates.
	Poller Poller

	// Synchronous prevents handlers from running in parallel.
	// It makes ProcessUpdate return after the handler is finished.
	Synchronous bool

	// Verbose forces bot to log all upcoming requests.
	// Use for debugging purposes only.
	Verbose bool

	// ParseMode used to set default parse mode of all sent messages.
	// It attaches to every send, edit or whatever method. You also
	// will be able to override the default mode by passing a new one.
	ParseMode ParseMode

	// Reporter is a callback function that will get called
	// on any panics recovered from endpoint handlers.
	Reporter func(error)

	// HTTP Client used to make requests to telegram api
	Client *http.Client

	// Offline allows to create a bot without network for testing purposes.
	Offline bool
}

Settings represents a utility struct for passing certain properties of a bot around and is required to make bots.

type ShippingAddress added in v2.2.0 

type ShippingAddress struct {
	CountryCode string `json:"country_code"`
	State       string `json:"state"`
	City        string `json:"city"`
	StreetLine1 string `json:"street_line1"`
	StreetLine2 string `json:"street_line2"`
	PostCode    string `json:"post_code"`
}

ShippingAddress represents a shipping address.

type ShippingOption added in v2.2.0 

type ShippingOption struct {
	ID     string  `json:"id"`
	Title  string  `json:"title"`
	Prices []Price `json:"prices"`
}

ShippingOption represents one shipping option.

type ShippingQuery added in v2.2.0 

type ShippingQuery struct {
	Sender  *User           `json:"from"`
	ID      string          `json:"id"`
	Payload string          `json:"invoice_payload"`
	Address ShippingAddress `json:"shipping_address"`
}

ShippingQuery contains information about an incoming shipping query.

type Sticker 

type Sticker struct {
	File
	Width        int           `json:"width"`
	Height       int           `json:"height"`
	Animated     bool          `json:"is_animated"`
	Thumbnail    *Photo        `json:"thumb"`
	Emoji        string        `json:"emoji"`
	SetName      string        `json:"set_name"`
	MaskPosition *MaskPosition `json:"mask_position"`
}

Sticker object represents a WebP image, so-called sticker.

func (*Sticker) Send 

func (s *Sticker) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type StickerResult 

type StickerResult struct {
	ResultBase

	// If Cache != "", it'll be used instead
	Cache string `json:"sticker_file_id,omitempty"`
}

StickerResult represents an inline cached sticker response.

type StickerSet added in v2.1.0 

type StickerSet struct {
	Name          string        `json:"name"`
	Title         string        `json:"title"`
	Animated      bool          `json:"is_animated"`
	Stickers      []Sticker     `json:"stickers"`
	Thumbnail     *Photo        `json:"thumb"`
	PNG           *File         `json:"png_sticker"`
	TGS           *File         `json:"tgs_sticker"`
	Emojis        string        `json:"emojis"`
	ContainsMasks bool          `json:"contains_masks"`
	MaskPosition  *MaskPosition `json:"mask_position"`
}

StickerSet represents a sticker set.

type StoredMessage 

type StoredMessage struct {
	MessageID string `sql:"message_id" json:"message_id"`
	ChatID    int64  `sql:"chat_id" json:"chat_id"`
}

StoredMessage is an example struct suitable for being stored in the database as-is or being embedded into a larger struct, which is often the case (you might want to store some metadata alongside, or might not.)

func (StoredMessage) MessageSig 

func (x StoredMessage) MessageSig() (string, int64)

type Update 

type Update struct {
	ID int `json:"update_id"`

	Message            *Message            `json:"message,omitempty"`
	EditedMessage      *Message            `json:"edited_message,omitempty"`
	ChannelPost        *Message            `json:"channel_post,omitempty"`
	EditedChannelPost  *Message            `json:"edited_channel_post,omitempty"`
	Callback           *Callback           `json:"callback_query,omitempty"`
	Query              *Query              `json:"inline_query,omitempty"`
	ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result,omitempty"`
	ShippingQuery      *ShippingQuery      `json:"shipping_query,omitempty"`
	PreCheckoutQuery   *PreCheckoutQuery   `json:"pre_checkout_query,omitempty"`
	Poll               *Poll               `json:"poll,omitempty"`
	PollAnswer         *PollAnswer         `json:"poll_answer,omitempty"`
	MyChatMember       *ChatMemberUpdated  `json:"my_chat_member,omitempty"`
	ChatMember         *ChatMemberUpdated  `json:"chat_member,omitempty"`
}

Update object represents an incoming update.

type User 

type User struct {
	ID int64 `json:"id"`

	FirstName    string `json:"first_name"`
	LastName     string `json:"last_name"`
	Username     string `json:"username"`
	LanguageCode string `json:"language_code"`
	IsBot        bool   `json:"is_bot"`

	// Returns only in getMe
	CanJoinGroups   bool `json:"can_join_groups"`
	CanReadMessages bool `json:"can_read_all_group_messages"`
	SupportsInline  bool `json:"supports_inline_queries"`
}

User object represents a Telegram user, bot.

func (*User) Recipient 

func (u *User) Recipient() string

Recipient returns user ID (see Recipient interface).

type Venue 

type Venue struct {
	Location Location `json:"location"`
	Title    string   `json:"title"`
	Address  string   `json:"address"`

	// (Optional)
	FoursquareID    string `json:"foursquare_id,omitempty"`
	FoursquareType  string `json:"foursquare_type,omitempty"`
	GooglePlaceID   string `json:"google_place_id,omitempty"`
	GooglePlaceType string `json:"google_place_type,omitempty"`
}

Venue object represents a venue location with name, address and optional foursquare ID.

func (*Venue) Send 

func (v *Venue) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type VenueResult 

type VenueResult struct {
	ResultBase

	Location

	// Title of the venue.
	Title string `json:"title"`

	// Address of the venue.
	Address string `json:"address"`

	// Optional. Foursquare identifier of the venue if known.
	FoursquareID string `json:"foursquare_id,omitempty"`

	// Optional. URL of the thumbnail for the result.
	ThumbURL string `json:"thumb_url,omitempty"`

	// Optional. Width of the thumbnail for the result.
	ThumbWidth int `json:"thumb_width,omitempty"`

	// Optional. Height of the thumbnail for the result.
	ThumbHeight int `json:"thumb_height,omitempty"`
}

VenueResult represents a venue. See also: https://core.telegram.org/bots/api#inlinequeryresultvenue

type Video 

type Video struct {
	File

	Width  int `json:"width"`
	Height int `json:"height"`

	Duration int `json:"duration,omitempty"`

	// (Optional)
	Caption           string `json:"caption,omitempty"`
	Thumbnail         *Photo `json:"thumb,omitempty"`
	SupportsStreaming bool   `json:"supports_streaming,omitempty"`
	MIME              string `json:"mime_type,omitempty"`
	FileName          string `json:"file_name,omitempty"`
}

Video object represents a video file.

func (*Video) MediaFile 

func (v *Video) MediaFile() *File

MediaFile returns &Video.File

func (*Video) Send 

func (v *Video) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type VideoNote 

type VideoNote struct {
	File

	// Duration of the recording in seconds as defined by sender.
	Duration int `json:"duration"`

	// (Optional)
	Thumbnail *Photo `json:"thumb,omitempty"`
	Length    int    `json:"length,omitempty"`
}

VideoNote represents a video message (available in Telegram apps as of v.4.0).

func (*VideoNote) Send 

func (v *VideoNote) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type VideoResult 

type VideoResult struct {
	ResultBase

	// A valid URL for the embedded video player or video file.
	URL string `json:"video_url"`

	// Mime type of the content of video url, “text/html” or “video/mp4”.
	MIME string `json:"mime_type"`

	// URL of the thumbnail (jpeg only) for the video.
	ThumbURL string `json:"thumb_url"`

	// Title for the result.
	Title string `json:"title"`

	// Optional. Caption of the video to be sent, 0-200 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// Optional. Video width.
	Width int `json:"video_width,omitempty"`

	// Optional. Video height.
	Height int `json:"video_height,omitempty"`

	// Optional. Video duration in seconds.
	Duration int `json:"video_duration,omitempty"`

	// Optional. Short description of the result.
	Description string `json:"description,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"video_file_id,omitempty"`
}

VideoResult represents a link to a page containing an embedded video player or a video file. See also: https://core.telegram.org/bots/api#inlinequeryresultvideo

type Voice 

type Voice struct {
	File

	// Duration of the recording in seconds as defined by sender.
	Duration int `json:"duration"`

	// (Optional)
	Caption string `json:"caption,omitempty"`
	MIME    string `json:"mime_type,omitempty"`
}

Voice object represents a voice note.

func (*Voice) Send 

func (v *Voice) Send(b *Bot, to Recipient, opt *SendOptions) (*Message, error)

Send delivers media through bot b to recipient.

type VoiceChatEnded added in v2.3.6 

type VoiceChatEnded struct {
	Duration int `json:"duration"`
}

VoiceChatEnded represents a service message about a voice chat ended in the chat.

type VoiceChatParticipantsInvited added in v2.4.0 

type VoiceChatParticipantsInvited struct {
	Users []User `json:"users"`
}

VoiceChatParticipantsInvited represents a service message about new members invited to a voice chat

type VoiceChatScheduled added in v2.4.0 

type VoiceChatScheduled struct {
	Unixtime int64 `json:"start_date"`
}

VoiceChatScheduled represents a service message about a voice chat scheduled in the chat.

func (*VoiceChatScheduled) ExpireDate added in v2.4.0 

func (v *VoiceChatScheduled) ExpireDate() time.Time

ExpireDate returns the point when the voice chat is supposed to be started by a chat administrator.

type VoiceChatStarted added in v2.3.6 

type VoiceChatStarted struct{}

VoiceChatStarted represents a service message about a voice chat started in the chat.

type VoiceResult 

type VoiceResult struct {
	ResultBase

	// A valid URL for the voice recording.
	URL string `json:"voice_url"`

	// Recording title.
	Title string `json:"title"`

	// Optional. Recording duration in seconds.
	Duration int `json:"voice_duration"`

	// Optional. Caption, 0-1024 characters.
	Caption string `json:"caption,omitempty"`

	// Optional. Send Markdown or HTML, if you want Telegram apps to show
	// bold, italic, fixed-width text or inline URLs in the media caption.
	ParseMode ParseMode `json:"parse_mode,omitempty"`

	// If Cache != "", it'll be used instead
	Cache string `json:"voice_file_id,omitempty"`
}

VoiceResult represents a link to a voice recording in an .ogg container encoded with OPUS.

See also: https://core.telegram.org/bots/api#inlinequeryresultvoice

type Webhook added in v2.1.0 

type Webhook struct {
	Listen         string   `json:"url"`
	MaxConnections int      `json:"max_connections"`
	AllowedUpdates []string `json:"allowed_updates"`

	// (WebhookInfo)
	HasCustomCert  bool   `json:"has_custom_certificate"`
	PendingUpdates int    `json:"pending_update_count"`
	ErrorUnixtime  int64  `json:"last_error_date"`
	ErrorMessage   string `json:"last_error_message"`

	IP          string `json:"ip_address"`
	DropUpdates bool   `json:"drop_pending_updates"`

	TLS      *WebhookTLS
	Endpoint *WebhookEndpoint
	// contains filtered or unexported fields
}

A Webhook configures the poller for webhooks. It opens a port on the given listen address. If TLS is filled, the listener will use the key and cert to open a secure port. Otherwise it will use plain HTTP.

If you have a loadbalancer ore other infrastructure in front of your service, you must fill the Endpoint structure so this poller will send this data to telegram. If you leave these values empty, your local address will be sent to telegram which is mostly not what you want (at least while developing). If you have a single instance of your bot you should consider to use the LongPoller instead of a WebHook.

You can also leave the Listen field empty. In this case it is up to the caller to add the Webhook to a http-mux.

func (*Webhook) Poll added in v2.1.0 

func (h *Webhook) Poll(b *Bot, dest chan Update, stop chan struct{})

func (*Webhook) ServeHTTP added in v2.1.0 

func (h *Webhook) ServeHTTP(w http.ResponseWriter, r *http.Request)

The handler simply reads the update from the body of the requests and writes them to the update channel.

type WebhookEndpoint added in v2.1.0 

type WebhookEndpoint struct {
	PublicURL string
	Cert      string
}

A WebhookEndpoint describes the endpoint to which telegram will send its requests. This must be a public URL and can be a loadbalancer or something similar. If the endpoint uses TLS and the certificate is self-signed you have to add the certificate path of this certificate so telegram will trust it. This field can be ignored if you have a trusted certificate (letsencrypt, ...).

type WebhookTLS added in v2.1.0 

type WebhookTLS struct {
	Key  string
	Cert string
}

A WebhookTLS specifies the path to a key and a cert so the poller can open a TLS listener

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.