Метод getUserGifts | Telegram Bot API

Описание

Возвращает подарки, которыми владеет и которые разместил пользователь. Возвращает OwnedGifts при успешном выполнении.

Параметр	Тип	Обязательный	Описание
user_id	Integer	Да	Уникальный идентификатор пользователя
exclude_unlimited	Boolean	Необязательный	Передайте True, чтобы исключить подарки, которые можно приобрести неограниченное количество раз
exclude_limited_upgradable	Boolean	Необязательный	Передайте True, чтобы исключить подарки, которые можно приобрести ограниченное количество раз и которые можно улучшить до уникальных
exclude_limited_non_upgradable	Boolean	Необязательный	Передайте True, чтобы исключить подарки, которые можно приобрести ограниченное количество раз и которые нельзя улучшить до уникальных
exclude_from_blockchain	Boolean	Необязательный	Передайте True, чтобы исключить подарки, которые были назначены из блокчейна TON и не могут быть перепроданы или переданы в Telegram
exclude_unique	Boolean	Необязательный	Передайте True, чтобы исключить уникальные подарки
sort_by_price	Boolean	Необязательный	Передайте True, чтобы отсортировать результаты по цене подарка вместо даты отправки. Сортировка применяется до пагинации.
offset	String	Необязательный	Смещение первой записи для возврата, полученное от предыдущего запроса; используйте пустую строку, чтобы получить первую порцию результатов
limit	Integer	Необязательный	Максимальное количество возвращаемых подарков; 1-100. По умолчанию: 100

Примеры

php

<?php
$botToken = 'ВАШ_ТОКЕН_БОТА';
$apiUrl = "https://api.telegram.org/bot{$botToken}/getUserGifts";

// Данные для отправки
$data = [
    'user_id' => 123456789, // ID пользователя
    'exclude_unlimited' => true, // Исключить безлимитные подарки (опционально)
    'exclude_limited_upgradable' => false, // Исключить улучшаемые лимитированные (опционально)
    'exclude_limited_non_upgradable' => false, // Исключить неулучшаемые лимитированные (опционально)
    'exclude_from_blockchain' => true, // Исключить подарки из блокчейна (опционально)
    'exclude_unique' => false, // Исключить уникальные подарки (опционально)
    'sort_by_price' => true, // Сортировать по цене (опционально)
    'offset' => '', // Смещение для пагинации (опционально)
    'limit' => 50 // Лимит результатов 1-100 (опционально, по умолчанию 100)
];

// Отправка запроса
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

// Обработка ответа
$result = json_decode($response, true);
if ($result['ok'] ?? false) {
    $gifts = $result['result'];
    
    // Вывод информации о подарках
    echo "Найдено подарков: " . count($gifts['gifts'] ?? []) . "\n";
    echo "Следующее смещение: " . ($gifts['next_offset'] ?? 'нет') . "\n";
    
    // Вывод списка подарков
    if (!empty($gifts['gifts'])) {
        foreach ($gifts['gifts'] as $index => $gift) {
            echo "\nПодарок #" . ($index + 1) . ":\n";
            echo "ID: " . ($gift['id'] ?? 'N/A') . "\n";
            echo "Название: " . ($gift['title'] ?? 'N/A') . "\n";
            echo "Цена: " . ($gift['price'] ?? 'N/A') . "\n";
            echo "Тип: " . ($gift['type'] ?? 'N/A') . "\n";
        }
    }
} else {
    echo "Ошибка: " . ($result['description'] ?? 'Неизвестная ошибка') . "\n";
}
?>

python

import requests
import json

bot_token = 'ВАШ_ТОКЕН_БОТА'
api_url = f'https://api.telegram.org/bot{bot_token}/getUserGifts'

# Данные для отправки
data = {
    'user_id': 123456789,  # ID пользователя
    'exclude_unlimited': True,  # Исключить безлимитные подарки (опционально)
    'exclude_limited_upgradable': False,  # Исключить улучшаемые лимитированные (опционально)
    'exclude_limited_non_upgradable': False,  # Исключить неулучшаемые лимитированные (опционально)
    'exclude_from_blockchain': True,  # Исключить подарки из блокчейна (опционально)
    'exclude_unique': False,  # Исключить уникальные подарки (опционально)
    'sort_by_price': True,  # Сортировать по цене (опционально)
    'offset': '',  # Смещение для пагинации (опционально)
    'limit': 50  # Лимит результатов 1-100 (опционально, по умолчанию 100)
}

# Отправка запроса
response = requests.post(api_url, json=data)

# Обработка ответа
if response.status_code == 200:
    result = response.json()
    if result.get('ok'):
        gifts = result['result']
        
        # Вывод информации о подарках
        print(f"Найдено подарков: {len(gifts.get('gifts', []))}")
        print(f"Следующее смещение: {gifts.get('next_offset', 'нет')}")
        
        # Вывод списка подарков
        if gifts.get('gifts'):
            for i, gift in enumerate(gifts['gifts'], 1):
                print(f"\nПодарок #{i}:")
                print(f"  ID: {gift.get('id', 'N/A')}")
                print(f"  Название: {gift.get('title', 'N/A')}")
                print(f"  Цена: {gift.get('price', 'N/A')}")
                print(f"  Тип: {gift.get('type', 'N/A')}")
                print(f"  Уникальный: {gift.get('is_unique', False)}")
                print(f"  Улучшаемый: {gift.get('is_upgradable', False)}")
    else:
        print(f"Ошибка: {result.get('description', 'Неизвестная ошибка')}")
else:
    print(f"Ошибка HTTP: {response.status_code}")

История изменений

API 9.3. Добавлен метод getUserGifts

Дополнительно

OwnedGifts - Объект содержит список подарков, принадлежащих пользователю или чату, с информацией об их количестве и возможностью постраничной загрузки.