From 76460f8a5b8b89b816998eefbac35b80ec96a06f Mon Sep 17 00:00:00 2001 From: Syfaro Date: Fri, 26 Jun 2015 00:52:12 -0500 Subject: [PATCH] comments on methods --- methods.go | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/methods.go b/methods.go index f88c416..69a8ca0 100644 --- a/methods.go +++ b/methods.go @@ -115,6 +115,8 @@ type WebhookConfig struct { Url *url.URL } +// Makes a request to a specific endpoint with our token +// All requests are POSTs because Telegram doesn't care, and it's easier func (bot *BotApi) MakeRequest(endpoint string, params url.Values) (ApiResponse, error) { resp, err := http.PostForm("https://api.telegram.org/bot"+bot.Token+"/"+endpoint, params) defer resp.Body.Close() @@ -141,6 +143,8 @@ func (bot *BotApi) MakeRequest(endpoint string, params url.Values) (ApiResponse, return apiResp, nil } +// Makes a request to the API with a file +// Requires the parameter to hold the file not be in the params func (bot *BotApi) UploadFile(endpoint string, params map[string]string, fieldname string, filename string) (ApiResponse, error) { var b bytes.Buffer w := multipart.NewWriter(&b) @@ -199,6 +203,8 @@ func (bot *BotApi) UploadFile(endpoint string, params map[string]string, fieldna return apiResp, nil } +// Fetches the currently authenticated bot +// There are no parameters for this method func (bot *BotApi) GetMe() (User, error) { resp, err := bot.MakeRequest("getMe", nil) if err != nil { @@ -215,6 +221,9 @@ func (bot *BotApi) GetMe() (User, error) { return user, nil } +// Sends a Message to a chat +// Requires ChatId and Text +// DisableWebPagePreview, ReplyToMessageId, and ReplyMarkup are optional func (bot *BotApi) SendMessage(config MessageConfig) (Message, error) { v := url.Values{} v.Add("chat_id", strconv.Itoa(config.ChatId)) @@ -248,6 +257,8 @@ func (bot *BotApi) SendMessage(config MessageConfig) (Message, error) { return message, nil } +// Forwards a message from one chat to another +// Requires ChatId (destionation), FromChatId (source), and MessageId func (bot *BotApi) ForwardMessage(config ForwardConfig) (Message, error) { v := url.Values{} v.Add("chat_id", strconv.Itoa(config.ChatId)) @@ -270,6 +281,9 @@ func (bot *BotApi) ForwardMessage(config ForwardConfig) (Message, error) { return message, nil } +// Sends or uploads a photo to a chat +// Requires ChatId and FileId OR FilePath +// Caption, ReplyToMessageId, and ReplyMarkup are optional func (bot *BotApi) SendPhoto(config PhotoConfig) (Message, error) { if config.UseExistingPhoto { v := url.Values{} @@ -338,6 +352,9 @@ func (bot *BotApi) SendPhoto(config PhotoConfig) (Message, error) { return message, nil } +// Sends or uploads an audio clip to a chat +// Requires ChatId and FileId OR FilePath +// ReplyToMessageId and ReplyMarkup are optional func (bot *BotApi) SendAudio(config AudioConfig) (Message, error) { if config.UseExistingAudio { v := url.Values{} @@ -401,6 +418,9 @@ func (bot *BotApi) SendAudio(config AudioConfig) (Message, error) { return message, nil } +// Sends or uploads a document to a chat +// Requires ChatId and FileId OR FilePath +// ReplyToMessageId and ReplyMarkup are optional func (bot *BotApi) SendDocument(config DocumentConfig) (Message, error) { if config.UseExistingDocument { v := url.Values{} @@ -464,6 +484,9 @@ func (bot *BotApi) SendDocument(config DocumentConfig) (Message, error) { return message, nil } +// Sends or uploads a sticker to a chat +// Requires ChatId and FileId OR FilePath +// ReplyToMessageId and ReplyMarkup are optional func (bot *BotApi) SendSticker(config StickerConfig) (Message, error) { if config.UseExistingSticker { v := url.Values{} @@ -527,6 +550,9 @@ func (bot *BotApi) SendSticker(config StickerConfig) (Message, error) { return message, nil } +// Sends or uploads a video to a chat +// Requires ChatId and FileId OR FilePath +// ReplyToMessageId and ReplyMarkup are optional func (bot *BotApi) SendVideo(config VideoConfig) (Message, error) { if config.UseExistingVideo { v := url.Values{} @@ -590,6 +616,9 @@ func (bot *BotApi) SendVideo(config VideoConfig) (Message, error) { return message, nil } +// Sends a location to a chat +// Requires ChatId, Latitude, and Longitude +// ReplyToMessageId and ReplyMarkup are optional func (bot *BotApi) SendLocation(config LocationConfig) (Message, error) { v := url.Values{} v.Add("chat_id", strconv.Itoa(config.ChatId)) @@ -623,6 +652,8 @@ func (bot *BotApi) SendLocation(config LocationConfig) (Message, error) { return message, nil } +// Sets a current action in a chat +// Requires ChatId and a valid Action (see CHAT constants) func (bot *BotApi) SendChatAction(config ChatActionConfig) error { v := url.Values{} v.Add("chat_id", strconv.Itoa(config.ChatId)) @@ -636,6 +667,9 @@ func (bot *BotApi) SendChatAction(config ChatActionConfig) error { return nil } +// Gets a user's profile photos +// Requires UserId +// Offset and Limit are optional func (bot *BotApi) GetUserProfilePhotos(config UserProfilePhotosConfig) (UserProfilePhotos, error) { v := url.Values{} v.Add("user_id", strconv.Itoa(config.UserId)) @@ -662,6 +696,11 @@ func (bot *BotApi) GetUserProfilePhotos(config UserProfilePhotosConfig) (UserPro return profilePhotos, nil } +// Fetches updates +// If a WebHook is set, this will not return any data! +// Offset, Limit, and Timeout are optional. +// To not get old items, set Offset to one higher than the previous item +// Set Timeout to a large number to reduce requests and get responses instantly func (bot *BotApi) GetUpdates(config UpdateConfig) ([]Update, error) { v := url.Values{} if config.Offset > 0 { @@ -689,6 +728,9 @@ func (bot *BotApi) GetUpdates(config UpdateConfig) ([]Update, error) { return updates, nil } +// Sets a webhook +// If this is set, GetUpdates will not get any data! +// Requires Url OR to set Clear to true func (bot *BotApi) SetWebhook(config WebhookConfig) error { v := url.Values{} if !config.Clear {