(new): v1.2 release

tgapi/business_methods.go

@@ -6,7 +6,10 @@ import "context"
 // Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#verifyuser
 type VerifyUser struct {
-	UserID            int64  `json:"user_id"`
+	// UserID Required. Unique identifier of the target user
+	UserID int64 `json:"user_id"`
+	// CustomDescription Optional. Custom description for the verification; 0-70 characters. Must be empty if
+	// the organization isn't allowed to provide a custom verification description.
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
@@ -32,7 +35,11 @@ func (api *API) VerifyUserWithContext(ctx context.Context, params VerifyUser) (b
 // Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#verifychat
 type VerifyChat struct {
-	ChatID            int64  `json:"chat_id"`
+	// ChatID Required. Unique identifier for the target chat or username of the target bot, supergroup or
+	// channel in the format @username. Channel direct messages chats can't be verified.
+	ChatID int64 `json:"chat_id"`
+	// CustomDescription Optional. Custom description for the verification; 0-70 characters. Must be empty if
+	// the organization isn't allowed to provide a custom verification description.
 	CustomDescription string `json:"custom_description,omitempty"`
 }
 
@@ -58,6 +65,7 @@ func (api *API) VerifyChatWithContext(ctx context.Context, params VerifyChat) (b
 // Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#removeuserverification
 type RemoveUserVerification struct {
+	// UserID Required. Unique identifier of the target user
 	UserID int64 `json:"user_id"`
 }
 
@@ -83,6 +91,8 @@ func (api *API) RemoveUserVerificationWithContext(ctx context.Context, params Re
 // Since: Bot API 8.0
 // See https://core.telegram.org/bots/api#removechatverification
 type RemoveChatVerification struct {
+	// ChatID Required. Unique identifier for the target chat or username of the target bot or channel in the
+	// format @username
 	ChatID int64 `json:"chat_id"`
 }
 
@@ -108,9 +118,14 @@ func (api *API) RemoveChatVerificationWithContext(ctx context.Context, params Re
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#readbusinessmessage
 type ReadBusinessMessage struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection on behalf of which to read
+	// the message
 	BusinessConnectionID string `json:"business_connection_id"`
-	ChatID               int64  `json:"chat_id"`
-	MessageID            int    `json:"message_id"`
+	// ChatID Required. Unique identifier of the chat in which the message was received. The chat must have been
+	// active in the last 24 hours.
+	ChatID int64 `json:"chat_id"`
+	// MessageID Required. Unique identifier of the message to mark as read
+	MessageID int `json:"message_id"`
 }
 
 // ReadBusinessMessage marks a business message as read.
@@ -135,6 +150,7 @@ func (api *API) ReadBusinessMessageWithContext(ctx context.Context, params ReadB
 // Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#getbusinessconnection
 type GetBusinessConnection struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
 }
 
@@ -159,8 +175,12 @@ func (api *API) GetBusinessConnectionWithContext(ctx context.Context, params Get
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#deletebusinessmessages
 type DeleteBusinessMessages struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection on behalf of which to delete
+	// the messages
 	BusinessConnectionID string `json:"business_connection_id"`
-	MessageIDs           []int  `json:"message_ids"`
+	// MessageIDs Required. A JSON-serialized list of 1-100 identifiers of messages to delete. All messages must
+	// be from the same chat. See deleteMessage for limitations on which messages can be deleted.
+	MessageIDs []int `json:"message_ids"`
 }
 
 // DeleteBusinessMessages deletes business messages.
@@ -185,9 +205,12 @@ func (api *API) DeleteBusinessMessagesWithContext(ctx context.Context, params De
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountname
 type SetBusinessAccountName struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	FirstName            string `json:"first_name"`
-	LastName             string `json:"last_name,omitempty"`
+	// FirstName Required. The new value of the first name for the business account; 1-64 characters
+	FirstName string `json:"first_name"`
+	// LastName Optional. The new value of the last name for the business account; 0-64 characters
+	LastName string `json:"last_name,omitempty"`
 }
 
 // SetBusinessAccountName sets the first and last name of a business account.
@@ -212,8 +235,10 @@ func (api *API) SetBusinessAccountNameWithContext(ctx context.Context, params Se
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountusername
 type SetBusinessAccountUsername struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	Username             string `json:"username,omitempty"`
+	// Username Optional. The new value of the username for the business account; 0-32 characters
+	Username string `json:"username,omitempty"`
 }
 
 // SetBusinessAccountUsername sets the username of a business account.
@@ -238,8 +263,10 @@ func (api *API) SetBusinessAccountUsernameWithContext(ctx context.Context, param
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountbio
 type SetBusinessAccountBio struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	Bio                  string `json:"bio,omitempty"`
+	// Bio Optional. The new value of the bio for the business account; 0-140 characters
+	Bio string `json:"bio,omitempty"`
 }
 
 // SetBusinessAccountBio sets the bio of a business account.
@@ -264,9 +291,13 @@ func (api *API) SetBusinessAccountBioWithContext(ctx context.Context, params Set
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto
 type SetBusinessAccountProfilePhoto struct {
-	BusinessConnectionID string            `json:"business_connection_id"`
-	Photo                InputProfilePhoto `json:"photo,omitempty"`
-	IsPublic             bool              `json:"is_public,omitempty"`
+	// BusinessConnectionID Required. Unique identifier of the business connection
+	BusinessConnectionID string `json:"business_connection_id"`
+	// Photo Required. The new profile photo to set
+	Photo InputProfilePhoto `json:"photo,omitempty"`
+	// IsPublic Optional. Pass True to set the public photo, which will be visible even if the main photo is
+	// hidden by the business account's privacy settings. An account can have only one public photo.
+	IsPublic bool `json:"is_public,omitempty"`
 }
 
 // SetBusinessAccountProfilePhoto sets the profile photo of a business account.
@@ -291,8 +322,12 @@ func (api *API) SetBusinessAccountProfilePhotoWithContext(ctx context.Context, p
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto
 type RemoveBusinessAccountProfilePhoto struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	IsPublic             bool   `json:"is_public,omitempty"`
+	// IsPublic Optional. Pass True to remove the public photo, which is visible even if the main photo is
+	// hidden by the business account's privacy settings. After the main photo is removed, the previous profile
+	// photo (if present) becomes the main photo.
+	IsPublic bool `json:"is_public,omitempty"`
 }
 
 // RemoveBusinessAccountProfilePhoto removes the profile photo of a business account.
@@ -317,9 +352,13 @@ func (api *API) RemoveBusinessAccountProfilePhotoWithContext(ctx context.Context
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings
 type SetBusinessAccountGiftSettings struct {
-	BusinessConnectionID string            `json:"business_connection_id"`
-	ShowGiftButton       bool              `json:"show_gift_button"`
-	AcceptedGiftTypes    AcceptedGiftTypes `json:"accepted_gift_types"`
+	// BusinessConnectionID Required. Unique identifier of the business connection
+	BusinessConnectionID string `json:"business_connection_id"`
+	// ShowGiftButton Required. Pass True if a button for sending a gift to the user or by the business account
+	// must always be shown in the input field
+	ShowGiftButton bool `json:"show_gift_button"`
+	// AcceptedGiftTypes Required. Types of gifts accepted by the business account
+	AcceptedGiftTypes AcceptedGiftTypes `json:"accepted_gift_types"`
 }
 
 // SetBusinessAccountGiftSettings sets gift settings for a business account.
@@ -344,6 +383,7 @@ func (api *API) SetBusinessAccountGiftSettingsWithContext(ctx context.Context, p
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountstarbalance
 type GetBusinessAccountStarBalance struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
 }
 
@@ -368,8 +408,10 @@ func (api *API) GetBusinessAccountStarBalanceWithContext(ctx context.Context, pa
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#transferbusinessaccountstars
 type TransferBusinessAccountStars struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	StarCount            int    `json:"star_count"`
+	// StarCount Required. Number of Telegram Stars to transfer; 1-10000
+	StarCount int `json:"star_count"`
 }
 
 // TransferBusinessAccountStars transfers stars from a business account.
@@ -394,17 +436,33 @@ func (api *API) TransferBusinessAccountStarsWithContext(ctx context.Context, par
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#getbusinessaccountgifts
 type GetBusinessAccountGifts struct {
-	BusinessConnectionID        string `json:"business_connection_id"`
-	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
-	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
-	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
-	ExcludeLimitedUpgradable    bool   `json:"exclude_limited_upgradable,omitempty"`
-	ExcludeLimitedNonUpgradable bool   `json:"exclude_limited_non_upgradable,omitempty"`
-	ExcludeUnique               bool   `json:"exclude_unique,omitempty"`
-	ExcludeFromBlockchain       bool   `json:"exclude_from_blockchain,omitempty"`
-	SortByPrice                 bool   `json:"sort_by_price,omitempty"`
-	Offset                      string `json:"offset,omitempty"`
-	Limit                       int    `json:"limit,omitempty"`
+	// BusinessConnectionID Required. Unique identifier of the business connection
+	BusinessConnectionID string `json:"business_connection_id"`
+	// ExcludeUnsaved Optional. Pass True to exclude gifts that aren't saved to the account's profile page
+	ExcludeUnsaved bool `json:"exclude_unsaved,omitempty"`
+	// ExcludeSaved Optional. Pass True to exclude gifts that are saved to the account's profile page
+	ExcludeSaved bool `json:"exclude_saved,omitempty"`
+	// ExcludeUnlimited Optional. Pass True to exclude gifts that can be purchased an unlimited number of times
+	ExcludeUnlimited bool `json:"exclude_unlimited,omitempty"`
+	// ExcludeLimitedUpgradable Optional. Pass True to exclude gifts that can be purchased a limited number of
+	// times and can be upgraded to unique
+	ExcludeLimitedUpgradable bool `json:"exclude_limited_upgradable,omitempty"`
+	// ExcludeLimitedNonUpgradable Optional. Pass True to exclude gifts that can be purchased a limited number
+	// of times and can't be upgraded to unique
+	ExcludeLimitedNonUpgradable bool `json:"exclude_limited_non_upgradable,omitempty"`
+	// ExcludeUnique Optional. Pass True to exclude unique gifts
+	ExcludeUnique bool `json:"exclude_unique,omitempty"`
+	// ExcludeFromBlockchain Optional. Pass True to exclude gifts that were assigned from the TON blockchain and
+	// can't be resold or transferred in Telegram
+	ExcludeFromBlockchain bool `json:"exclude_from_blockchain,omitempty"`
+	// SortByPrice Optional. Pass True to sort results by gift price instead of send date. Sorting is applied
+	// before pagination.
+	SortByPrice bool `json:"sort_by_price,omitempty"`
+	// Offset Optional. Offset of the first entry to return as received from the previous request; use empty
+	// string to get the first chunk of results
+	Offset string `json:"offset,omitempty"`
+	// Limit Optional. The maximum number of gifts to be returned; 1-100. Defaults to 100.
+	Limit int `json:"limit,omitempty"`
 }
 
 // GetBusinessAccountGifts returns gifts owned by a business account.
@@ -428,8 +486,10 @@ func (api *API) GetBusinessAccountGiftsWithContext(ctx context.Context, params G
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#convertgifttostars
 type ConvertGiftToStars struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	OwnedGiftID          string `json:"owned_gift_id"`
+	// OwnedGiftID Required. Unique identifier of the regular gift that should be converted to Telegram Stars
+	OwnedGiftID string `json:"owned_gift_id"`
 }
 
 // ConvertGiftToStars converts a gift to Telegram Stars.
@@ -454,10 +514,17 @@ func (api *API) ConvertGiftToStarsWithContext(ctx context.Context, params Conver
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#upgradegift
 type UpgradeGift struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	OwnedGiftID          string `json:"owned_gift_id"`
-	KeepOriginalDetails  bool   `json:"keep_original_details,omitempty"`
-	StarCount            int    `json:"star_count,omitempty"`
+	// OwnedGiftID Required. Unique identifier of the regular gift that should be upgraded to a unique one
+	OwnedGiftID string `json:"owned_gift_id"`
+	// KeepOriginalDetails Optional. Pass True to keep the original gift text, sender and receiver in the
+	// upgraded gift
+	KeepOriginalDetails bool `json:"keep_original_details,omitempty"`
+	// StarCount Optional. The amount of Telegram Stars that will be paid for the upgrade from the business
+	// account balance. If gift.prepaid_upgrade_star_count > 0, then pass 0, otherwise, the can_transfer_stars
+	// business bot right is required and gift.upgrade_star_count must be passed.
+	StarCount int `json:"star_count,omitempty"`
 }
 
 // UpgradeGift upgrades a gift.
@@ -482,10 +549,16 @@ func (api *API) UpgradeGiftWithContext(ctx context.Context, params UpgradeGift)
 // Since: Bot API 9.0
 // See https://core.telegram.org/bots/api#transfergift
 type TransferGift struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	OwnedGiftID          string `json:"owned_gift_id"`
-	NewOwnerChatID       int64  `json:"new_owner_chat_id"`
-	StarCount            int    `json:"star_count,omitempty"`
+	// OwnedGiftID Required. Unique identifier of the regular gift that should be transferred
+	OwnedGiftID string `json:"owned_gift_id"`
+	// NewOwnerChatID Required. Unique identifier of the chat which will own the gift. The chat must be active
+	// in the last 24 hours.
+	NewOwnerChatID int64 `json:"new_owner_chat_id"`
+	// StarCount Optional. The amount of Telegram Stars that will be paid for the transfer from the business
+	// account balance. If positive, then the can_transfer_stars business bot right is required.
+	StarCount int `json:"star_count,omitempty"`
 }
 
 // TransferGift transfers a gift to another chat.
@@ -510,16 +583,29 @@ func (api *API) TransferGiftWithContext(ctx context.Context, params TransferGift
 // Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#poststory
 type PostStory struct {
-	BusinessConnectionID string            `json:"business_connection_id"`
-	Content              InputStoryContent `json:"content"`
-	ActivePeriod         int               `json:"active_period"`
+	// BusinessConnectionID Required. Unique identifier of the business connection
+	BusinessConnectionID string `json:"business_connection_id"`
+	// Content Required. Content of the story
+	Content InputStoryContent `json:"content"`
+	// ActivePeriod Required. Period after which the story is moved to the archive, in seconds; must be one of 6
+	// * 3600, 12 * 3600, 86400, or 2 * 86400
+	ActivePeriod int `json:"active_period"`
 
-	Caption         string          `json:"caption,omitempty"`
-	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	// Caption Optional. Caption of the story, 0-2048 characters after entities parsing
+	Caption string `json:"caption,omitempty"`
+	// ParseMode Optional. Mode for parsing entities in the story caption. See formatting options for more
+	// details.
+	ParseMode ParseMode `json:"parse_mode,omitempty"`
+	// CaptionEntities Optional. A JSON-serialized list of special entities that appear in the caption, which
+	// can be specified instead of parse_mode
 	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
-	Areas           []StoryArea     `json:"areas"`
+	// Areas Optional. A JSON-serialized list of clickable areas to be shown on the story
+	Areas []StoryArea `json:"areas"`
 
+	// PostToChatPage Optional. Pass True to keep the story accessible after it expires
 	PostToChatPage bool `json:"post_to_chat_page,omitempty"`
+	// ProtectContent Optional. Pass True if the content of the story must be protected from forwarding and
+	// screenshotting
 	ProtectContent bool `json:"protect_content,omitempty"`
 }
 
@@ -544,12 +630,20 @@ func (api *API) PostStoryWithContext(ctx context.Context, params PostStory) (Sto
 // Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#repoststory
 type RepostStory struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	FromChatID           int64  `json:"from_chat_id"`
-	FromStoryID          int    `json:"from_story_id"`
-	ActivePeriod         int    `json:"active_period"`
-	PostToChatPage       bool   `json:"post_to_chat_page,omitempty"`
-	ProtectContent       bool   `json:"protect_content,omitempty"`
+	// FromChatID Required. Unique identifier of the chat which posted the story that should be reposted
+	FromChatID int64 `json:"from_chat_id"`
+	// FromStoryID Required. Unique identifier of the story that should be reposted
+	FromStoryID int `json:"from_story_id"`
+	// ActivePeriod Required. Period after which the story is moved to the archive, in seconds; must be one of 6
+	// * 3600, 12 * 3600, 86400, or 2 * 86400
+	ActivePeriod int `json:"active_period"`
+	// PostToChatPage Optional. Pass True to keep the story accessible after it expires
+	PostToChatPage bool `json:"post_to_chat_page,omitempty"`
+	// ProtectContent Optional. Pass True if the content of the story must be protected from forwarding and
+	// screenshotting
+	ProtectContent bool `json:"protect_content,omitempty"`
 }
 
 // RepostStory reposts a story from another chat.
@@ -574,14 +668,23 @@ func (api *API) RepostStoryWithContext(ctx context.Context, params RepostStory)
 // Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#editstory
 type EditStory struct {
-	BusinessConnectionID string            `json:"business_connection_id"`
-	StoryID              int               `json:"story_id"`
-	Content              InputStoryContent `json:"content"`
+	// BusinessConnectionID Required. Unique identifier of the business connection
+	BusinessConnectionID string `json:"business_connection_id"`
+	// StoryID Required. Unique identifier of the story to edit
+	StoryID int `json:"story_id"`
+	// Content Required. Content of the story
+	Content InputStoryContent `json:"content"`
 
-	Caption         string          `json:"caption,omitempty"`
-	ParseMode       ParseMode       `json:"parse_mode,omitempty"`
+	// Caption Optional. Caption of the story, 0-2048 characters after entities parsing
+	Caption string `json:"caption,omitempty"`
+	// ParseMode Optional. Mode for parsing entities in the story caption. See formatting options for more
+	// details.
+	ParseMode ParseMode `json:"parse_mode,omitempty"`
+	// CaptionEntities Optional. A JSON-serialized list of special entities that appear in the caption, which
+	// can be specified instead of parse_mode
 	CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
-	Areas           []StoryArea     `json:"areas,omitempty"`
+	// Areas Optional. A JSON-serialized list of clickable areas to be shown on the story
+	Areas []StoryArea `json:"areas,omitempty"`
 }
 
 // EditStory edits an existing story.
@@ -606,8 +709,10 @@ func (api *API) EditStoryWithContext(ctx context.Context, params EditStory) (Sto
 // Since: Bot API 7.2
 // See https://core.telegram.org/bots/api#deletestory
 type DeleteStory struct {
+	// BusinessConnectionID Required. Unique identifier of the business connection
 	BusinessConnectionID string `json:"business_connection_id"`
-	StoryID              int    `json:"story_id"`
+	// StoryID Required. Unique identifier of the story to delete
+	StoryID int `json:"story_id"`
 }
 
 // DeleteStory deletes a story.