setBusinessAccountGiftSettings

Returns: TrueOfficial docs ↗

Changes the privacy settings pertaining to incoming gifts in a managed business account. Requires the can_change_gift_settings business bot right. Returns True on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

show_gift_buttonBooleanRequired

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

accepted_gift_typesAcceptedGiftTypesRequired

Types of gifts accepted by the business account

Returns

On success, True is returned.

GramIO Usage

// Accept all gift types and show the gift button
bot.on("business_connection", async (ctx) => {
  if (ctx.canChangeGiftSettings && ctx.isEnabled) {
    await bot.api.setBusinessAccountGiftSettings({
      business_connection_id: ctx.id,
      show_gift_button: true,
      accepted_gift_types: {
        unlimited_gifts: true,
        limited_gifts: true,
        unique_gifts: true,
        premium_subscription: true,
        gifts_from_channels: true,
      },
    });
  }
});

// Accept only premium subscriptions and unique gifts, hide the gift button
await bot.api.setBusinessAccountGiftSettings({
  business_connection_id: "your_business_connection_id",
  show_gift_button: false,
  accepted_gift_types: {
    unlimited_gifts: false,
    limited_gifts: false,
    unique_gifts: true,
    premium_subscription: true,
    gifts_from_channels: false,
  },
});

// Disable all incoming gifts
await bot.api.setBusinessAccountGiftSettings({
  business_connection_id: "your_business_connection_id",
  show_gift_button: false,
  accepted_gift_types: {
    unlimited_gifts: false,
    limited_gifts: false,
    unique_gifts: false,
    premium_subscription: false,
    gifts_from_channels: false,
  },
});

Errors

Code	Error	Cause
400	Bad Request: BUSINESS_CONNECTION_INVALID	The business_connection_id is invalid or the connection was revoked — re-fetch from the business_connection event
403	Forbidden: not enough rights	Bot lacks can_change_gift_settings right — check ctx.canChangeGiftSettings before calling
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• All five accepted_gift_types fields must be provided. AcceptedGiftTypes is not a partial — you must explicitly set unlimited_gifts, limited_gifts, unique_gifts, premium_subscription, and gifts_from_channels to true or false.
• show_gift_button controls UI visibility, not acceptance. Even if show_gift_button is false, users may still be able to send gifts if the accepted types allow it. The button just adds a shortcut in the chat input.
• Check canChangeGiftSettings before calling. The bot must have can_change_gift_settings right. Verify with ctx.canChangeGiftSettings when handling business_connection events.
• gifts_from_channels covers unique gift transfers. This field controls whether unique gifts transferred from channels are accepted — useful for businesses that want to accept transferred collectibles.
• business_connection_id must be current. Retrieve from ctx.id in business_connection handlers, or ctx.businessConnectionId in business_message handlers.

See Also

• getBusinessAccountGifts — retrieve gifts owned by the business account
• AcceptedGiftTypes — the gift types configuration object
• setBusinessAccountBio — change the bio
• setBusinessAccountName — change the display name
• BusinessConnection — business connection object with rights (canChangeGiftSettings, isEnabled, etc.)