types.go (view raw)
1package tgbotapi
2
3import (
4 "encoding/json"
5 "errors"
6 "fmt"
7 "net/url"
8 "strings"
9 "time"
10)
11
12// APIResponse is a response from the Telegram API with the result
13// stored raw.
14type APIResponse struct {
15 Ok bool `json:"ok"`
16 Result json.RawMessage `json:"result"`
17 ErrorCode int `json:"error_code"`
18 Description string `json:"description"`
19 Parameters *ResponseParameters `json:"parameters"`
20}
21
22// ResponseParameters are various errors that can be returned in APIResponse.
23type ResponseParameters struct {
24 MigrateToChatID int `json:"migrate_to_chat_id"` // optional
25 RetryAfter int `json:"retry_after"` // optional
26}
27
28// Update is an update response, from GetUpdates.
29type Update struct {
30 UpdateID int `json:"update_id"`
31 Message *Message `json:"message"`
32 EditedMessage *Message `json:"edited_message"`
33 InlineQuery *InlineQuery `json:"inline_query"`
34 ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result"`
35 CallbackQuery *CallbackQuery `json:"callback_query"`
36}
37
38// User is a user on Telegram.
39type User struct {
40 ID int `json:"id"`
41 FirstName string `json:"first_name"`
42 LastName string `json:"last_name"` // optional
43 UserName string `json:"username"` // optional
44}
45
46// String displays a simple text version of a user.
47//
48// It is normally a user's username, but falls back to a first/last
49// name as available.
50func (u *User) String() string {
51 if u.UserName != "" {
52 return u.UserName
53 }
54
55 name := u.FirstName
56 if u.LastName != "" {
57 name += " " + u.LastName
58 }
59
60 return name
61}
62
63// GroupChat is a group chat.
64type GroupChat struct {
65 ID int `json:"id"`
66 Title string `json:"title"`
67}
68
69// Chat contains information about the place a message was sent.
70type Chat struct {
71 ID int64 `json:"id"`
72 Type string `json:"type"`
73 Title string `json:"title"` // optional
74 UserName string `json:"username"` // optional
75 FirstName string `json:"first_name"` // optional
76 LastName string `json:"last_name"` // optional
77 AllMembersAreAdmins bool `json:"all_members_are_administrators"` // optional
78}
79
80// IsPrivate returns if the Chat is a private conversation.
81func (c Chat) IsPrivate() bool {
82 return c.Type == "private"
83}
84
85// IsGroup returns if the Chat is a group.
86func (c Chat) IsGroup() bool {
87 return c.Type == "group"
88}
89
90// IsSuperGroup returns if the Chat is a supergroup.
91func (c Chat) IsSuperGroup() bool {
92 return c.Type == "supergroup"
93}
94
95// IsChannel returns if the Chat is a channel.
96func (c Chat) IsChannel() bool {
97 return c.Type == "channel"
98}
99
100// ChatConfig returns a ChatConfig struct for chat related methods.
101func (c Chat) ChatConfig() ChatConfig {
102 return ChatConfig{ChatID: c.ID}
103}
104
105// Message is returned by almost every request, and contains data about
106// almost anything.
107type Message struct {
108 MessageID int `json:"message_id"`
109 From *User `json:"from"` // optional
110 Date int `json:"date"`
111 Chat *Chat `json:"chat"`
112 ForwardFrom *User `json:"forward_from"` // optional
113 ForwardFromChat *Chat `json:"forward_from_chat"` // optional
114 ForwardDate int `json:"forward_date"` // optional
115 ReplyToMessage *Message `json:"reply_to_message"` // optional
116 EditDate int `json:"edit_date"` // optional
117 Text string `json:"text"` // optional
118 Entities *[]MessageEntity `json:"entities"` // optional
119 Audio *Audio `json:"audio"` // optional
120 Document *Document `json:"document"` // optional
121 Game *Game `json:"game"` // optional
122 Photo *[]PhotoSize `json:"photo"` // optional
123 Sticker *Sticker `json:"sticker"` // optional
124 Video *Video `json:"video"` // optional
125 Voice *Voice `json:"voice"` // optional
126 Caption string `json:"caption"` // optional
127 Contact *Contact `json:"contact"` // optional
128 Location *Location `json:"location"` // optional
129 Venue *Venue `json:"venue"` // optional
130 NewChatMember *User `json:"new_chat_member"` // optional
131 LeftChatMember *User `json:"left_chat_member"` // optional
132 NewChatTitle string `json:"new_chat_title"` // optional
133 NewChatPhoto *[]PhotoSize `json:"new_chat_photo"` // optional
134 DeleteChatPhoto bool `json:"delete_chat_photo"` // optional
135 GroupChatCreated bool `json:"group_chat_created"` // optional
136 SuperGroupChatCreated bool `json:"supergroup_chat_created"` // optional
137 ChannelChatCreated bool `json:"channel_chat_created"` // optional
138 MigrateToChatID int64 `json:"migrate_to_chat_id"` // optional
139 MigrateFromChatID int64 `json:"migrate_from_chat_id"` // optional
140 PinnedMessage *Message `json:"pinned_message"` // optional
141}
142
143// Time converts the message timestamp into a Time.
144func (m *Message) Time() time.Time {
145 return time.Unix(int64(m.Date), 0)
146}
147
148// IsCommand returns true if message starts with '/'.
149func (m *Message) IsCommand() bool {
150 return m.Text != "" && m.Text[0] == '/'
151}
152
153// Command checks if the message was a command and if it was, returns the
154// command. If the Message was not a command, it returns an empty string.
155//
156// If the command contains the at bot syntax, it removes the bot name.
157func (m *Message) Command() string {
158 if !m.IsCommand() {
159 return ""
160 }
161
162 command := strings.SplitN(m.Text, " ", 2)[0][1:]
163
164 if i := strings.Index(command, "@"); i != -1 {
165 command = command[:i]
166 }
167
168 return command
169}
170
171// CommandArguments checks if the message was a command and if it was,
172// returns all text after the command name. If the Message was not a
173// command, it returns an empty string.
174func (m *Message) CommandArguments() string {
175 if !m.IsCommand() {
176 return ""
177 }
178
179 split := strings.SplitN(m.Text, " ", 2)
180 if len(split) != 2 {
181 return ""
182 }
183
184 return strings.SplitN(m.Text, " ", 2)[1]
185}
186
187// MessageEntity contains information about data in a Message.
188type MessageEntity struct {
189 Type string `json:"type"`
190 Offset int `json:"offset"`
191 Length int `json:"length"`
192 URL string `json:"url"` // optional
193 User *User `json:"user"` // optional
194}
195
196// ParseURL attempts to parse a URL contained within a MessageEntity.
197func (entity MessageEntity) ParseURL() (*url.URL, error) {
198 if entity.URL == "" {
199 return nil, errors.New(ErrBadURL)
200 }
201
202 return url.Parse(entity.URL)
203}
204
205// PhotoSize contains information about photos.
206type PhotoSize struct {
207 FileID string `json:"file_id"`
208 Width int `json:"width"`
209 Height int `json:"height"`
210 FileSize int `json:"file_size"` // optional
211}
212
213// Audio contains information about audio.
214type Audio struct {
215 FileID string `json:"file_id"`
216 Duration int `json:"duration"`
217 Performer string `json:"performer"` // optional
218 Title string `json:"title"` // optional
219 MimeType string `json:"mime_type"` // optional
220 FileSize int `json:"file_size"` // optional
221}
222
223// Document contains information about a document.
224type Document struct {
225 FileID string `json:"file_id"`
226 Thumbnail *PhotoSize `json:"thumb"` // optional
227 FileName string `json:"file_name"` // optional
228 MimeType string `json:"mime_type"` // optional
229 FileSize int `json:"file_size"` // optional
230}
231
232// Sticker contains information about a sticker.
233type Sticker struct {
234 FileID string `json:"file_id"`
235 Width int `json:"width"`
236 Height int `json:"height"`
237 Thumbnail *PhotoSize `json:"thumb"` // optional
238 Emoji string `json:"emoji"` // optional
239 FileSize int `json:"file_size"` // optional
240}
241
242// Video contains information about a video.
243type Video struct {
244 FileID string `json:"file_id"`
245 Width int `json:"width"`
246 Height int `json:"height"`
247 Duration int `json:"duration"`
248 Thumbnail *PhotoSize `json:"thumb"` // optional
249 MimeType string `json:"mime_type"` // optional
250 FileSize int `json:"file_size"` // optional
251}
252
253// Voice contains information about a voice.
254type Voice struct {
255 FileID string `json:"file_id"`
256 Duration int `json:"duration"`
257 MimeType string `json:"mime_type"` // optional
258 FileSize int `json:"file_size"` // optional
259}
260
261// Contact contains information about a contact.
262//
263// Note that LastName and UserID may be empty.
264type Contact struct {
265 PhoneNumber string `json:"phone_number"`
266 FirstName string `json:"first_name"`
267 LastName string `json:"last_name"` // optional
268 UserID int `json:"user_id"` // optional
269}
270
271// Location contains information about a place.
272type Location struct {
273 Longitude float64 `json:"longitude"`
274 Latitude float64 `json:"latitude"`
275}
276
277// Venue contains information about a venue, including its Location.
278type Venue struct {
279 Location Location `json:"location"`
280 Title string `json:"title"`
281 Address string `json:"address"`
282 FoursquareID string `json:"foursquare_id"` // optional
283}
284
285// UserProfilePhotos contains a set of user profile photos.
286type UserProfilePhotos struct {
287 TotalCount int `json:"total_count"`
288 Photos [][]PhotoSize `json:"photos"`
289}
290
291// File contains information about a file to download from Telegram.
292type File struct {
293 FileID string `json:"file_id"`
294 FileSize int `json:"file_size"` // optional
295 FilePath string `json:"file_path"` // optional
296}
297
298// Link returns a full path to the download URL for a File.
299//
300// It requires the Bot Token to create the link.
301func (f *File) Link(token string) string {
302 return fmt.Sprintf(FileEndpoint, token, f.FilePath)
303}
304
305// ReplyKeyboardMarkup allows the Bot to set a custom keyboard.
306type ReplyKeyboardMarkup struct {
307 Keyboard [][]KeyboardButton `json:"keyboard"`
308 ResizeKeyboard bool `json:"resize_keyboard"` // optional
309 OneTimeKeyboard bool `json:"one_time_keyboard"` // optional
310 Selective bool `json:"selective"` // optional
311}
312
313// KeyboardButton is a button within a custom keyboard.
314type KeyboardButton struct {
315 Text string `json:"text"`
316 RequestContact bool `json:"request_contact"`
317 RequestLocation bool `json:"request_location"`
318}
319
320// ReplyKeyboardHide allows the Bot to hide a custom keyboard.
321type ReplyKeyboardHide struct {
322 HideKeyboard bool `json:"hide_keyboard"`
323 Selective bool `json:"selective"` // optional
324}
325
326// InlineKeyboardMarkup is a custom keyboard presented for an inline bot.
327type InlineKeyboardMarkup struct {
328 InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
329}
330
331// InlineKeyboardButton is a button within a custom keyboard for
332// inline query responses.
333//
334// Note that some values are references as even an empty string
335// will change behavior.
336//
337// CallbackGame, if set, MUST be first button in first row.
338type InlineKeyboardButton struct {
339 Text string `json:"text"`
340 URL *string `json:"url,omitempty"` // optional
341 CallbackData *string `json:"callback_data,omitempty"` // optional
342 SwitchInlineQuery *string `json:"switch_inline_query,omitempty"` // optional
343 SwitchInlineQueryCurrentChat *string `json:"switch_inline_query_current_chat"` // optional
344 CallbackGame *CallbackGame `json:"callback_game"` // optional
345}
346
347// CallbackQuery is data sent when a keyboard button with callback data
348// is clicked.
349type CallbackQuery struct {
350 ID string `json:"id"`
351 From *User `json:"from"`
352 Message *Message `json:"message"` // optional
353 InlineMessageID string `json:"inline_message_id"` // optional
354 ChatInstance string `json:"chat_instance"`
355 Data string `json:"data"` // optional
356 GameShortName string `json:"game_short_name"` // optional
357}
358
359// ForceReply allows the Bot to have users directly reply to it without
360// additional interaction.
361type ForceReply struct {
362 ForceReply bool `json:"force_reply"`
363 Selective bool `json:"selective"` // optional
364}
365
366// ChatMember is information about a member in a chat.
367type ChatMember struct {
368 User *User `json:"user"`
369 Status string `json:"status"`
370}
371
372// IsCreator returns if the ChatMember was the creator of the chat.
373func (chat ChatMember) IsCreator() bool { return chat.Status == "creator" }
374
375// IsAdministrator returns if the ChatMember is a chat administrator.
376func (chat ChatMember) IsAdministrator() bool { return chat.Status == "administrator" }
377
378// IsMember returns if the ChatMember is a current member of the chat.
379func (chat ChatMember) IsMember() bool { return chat.Status == "member" }
380
381// HasLeft returns if the ChatMember left the chat.
382func (chat ChatMember) HasLeft() bool { return chat.Status == "left" }
383
384// WasKicked returns if the ChatMember was kicked from the chat.
385func (chat ChatMember) WasKicked() bool { return chat.Status == "kicked" }
386
387// Game is a game within Telegram.
388type Game struct {
389 Title string `json:"title"`
390 Description string `json:"description"`
391 Photo []PhotoSize `json:"photo"`
392 Text string `json:"text"`
393 TextEntities []MessageEntity `json:"text_entities"`
394 Animation Animation `json:"animation"`
395}
396
397// Animation is a GIF animation demonstrating the game.
398type Animation struct {
399 FileID string `json:"file_id"`
400 Thumb PhotoSize `json:"thumb"`
401 FileName string `json:"file_name"`
402 MimeType string `json:"mime_type"`
403 FileSize int `json:"file_size"`
404}
405
406// GameHighScore is a user's score and position on the leaderboard.
407type GameHighScore struct {
408 Position int `json:"position"`
409 User User `json:"user"`
410 Score int `json:"score"`
411}
412
413// CallbackGame is for starting a game in an inline keyboard button.
414type CallbackGame struct{}
415
416// WebhookInfo is information about a currently set webhook.
417type WebhookInfo struct {
418 URL string `json:"url"`
419 HasCustomCertificate bool `json:"has_custom_certificate"`
420 PendingUpdateCount int `json:"pending_update_count"`
421 LastErrorDate int `json:"last_error_date"` // optional
422 LastErrorMessage string `json:"last_error_message"` // optional
423}
424
425// IsSet returns true if a webhook is currently set.
426func (info WebhookInfo) IsSet() bool {
427 return info.URL != ""
428}
429
430// InlineQuery is a Query from Telegram for an inline request.
431type InlineQuery struct {
432 ID string `json:"id"`
433 From *User `json:"from"`
434 Location *Location `json:"location"` // optional
435 Query string `json:"query"`
436 Offset string `json:"offset"`
437}
438
439// InlineQueryResultArticle is an inline query response article.
440type InlineQueryResultArticle struct {
441 Type string `json:"type"` // required
442 ID string `json:"id"` // required
443 Title string `json:"title"` // required
444 InputMessageContent interface{} `json:"input_message_content,omitempty"` // required
445 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
446 URL string `json:"url"`
447 HideURL bool `json:"hide_url"`
448 Description string `json:"description"`
449 ThumbURL string `json:"thumb_url"`
450 ThumbWidth int `json:"thumb_width"`
451 ThumbHeight int `json:"thumb_height"`
452}
453
454// InlineQueryResultPhoto is an inline query response photo.
455type InlineQueryResultPhoto struct {
456 Type string `json:"type"` // required
457 ID string `json:"id"` // required
458 URL string `json:"photo_url"` // required
459 MimeType string `json:"mime_type"`
460 Width int `json:"photo_width"`
461 Height int `json:"photo_height"`
462 ThumbURL string `json:"thumb_url"`
463 Title string `json:"title"`
464 Description string `json:"description"`
465 Caption string `json:"caption"`
466 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
467 InputMessageContent interface{} `json:"input_message_content,omitempty"`
468}
469
470// InlineQueryResultGIF is an inline query response GIF.
471type InlineQueryResultGIF struct {
472 Type string `json:"type"` // required
473 ID string `json:"id"` // required
474 URL string `json:"gif_url"` // required
475 Width int `json:"gif_width"`
476 Height int `json:"gif_height"`
477 ThumbURL string `json:"thumb_url"`
478 Title string `json:"title"`
479 Caption string `json:"caption"`
480 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
481 InputMessageContent interface{} `json:"input_message_content,omitempty"`
482}
483
484// InlineQueryResultMPEG4GIF is an inline query response MPEG4 GIF.
485type InlineQueryResultMPEG4GIF struct {
486 Type string `json:"type"` // required
487 ID string `json:"id"` // required
488 URL string `json:"mpeg4_url"` // required
489 Width int `json:"mpeg4_width"`
490 Height int `json:"mpeg4_height"`
491 ThumbURL string `json:"thumb_url"`
492 Title string `json:"title"`
493 Caption string `json:"caption"`
494 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
495 InputMessageContent interface{} `json:"input_message_content,omitempty"`
496}
497
498// InlineQueryResultVideo is an inline query response video.
499type InlineQueryResultVideo struct {
500 Type string `json:"type"` // required
501 ID string `json:"id"` // required
502 URL string `json:"video_url"` // required
503 MimeType string `json:"mime_type"` // required
504 ThumbURL string `json:"thumb_url"`
505 Title string `json:"title"`
506 Caption string `json:"caption"`
507 Width int `json:"video_width"`
508 Height int `json:"video_height"`
509 Duration int `json:"video_duration"`
510 Description string `json:"description"`
511 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
512 InputMessageContent interface{} `json:"input_message_content,omitempty"`
513}
514
515// InlineQueryResultAudio is an inline query response audio.
516type InlineQueryResultAudio struct {
517 Type string `json:"type"` // required
518 ID string `json:"id"` // required
519 URL string `json:"audio_url"` // required
520 Title string `json:"title"` // required
521 Caption string `json:"caption"`
522 Performer string `json:"performer"`
523 Duration int `json:"audio_duration"`
524 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
525 InputMessageContent interface{} `json:"input_message_content,omitempty"`
526}
527
528// InlineQueryResultVoice is an inline query response voice.
529type InlineQueryResultVoice struct {
530 Type string `json:"type"` // required
531 ID string `json:"id"` // required
532 URL string `json:"voice_url"` // required
533 Title string `json:"title"` // required
534 Caption string `json:"caption"`
535 Duration int `json:"voice_duration"`
536 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
537 InputMessageContent interface{} `json:"input_message_content,omitempty"`
538}
539
540// InlineQueryResultDocument is an inline query response document.
541type InlineQueryResultDocument struct {
542 Type string `json:"type"` // required
543 ID string `json:"id"` // required
544 Title string `json:"title"` // required
545 Caption string `json:"caption"`
546 URL string `json:"document_url"` // required
547 MimeType string `json:"mime_type"` // required
548 Description string `json:"description"`
549 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
550 InputMessageContent interface{} `json:"input_message_content,omitempty"`
551 ThumbURL string `json:"thumb_url"`
552 ThumbWidth int `json:"thumb_width"`
553 ThumbHeight int `json:"thumb_height"`
554}
555
556// InlineQueryResultLocation is an inline query response location.
557type InlineQueryResultLocation struct {
558 Type string `json:"type"` // required
559 ID string `json:"id"` // required
560 Latitude float64 `json:"latitude"` // required
561 Longitude float64 `json:"longitude"` // required
562 Title string `json:"title"` // required
563 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
564 InputMessageContent interface{} `json:"input_message_content,omitempty"`
565 ThumbURL string `json:"thumb_url"`
566 ThumbWidth int `json:"thumb_width"`
567 ThumbHeight int `json:"thumb_height"`
568}
569
570// InlineQueryResultGame is an inline query response game.
571type InlineQueryResultGame struct {
572 Type string `json:"type"`
573 ID string `json:"id"`
574 GameShortName string `json:"game_short_name"`
575 ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup"`
576}
577
578// ChosenInlineResult is an inline query result chosen by a User
579type ChosenInlineResult struct {
580 ResultID string `json:"result_id"`
581 From *User `json:"from"`
582 Location *Location `json:"location"`
583 InlineMessageID string `json:"inline_message_id"`
584 Query string `json:"query"`
585}
586
587// InputTextMessageContent contains text for displaying
588// as an inline query result.
589type InputTextMessageContent struct {
590 Text string `json:"message_text"`
591 ParseMode string `json:"parse_mode"`
592 DisableWebPagePreview bool `json:"disable_web_page_preview"`
593}
594
595// InputLocationMessageContent contains a location for displaying
596// as an inline query result.
597type InputLocationMessageContent struct {
598 Latitude float64 `json:"latitude"`
599 Longitude float64 `json:"longitude"`
600}
601
602// InputVenueMessageContent contains a venue for displaying
603// as an inline query result.
604type InputVenueMessageContent struct {
605 Latitude float64 `json:"latitude"`
606 Longitude float64 `json:"longitude"`
607 Title string `json:"title"`
608 Address string `json:"address"`
609 FoursquareID string `json:"foursquare_id"`
610}
611
612// InputContactMessageContent contains a contact for displaying
613// as an inline query result.
614type InputContactMessageContent struct {
615 PhoneNumber string `json:"phone_number"`
616 FirstName string `json:"first_name"`
617 LastName string `json:"last_name"`
618}