getBusinessAccountGifts

Returns: OwnedGiftsOfficial docs ↗

Returns the gifts received and owned by a managed business account. Requires the can_view_gifts_and_stars business bot right. Returns OwnedGifts on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

exclude_unsavedBooleanOptional

Pass True to exclude gifts that aren't saved to the account's profile page

exclude_savedBooleanOptional

Pass True to exclude gifts that are saved to the account's profile page

exclude_unlimitedBooleanOptional

Pass True to exclude gifts that can be purchased an unlimited number of times

exclude_limited_upgradableBooleanOptional

Pass True to exclude gifts that can be purchased a limited number of times and can be upgraded to unique

exclude_limited_non_upgradableBooleanOptional

Pass True to exclude gifts that can be purchased a limited number of times and can't be upgraded to unique

exclude_uniqueBooleanOptional

Pass True to exclude unique gifts

exclude_from_blockchainBooleanOptional

Pass True to exclude gifts that were assigned from the TON blockchain and can't be resold or transferred in Telegram

sort_by_priceBooleanOptional

Pass True to sort results by gift price instead of send date. Sorting is applied before pagination.

offsetStringOptional

Offset of the first entry to return as received from the previous request; use empty string to get the first chunk of results

limitIntegerOptional Default: 100

The maximum number of gifts to be returned; 1-100. Defaults to 100

Returns

On success, the OwnedGifts object is returned.

GramIO Usage

// Fetch the first page of owned gifts for a business account
const result = await bot.api.getBusinessAccountGifts({
  business_connection_id: "bc_123",
});

console.log(`Total gifts: ${result.total_count}`);
console.log(`Fetched: ${result.gifts.length}`);

// Fetch only unique gifts, sorted by price
const result = await bot.api.getBusinessAccountGifts({
  business_connection_id: "bc_123",
  exclude_unlimited: true,
  exclude_limited_upgradable: true,
  exclude_limited_non_upgradable: true,
  sort_by_price: true,
  limit: 50,
});

console.log(`Unique gifts: ${result.gifts.length}`);

// Paginate through all owned gifts
async function fetchAllGifts(businessConnectionId: string) {
  const all = [];
  let offset = "";

  do {
    const page = await bot.api.getBusinessAccountGifts({
      business_connection_id: businessConnectionId,
      limit: 100,
      offset,
    });

    all.push(...page.gifts);
    offset = page.next_offset ?? "";
  } while (offset);

  return all;
}

const allGifts = await fetchAllGifts("bc_123");
console.log(`Total fetched: ${allGifts.length}`);

// Check owned gifts when a business connection is established
bot.on("business_connection", async (ctx) => {
  if (!ctx.isEnabled) return;

  const result = await bot.api.getBusinessAccountGifts({
    business_connection_id: ctx.id,
    exclude_from_blockchain: true,
  });

  console.log(`Business account has ${result.total_count} gifts`);
});

Errors

Code	Error	Cause
400	Bad Request: business connection not found	The business_connection_id is invalid or the connection was revoked — verify it's still active with getBusinessConnection
400	Bad Request: not enough rights	The bot lacks the can_view_gifts_and_stars business bot right — check connection.rights before calling
400	Bad Request: invalid offset	The offset string is malformed — always use the next_offset value from a previous response
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

• Requires can_view_gifts_and_stars right. Granted by the business account owner during connection setup — check connection.rights?.can_view_gifts_and_stars before calling to avoid unnecessary errors.
• All exclude_* flags are independent and additive. You can combine any number of them to narrow the result. There's no "include only X" flag — use exclude_* for everything else.
• sort_by_price applies before pagination. Always pass the same value in every paginated request, otherwise ordering shifts and you'll get duplicate or missing entries across pages.
• Pagination uses opaque string offsets. Never construct offset values manually — use next_offset from the previous response. Pass an empty string "" to start from the beginning.
• limit defaults to 100 (the maximum). For quick previews, use a smaller value. Don't fetch more pages than you need — accounts with many gifts can have large result sets.
• Blockchain gifts (exclude_from_blockchain) are TON-assigned and cannot be resold or transferred within Telegram. Exclude them if your workflow only handles tradeable gifts.

See Also

• getBusinessConnection — verify the connection and check available rights before calling
• getBusinessAccountStarBalance — get the Star balance of the same business account
• upgradeGift — upgrade a gift to a unique version
• transferGift — transfer an owned gift to another user
• getAvailableGifts — get all gifts that can be sent by the bot
• OwnedGifts — the return type with gifts array and next_offset
• BusinessConnection — the business connection object with rights info