types.go (view raw)
1package tgbotapi
2
3import (
4 "encoding/json"
5 "fmt"
6 "net/url"
7 "strings"
8 "time"
9)
10
11// APIResponse is a response from the Telegram API with the result
12// stored raw.
13type APIResponse struct {
14 Ok bool `json:"ok"`
15 Result json.RawMessage `json:"result"`
16 ErrorCode int `json:"error_code"`
17 Description string `json:"description"`
18}
19
20// Update is an update response, from GetUpdates.
21type Update struct {
22 UpdateID int `json:"update_id"`
23 Message Message `json:"message"`
24 InlineQuery InlineQuery `json:"inline_query"`
25 ChosenInlineResult ChosenInlineResult `json:"chosen_inline_result"`
26 CallbackQuery CallbackQuery `json:"callback_query"`
27}
28
29// User is a user on Telegram.
30type User struct {
31 ID int `json:"id"`
32 FirstName string `json:"first_name"`
33 LastName string `json:"last_name"` // optional
34 UserName string `json:"username"` // optional
35}
36
37// String displays a simple text version of a user.
38//
39// It is normally a user's username, but falls back to a first/last
40// name as available.
41func (u *User) String() string {
42 if u.UserName != "" {
43 return u.UserName
44 }
45
46 name := u.FirstName
47 if u.LastName != "" {
48 name += " " + u.LastName
49 }
50
51 return name
52}
53
54// GroupChat is a group chat.
55type GroupChat struct {
56 ID int `json:"id"`
57 Title string `json:"title"`
58}
59
60// Chat contains information about the place a message was sent.
61type Chat struct {
62 ID int64 `json:"id"`
63 Type string `json:"type"`
64 Title string `json:"title"` // optional
65 UserName string `json:"username"` // optional
66 FirstName string `json:"first_name"` // optional
67 LastName string `json:"last_name"` // optional
68}
69
70// IsPrivate returns if the Chat is a private conversation.
71func (c *Chat) IsPrivate() bool {
72 return c.Type == "private"
73}
74
75// IsGroup returns if the Chat is a group.
76func (c *Chat) IsGroup() bool {
77 return c.Type == "group"
78}
79
80// IsSuperGroup returns if the Chat is a supergroup.
81func (c *Chat) IsSuperGroup() bool {
82 return c.Type == "supergroup"
83}
84
85// IsChannel returns if the Chat is a channel.
86func (c *Chat) IsChannel() bool {
87 return c.Type == "channel"
88}
89
90// Message is returned by almost every request, and contains data about
91// almost anything.
92type Message struct {
93 MessageID int `json:"message_id"`
94 From User `json:"from"` // optional
95 Date int `json:"date"`
96 Chat Chat `json:"chat"`
97 ForwardFrom User `json:"forward_from"` // optional
98 ForwardDate int `json:"forward_date"` // optional
99 ReplyToMessage *Message `json:"reply_to_message"` // optional
100 Text string `json:"text"` // optional
101 Entities []MessageEntity `json:"entities"` // optional
102 Audio Audio `json:"audio"` // optional
103 Document Document `json:"document"` // optional
104 Photo []PhotoSize `json:"photo"` // optional
105 Sticker Sticker `json:"sticker"` // optional
106 Video Video `json:"video"` // optional
107 Voice Voice `json:"voice"` // optional
108 Caption string `json:"caption"` // optional
109 Contact Contact `json:"contact"` // optional
110 Location Location `json:"location"` // optional
111 Venue Venue `json:"venue"` // optional
112 NewChatMember User `json:"new_chat_member"` // optional
113 LeftChatMember User `json:"left_chat_member"` // optional
114 NewChatTitle string `json:"new_chat_title"` // optional
115 NewChatPhoto []PhotoSize `json:"new_chat_photo"` // optional
116 DeleteChatPhoto bool `json:"delete_chat_photo"` // optional
117 GroupChatCreated bool `json:"group_chat_created"` // optional
118 SuperGroupChatCreated bool `json:"supergroup_chat_created"` // optional
119 ChannelChatCreated bool `json:"channel_chat_created"` // optional
120 MigrateToChatID int64 `json:"migrate_to_chat_id"` // optional
121 MigrateFromChatID int64 `json:"migrate_from_chat_id"` // optional
122 PinnedMessage *Message `json:"pinned_message"` // optional
123}
124
125// Time converts the message timestamp into a Time.
126func (m *Message) Time() time.Time {
127 return time.Unix(int64(m.Date), 0)
128}
129
130// IsCommand returns true if message starts with '/'.
131func (m *Message) IsCommand() bool {
132 return m.Text != "" && m.Text[0] == '/'
133}
134
135// Command checks if the message was a command and if it was, returns the
136// command. If the Message was not a command, it returns an empty string.
137//
138// If the command contains the at bot syntax, it removes the bot name.
139func (m *Message) Command() string {
140 if !m.IsCommand() {
141 return ""
142 }
143
144 command := strings.SplitN(m.Text, " ", 2)[0][1:]
145
146 if i := strings.Index(command, "@"); i != -1 {
147 command = command[:i]
148 }
149
150 return command
151}
152
153// CommandArguments checks if the message was a command and if it was,
154// returns all text after the command name. If the Message was not a
155// command, it returns an empty string.
156func (m *Message) CommandArguments() string {
157 if !m.IsCommand() {
158 return ""
159 }
160
161 split := strings.SplitN(m.Text, " ", 2)
162 if len(split) != 2 {
163 return ""
164 }
165
166 return strings.SplitN(m.Text, " ", 2)[1]
167}
168
169// MessageEntity contains information about data in a Message.
170type MessageEntity struct {
171 Type string `json:"type"`
172 Offset int `json:"offset"`
173 Length int `json:"length"`
174 URL string `json:"url"` // optional
175}
176
177// ParseURL attempts to parse a URL contained within a MessageEntity.
178func (entity MessageEntity) ParseURL() (*url.URL, error) {
179 return url.Parse(entity.URL)
180}
181
182// PhotoSize contains information about photos.
183type PhotoSize struct {
184 FileID string `json:"file_id"`
185 Width int `json:"width"`
186 Height int `json:"height"`
187 FileSize int `json:"file_size"` // optional
188}
189
190// Audio contains information about audio.
191type Audio struct {
192 FileID string `json:"file_id"`
193 Duration int `json:"duration"`
194 Performer string `json:"performer"` // optional
195 Title string `json:"title"` // optional
196 MimeType string `json:"mime_type"` // optional
197 FileSize int `json:"file_size"` // optional
198}
199
200// Document contains information about a document.
201type Document struct {
202 FileID string `json:"file_id"`
203 Thumbnail PhotoSize `json:"thumb"` // optional
204 FileName string `json:"file_name"` // optional
205 MimeType string `json:"mime_type"` // optional
206 FileSize int `json:"file_size"` // optional
207}
208
209// Sticker contains information about a sticker.
210type Sticker struct {
211 FileID string `json:"file_id"`
212 Width int `json:"width"`
213 Height int `json:"height"`
214 Thumbnail PhotoSize `json:"thumb"` // optional
215 FileSize int `json:"file_size"` // optional
216}
217
218// Video contains information about a video.
219type Video struct {
220 FileID string `json:"file_id"`
221 Width int `json:"width"`
222 Height int `json:"height"`
223 Duration int `json:"duration"`
224 Thumbnail PhotoSize `json:"thumb"` // optional
225 MimeType string `json:"mime_type"` // optional
226 FileSize int `json:"file_size"` // optional
227}
228
229// Voice contains information about a voice.
230type Voice struct {
231 FileID string `json:"file_id"`
232 Duration int `json:"duration"`
233 MimeType string `json:"mime_type"` // optional
234 FileSize int `json:"file_size"` // optional
235}
236
237// Contact contains information about a contact.
238//
239// Note that LastName and UserID may be empty.
240type Contact struct {
241 PhoneNumber string `json:"phone_number"`
242 FirstName string `json:"first_name"`
243 LastName string `json:"last_name"` // optional
244 UserID int `json:"user_id"` // optional
245}
246
247// Location contains information about a place.
248type Location struct {
249 Longitude float32 `json:"longitude"`
250 Latitude float32 `json:"latitude"`
251}
252
253// Venue contains information about a venue, including its Location.
254type Venue struct {
255 Location Location `json:"location"`
256 Title string `json:"title"`
257 Address string `json:"address"`
258 FoursquareID string `json:"foursquare_id"` // optional
259}
260
261// UserProfilePhotos contains a set of user profile photos.
262type UserProfilePhotos struct {
263 TotalCount int `json:"total_count"`
264 Photos [][]PhotoSize `json:"photos"`
265}
266
267// File contains information about a file to download from Telegram.
268type File struct {
269 FileID string `json:"file_id"`
270 FileSize int `json:"file_size"` // optional
271 FilePath string `json:"file_path"` // optional
272}
273
274// Link returns a full path to the download URL for a File.
275//
276// It requires the Bot Token to create the link.
277func (f *File) Link(token string) string {
278 return fmt.Sprintf(FileEndpoint, token, f.FilePath)
279}
280
281// ReplyKeyboardMarkup allows the Bot to set a custom keyboard.
282type ReplyKeyboardMarkup struct {
283 Keyboard [][]KeyboardButton `json:"keyboard"`
284 ResizeKeyboard bool `json:"resize_keyboard"` // optional
285 OneTimeKeyboard bool `json:"one_time_keyboard"` // optional
286 Selective bool `json:"selective"` // optional
287}
288
289// KeyboardButton is a button within a custom keyboard.
290type KeyboardButton struct {
291 Text string `json:"text"`
292 RequestContact bool `json:"request_contact"`
293 RequestLocation bool `json:"request_location"`
294}
295
296// ReplyKeyboardHide allows the Bot to hide a custom keyboard.
297type ReplyKeyboardHide struct {
298 HideKeyboard bool `json:"hide_keyboard"`
299 Selective bool `json:"selective"` // optional
300}
301
302// InlineKeyboardMarkup is a custom keyboard presented for an inline bot.
303type InlineKeyboardMarkup struct {
304 InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"`
305}
306
307// InlineKeyboardButton is a button within a custom keyboard for
308// inline query responses.
309//
310// Note that some values are references as even an empty string
311// will change behavior.
312type InlineKeyboardButton struct {
313 Text string `json:"text"`
314 URL *string `json:"url"` // optional
315 CallbackData *string `json:"callback_data"` // optional
316 SwitchInlineQuery *string `json:"switch_inline_query"` // optional
317}
318
319// CallbackQuery is data sent when a keyboard button with callback data
320// is clicked.
321type CallbackQuery struct {
322 ID string `json:"id"`
323 From User `json:"from"`
324 Message Message `json:"message"` // optional
325 InlineMessageID string `json:"inline_message_id"` // optional
326 Data string `json:"data"` // optional
327}
328
329// ForceReply allows the Bot to have users directly reply to it without
330// additional interaction.
331type ForceReply struct {
332 ForceReply bool `json:"force_reply"`
333 Selective bool `json:"selective"` // optional
334}
335
336// InlineQuery is a Query from Telegram for an inline request.
337type InlineQuery struct {
338 ID string `json:"id"`
339 From User `json:"from"`
340 Location Location `json:"location"` // optional
341 Query string `json:"query"`
342 Offset string `json:"offset"`
343}
344
345// InlineQueryResultArticle is an inline query response article.
346type InlineQueryResultArticle struct {
347 Type string `json:"type"` // required
348 ID string `json:"id"` // required
349 Title string `json:"title"` // required
350 MessageText string `json:"message_text"` // required
351 ParseMode string `json:"parse_mode"`
352 DisableWebPagePreview bool `json:"disable_web_page_preview"`
353 URL string `json:"url"`
354 HideURL bool `json:"hide_url"`
355 Description string `json:"description"`
356 ThumbURL string `json:"thumb_url"`
357 ThumbWidth int `json:"thumb_width"`
358 ThumbHeight int `json:"thumb_height"`
359}
360
361// InlineQueryResultPhoto is an inline query response photo.
362type InlineQueryResultPhoto struct {
363 Type string `json:"type"` // required
364 ID string `json:"id"` // required
365 URL string `json:"photo_url"` // required
366 MimeType string `json:"mime_type"`
367 Width int `json:"photo_width"`
368 Height int `json:"photo_height"`
369 ThumbURL string `json:"thumb_url"`
370 Title string `json:"title"`
371 Description string `json:"description"`
372 Caption string `json:"caption"`
373 MessageText string `json:"message_text"`
374 ParseMode string `json:"parse_mode"`
375 DisableWebPagePreview bool `json:"disable_web_page_preview"`
376}
377
378// InlineQueryResultGIF is an inline query response GIF.
379type InlineQueryResultGIF struct {
380 Type string `json:"type"` // required
381 ID string `json:"id"` // required
382 URL string `json:"gif_url"` // required
383 Width int `json:"gif_width"`
384 Height int `json:"gif_height"`
385 ThumbURL string `json:"thumb_url"`
386 Title string `json:"title"`
387 Caption string `json:"caption"`
388 MessageText string `json:"message_text"`
389 ParseMode string `json:"parse_mode"`
390 DisableWebPagePreview bool `json:"disable_web_page_preview"`
391}
392
393// InlineQueryResultMPEG4GIF is an inline query response MPEG4 GIF.
394type InlineQueryResultMPEG4GIF struct {
395 Type string `json:"type"` // required
396 ID string `json:"id"` // required
397 URL string `json:"mpeg4_url"` // required
398 Width int `json:"mpeg4_width"`
399 Height int `json:"mpeg4_height"`
400 ThumbURL string `json:"thumb_url"`
401 Title string `json:"title"`
402 Caption string `json:"caption"`
403 MessageText string `json:"message_text"`
404 ParseMode string `json:"parse_mode"`
405 DisableWebPagePreview bool `json:"disable_web_page_preview"`
406}
407
408// InlineQueryResultVideo is an inline query response video.
409type InlineQueryResultVideo struct {
410 Type string `json:"type"` // required
411 ID string `json:"id"` // required
412 URL string `json:"video_url"` // required
413 MimeType string `json:"mime_type"` // required
414 MessageText string `json:"message_text"` // required
415 ParseMode string `json:"parse_mode"`
416 DisableWebPagePreview bool `json:"disable_web_page_preview"`
417 Width int `json:"video_width"`
418 Height int `json:"video_height"`
419 ThumbURL string `json:"thumb_url"`
420 Title string `json:"title"`
421 Description string `json:"description"`
422}
423
424// ChosenInlineResult is an inline query result chosen by a User
425type ChosenInlineResult struct {
426 ResultID string `json:"result_id"`
427 From User `json:"from"`
428 Query string `json:"query"`
429}