helpers.go (view raw)
1package tgbotapi
2
3import (
4 "log"
5 "net/url"
6)
7
8// NewMessage creates a new Message.
9//
10// chatID is where to send it, text is the message text.
11func NewMessage(chatID int64, text string) MessageConfig {
12 return MessageConfig{
13 BaseChat: BaseChat{
14 ChatID: chatID,
15 ReplyToMessageID: 0,
16 },
17 Text: text,
18 DisableWebPagePreview: false,
19 }
20}
21
22// NewMessageToChannel creates a new Message that is sent to a channel
23// by username.
24//
25// username is the username of the channel, text is the message text.
26func NewMessageToChannel(username string, text string) MessageConfig {
27 return MessageConfig{
28 BaseChat: BaseChat{
29 ChannelUsername: username,
30 },
31 Text: text,
32 }
33}
34
35// NewForward creates a new forward.
36//
37// chatID is where to send it, fromChatID is the source chat,
38// and messageID is the ID of the original message.
39func NewForward(chatID int64, fromChatID int64, messageID int) ForwardConfig {
40 return ForwardConfig{
41 BaseChat: BaseChat{ChatID: chatID},
42 FromChatID: fromChatID,
43 MessageID: messageID,
44 }
45}
46
47// NewPhotoUpload creates a new photo uploader.
48//
49// chatID is where to send it, file is a string path to the file,
50// FileReader, or FileBytes.
51//
52// Note that you must send animated GIFs as a document.
53func NewPhotoUpload(chatID int64, file interface{}) PhotoConfig {
54 return PhotoConfig{
55 BaseFile: BaseFile{
56 BaseChat: BaseChat{ChatID: chatID},
57 File: file,
58 UseExisting: false,
59 },
60 }
61}
62
63// NewPhotoShare shares an existing photo.
64// You may use this to reshare an existing photo without reuploading it.
65//
66// chatID is where to send it, fileID is the ID of the file
67// already uploaded.
68func NewPhotoShare(chatID int64, fileID string) PhotoConfig {
69 return PhotoConfig{
70 BaseFile: BaseFile{
71 BaseChat: BaseChat{ChatID: chatID},
72 FileID: fileID,
73 UseExisting: true,
74 },
75 }
76}
77
78// NewAudioUpload creates a new audio uploader.
79//
80// chatID is where to send it, file is a string path to the file,
81// FileReader, or FileBytes.
82func NewAudioUpload(chatID int64, file interface{}) AudioConfig {
83 return AudioConfig{
84 BaseFile: BaseFile{
85 BaseChat: BaseChat{ChatID: chatID},
86 File: file,
87 UseExisting: false,
88 },
89 }
90}
91
92// NewAudioShare shares an existing audio file.
93// You may use this to reshare an existing audio file without
94// reuploading it.
95//
96// chatID is where to send it, fileID is the ID of the audio
97// already uploaded.
98func NewAudioShare(chatID int64, fileID string) AudioConfig {
99 return AudioConfig{
100 BaseFile: BaseFile{
101 BaseChat: BaseChat{ChatID: chatID},
102 FileID: fileID,
103 UseExisting: true,
104 },
105 }
106}
107
108// NewDocumentUpload creates a new document uploader.
109//
110// chatID is where to send it, file is a string path to the file,
111// FileReader, or FileBytes.
112func NewDocumentUpload(chatID int64, file interface{}) DocumentConfig {
113 return DocumentConfig{
114 BaseFile: BaseFile{
115 BaseChat: BaseChat{ChatID: chatID},
116 File: file,
117 UseExisting: false,
118 },
119 }
120}
121
122// NewDocumentShare shares an existing document.
123// You may use this to reshare an existing document without
124// reuploading it.
125//
126// chatID is where to send it, fileID is the ID of the document
127// already uploaded.
128func NewDocumentShare(chatID int64, fileID string) DocumentConfig {
129 return DocumentConfig{
130 BaseFile: BaseFile{
131 BaseChat: BaseChat{ChatID: chatID},
132 FileID: fileID,
133 UseExisting: true,
134 },
135 }
136}
137
138// NewStickerUpload creates a new sticker uploader.
139//
140// chatID is where to send it, file is a string path to the file,
141// FileReader, or FileBytes.
142func NewStickerUpload(chatID int64, file interface{}) StickerConfig {
143 return StickerConfig{
144 BaseFile: BaseFile{
145 BaseChat: BaseChat{ChatID: chatID},
146 File: file,
147 UseExisting: false,
148 },
149 }
150}
151
152// NewStickerShare shares an existing sticker.
153// You may use this to reshare an existing sticker without
154// reuploading it.
155//
156// chatID is where to send it, fileID is the ID of the sticker
157// already uploaded.
158func NewStickerShare(chatID int64, fileID string) StickerConfig {
159 return StickerConfig{
160 BaseFile: BaseFile{
161 BaseChat: BaseChat{ChatID: chatID},
162 FileID: fileID,
163 UseExisting: true,
164 },
165 }
166}
167
168// NewVideoUpload creates a new video uploader.
169//
170// chatID is where to send it, file is a string path to the file,
171// FileReader, or FileBytes.
172func NewVideoUpload(chatID int64, file interface{}) VideoConfig {
173 return VideoConfig{
174 BaseFile: BaseFile{
175 BaseChat: BaseChat{ChatID: chatID},
176 File: file,
177 UseExisting: false,
178 },
179 }
180}
181
182// NewVideoShare shares an existing video.
183// You may use this to reshare an existing video without reuploading it.
184//
185// chatID is where to send it, fileID is the ID of the video
186// already uploaded.
187func NewVideoShare(chatID int64, fileID string) VideoConfig {
188 return VideoConfig{
189 BaseFile: BaseFile{
190 BaseChat: BaseChat{ChatID: chatID},
191 FileID: fileID,
192 UseExisting: true,
193 },
194 }
195}
196
197// NewVoiceUpload creates a new voice uploader.
198//
199// chatID is where to send it, file is a string path to the file,
200// FileReader, or FileBytes.
201func NewVoiceUpload(chatID int64, file interface{}) VoiceConfig {
202 return VoiceConfig{
203 BaseFile: BaseFile{
204 BaseChat: BaseChat{ChatID: chatID},
205 File: file,
206 UseExisting: false,
207 },
208 }
209}
210
211// NewVoiceShare shares an existing voice.
212// You may use this to reshare an existing voice without reuploading it.
213//
214// chatID is where to send it, fileID is the ID of the video
215// already uploaded.
216func NewVoiceShare(chatID int64, fileID string) VoiceConfig {
217 return VoiceConfig{
218 BaseFile: BaseFile{
219 BaseChat: BaseChat{ChatID: chatID},
220 FileID: fileID,
221 UseExisting: true,
222 },
223 }
224}
225
226// NewContact allows you to send a shared contact.
227func NewContact(chatID int64, phoneNumber, firstName string) ContactConfig {
228 return ContactConfig{
229 BaseChat: BaseChat{
230 ChatID: chatID,
231 },
232 PhoneNumber: phoneNumber,
233 FirstName: firstName,
234 }
235}
236
237// NewLocation shares your location.
238//
239// chatID is where to send it, latitude and longitude are coordinates.
240func NewLocation(chatID int64, latitude float64, longitude float64) LocationConfig {
241 return LocationConfig{
242 BaseChat: BaseChat{
243 ChatID: chatID,
244 },
245 Latitude: latitude,
246 Longitude: longitude,
247 }
248}
249
250// NewVenue allows you to send a venue and its location.
251func NewVenue(chatID int64, title, address string, latitude, longitude float64) VenueConfig {
252 return VenueConfig{
253 BaseChat: BaseChat{
254 ChatID: chatID,
255 },
256 Title: title,
257 Address: address,
258 Latitude: latitude,
259 Longitude: longitude,
260 }
261}
262
263// NewChatAction sets a chat action.
264// Actions last for 5 seconds, or until your next action.
265//
266// chatID is where to send it, action should be set via Chat constants.
267func NewChatAction(chatID int64, action string) ChatActionConfig {
268 return ChatActionConfig{
269 BaseChat: BaseChat{ChatID: chatID},
270 Action: action,
271 }
272}
273
274// NewUserProfilePhotos gets user profile photos.
275//
276// userID is the ID of the user you wish to get profile photos from.
277func NewUserProfilePhotos(userID int) UserProfilePhotosConfig {
278 return UserProfilePhotosConfig{
279 UserID: userID,
280 Offset: 0,
281 Limit: 0,
282 }
283}
284
285// NewUpdate gets updates since the last Offset.
286//
287// offset is the last Update ID to include.
288// You likely want to set this to the last Update ID plus 1.
289func NewUpdate(offset int) UpdateConfig {
290 return UpdateConfig{
291 Offset: offset,
292 Limit: 0,
293 Timeout: 0,
294 }
295}
296
297// NewWebhook creates a new webhook.
298//
299// link is the url parsable link you wish to get the updates.
300func NewWebhook(link string) WebhookConfig {
301 u, _ := url.Parse(link)
302
303 return WebhookConfig{
304 URL: u,
305 }
306}
307
308// NewWebhookWithCert creates a new webhook with a certificate.
309//
310// link is the url you wish to get webhooks,
311// file contains a string to a file, FileReader, or FileBytes.
312func NewWebhookWithCert(link string, file interface{}) WebhookConfig {
313 u, _ := url.Parse(link)
314
315 return WebhookConfig{
316 URL: u,
317 Certificate: file,
318 }
319}
320
321// NewWebhookWithCert creates a new webhook with a certificate and max_connections.
322//
323// link is the url you wish to get webhooks,
324// file contains a string to a file, FileReader, or FileBytes.
325// maxConnections defines maximum number of connections from telegram to your server
326func NewWebhookWithCertAndMaxConnections(link string, file interface{}, maxConnections int) WebhookConfig {
327 u, _ := url.Parse(link)
328
329 return WebhookConfig{
330 URL: u,
331 Certificate: file,
332 MaxConnections: maxConnections,
333 }
334}
335
336// NewInlineQueryResultArticle creates a new inline query article.
337func NewInlineQueryResultArticle(id, title, messageText string) InlineQueryResultArticle {
338 return InlineQueryResultArticle{
339 Type: "article",
340 ID: id,
341 Title: title,
342 InputMessageContent: InputTextMessageContent{
343 Text: messageText,
344 },
345 }
346}
347
348// NewInlineQueryResultArticleMarkdown creates a new inline query article with Markdown parsing.
349func NewInlineQueryResultArticleMarkdown(id, title, messageText string) InlineQueryResultArticle {
350 return InlineQueryResultArticle{
351 Type: "article",
352 ID: id,
353 Title: title,
354 InputMessageContent: InputTextMessageContent{
355 Text: messageText,
356 ParseMode: "Markdown",
357 },
358 }
359}
360
361// NewInlineQueryResultArticleHTML creates a new inline query article with HTML parsing.
362func NewInlineQueryResultArticleHTML(id, title, messageText string) InlineQueryResultArticle {
363 return InlineQueryResultArticle{
364 Type: "article",
365 ID: id,
366 Title: title,
367 InputMessageContent: InputTextMessageContent{
368 Text: messageText,
369 ParseMode: "HTML",
370 },
371 }
372}
373
374// NewInlineQueryResultGIF creates a new inline query GIF.
375func NewInlineQueryResultGIF(id, url string) InlineQueryResultGIF {
376 return InlineQueryResultGIF{
377 Type: "gif",
378 ID: id,
379 URL: url,
380 }
381}
382
383// NewInlineQueryResultMPEG4GIF creates a new inline query MPEG4 GIF.
384func NewInlineQueryResultMPEG4GIF(id, url string) InlineQueryResultMPEG4GIF {
385 return InlineQueryResultMPEG4GIF{
386 Type: "mpeg4_gif",
387 ID: id,
388 URL: url,
389 }
390}
391
392// NewInlineQueryResultPhoto creates a new inline query photo.
393func NewInlineQueryResultPhoto(id, url string) InlineQueryResultPhoto {
394 return InlineQueryResultPhoto{
395 Type: "photo",
396 ID: id,
397 URL: url,
398 }
399}
400
401// NewInlineQueryResultPhotoWithThumb creates a new inline query photo.
402func NewInlineQueryResultPhotoWithThumb(id, url, thumb string) InlineQueryResultPhoto {
403 return InlineQueryResultPhoto{
404 Type: "photo",
405 ID: id,
406 URL: url,
407 ThumbURL: thumb,
408 }
409}
410
411// NewInlineQueryResultVideo creates a new inline query video.
412func NewInlineQueryResultVideo(id, url string) InlineQueryResultVideo {
413 return InlineQueryResultVideo{
414 Type: "video",
415 ID: id,
416 URL: url,
417 }
418}
419
420// NewInlineQueryResultAudio creates a new inline query audio.
421func NewInlineQueryResultAudio(id, url, title string) InlineQueryResultAudio {
422 return InlineQueryResultAudio{
423 Type: "audio",
424 ID: id,
425 URL: url,
426 Title: title,
427 }
428}
429
430// NewInlineQueryResultVoice creates a new inline query voice.
431func NewInlineQueryResultVoice(id, url, title string) InlineQueryResultVoice {
432 return InlineQueryResultVoice{
433 Type: "voice",
434 ID: id,
435 URL: url,
436 Title: title,
437 }
438}
439
440// NewInlineQueryResultDocument creates a new inline query document.
441func NewInlineQueryResultDocument(id, url, title, mimeType string) InlineQueryResultDocument {
442 return InlineQueryResultDocument{
443 Type: "document",
444 ID: id,
445 URL: url,
446 Title: title,
447 MimeType: mimeType,
448 }
449}
450
451// NewInlineQueryResultLocation creates a new inline query location.
452func NewInlineQueryResultLocation(id, title string, latitude, longitude float64) InlineQueryResultLocation {
453 return InlineQueryResultLocation{
454 Type: "location",
455 ID: id,
456 Title: title,
457 Latitude: latitude,
458 Longitude: longitude,
459 }
460}
461
462// NewEditMessageText allows you to edit the text of a message.
463func NewEditMessageText(chatID int64, messageID int, text string) EditMessageTextConfig {
464 return EditMessageTextConfig{
465 BaseEdit: BaseEdit{
466 ChatID: chatID,
467 MessageID: messageID,
468 },
469 Text: text,
470 }
471}
472
473// NewEditMessageCaption allows you to edit the caption of a message.
474func NewEditMessageCaption(chatID int64, messageID int, caption string) EditMessageCaptionConfig {
475 return EditMessageCaptionConfig{
476 BaseEdit: BaseEdit{
477 ChatID: chatID,
478 MessageID: messageID,
479 },
480 Caption: caption,
481 }
482}
483
484// NewEditMessageReplyMarkup allows you to edit the inline
485// keyboard markup.
486func NewEditMessageReplyMarkup(chatID int64, messageID int, replyMarkup InlineKeyboardMarkup) EditMessageReplyMarkupConfig {
487 return EditMessageReplyMarkupConfig{
488 BaseEdit: BaseEdit{
489 ChatID: chatID,
490 MessageID: messageID,
491 ReplyMarkup: &replyMarkup,
492 },
493 }
494}
495
496// NewHideKeyboard hides the keyboard, with the option for being selective
497// or hiding for everyone.
498func NewHideKeyboard(selective bool) ReplyKeyboardHide {
499 log.Println("NewHideKeyboard is deprecated, please use NewRemoveKeyboard")
500
501 return ReplyKeyboardHide{
502 HideKeyboard: true,
503 Selective: selective,
504 }
505}
506
507// NewRemoveKeyboard hides the keyboard, with the option for being selective
508// or hiding for everyone.
509func NewRemoveKeyboard(selective bool) ReplyKeyboardRemove {
510 return ReplyKeyboardRemove{
511 RemoveKeyboard: true,
512 Selective: selective,
513 }
514}
515
516// NewKeyboardButton creates a regular keyboard button.
517func NewKeyboardButton(text string) KeyboardButton {
518 return KeyboardButton{
519 Text: text,
520 }
521}
522
523// NewKeyboardButtonContact creates a keyboard button that requests
524// user contact information upon click.
525func NewKeyboardButtonContact(text string) KeyboardButton {
526 return KeyboardButton{
527 Text: text,
528 RequestContact: true,
529 }
530}
531
532// NewKeyboardButtonLocation creates a keyboard button that requests
533// user location information upon click.
534func NewKeyboardButtonLocation(text string) KeyboardButton {
535 return KeyboardButton{
536 Text: text,
537 RequestLocation: true,
538 }
539}
540
541// NewKeyboardButtonRow creates a row of keyboard buttons.
542func NewKeyboardButtonRow(buttons ...KeyboardButton) []KeyboardButton {
543 var row []KeyboardButton
544
545 row = append(row, buttons...)
546
547 return row
548}
549
550// NewReplyKeyboard creates a new regular keyboard with sane defaults.
551func NewReplyKeyboard(rows ...[]KeyboardButton) ReplyKeyboardMarkup {
552 var keyboard [][]KeyboardButton
553
554 keyboard = append(keyboard, rows...)
555
556 return ReplyKeyboardMarkup{
557 ResizeKeyboard: true,
558 Keyboard: keyboard,
559 }
560}
561
562// NewInlineKeyboardButtonData creates an inline keyboard button with text
563// and data for a callback.
564func NewInlineKeyboardButtonData(text, data string) InlineKeyboardButton {
565 return InlineKeyboardButton{
566 Text: text,
567 CallbackData: &data,
568 }
569}
570
571// NewInlineKeyboardButtonURL creates an inline keyboard button with text
572// which goes to a URL.
573func NewInlineKeyboardButtonURL(text, url string) InlineKeyboardButton {
574 return InlineKeyboardButton{
575 Text: text,
576 URL: &url,
577 }
578}
579
580// NewInlineKeyboardButtonSwitch creates an inline keyboard button with
581// text which allows the user to switch to a chat or return to a chat.
582func NewInlineKeyboardButtonSwitch(text, sw string) InlineKeyboardButton {
583 return InlineKeyboardButton{
584 Text: text,
585 SwitchInlineQuery: &sw,
586 }
587}
588
589// NewInlineKeyboardRow creates an inline keyboard row with buttons.
590func NewInlineKeyboardRow(buttons ...InlineKeyboardButton) []InlineKeyboardButton {
591 var row []InlineKeyboardButton
592
593 row = append(row, buttons...)
594
595 return row
596}
597
598// NewInlineKeyboardMarkup creates a new inline keyboard.
599func NewInlineKeyboardMarkup(rows ...[]InlineKeyboardButton) InlineKeyboardMarkup {
600 var keyboard [][]InlineKeyboardButton
601
602 keyboard = append(keyboard, rows...)
603
604 return InlineKeyboardMarkup{
605 InlineKeyboard: keyboard,
606 }
607}
608
609// NewCallback creates a new callback message.
610func NewCallback(id, text string) CallbackConfig {
611 return CallbackConfig{
612 CallbackQueryID: id,
613 Text: text,
614 ShowAlert: false,
615 }
616}
617
618// NewCallbackWithAlert creates a new callback message that alerts
619// the user.
620func NewCallbackWithAlert(id, text string) CallbackConfig {
621 return CallbackConfig{
622 CallbackQueryID: id,
623 Text: text,
624 ShowAlert: true,
625 }
626}