Metadata-Version: 2.4
Name: neogram
Version: 9.7.1
Summary: Telegram Bot API library
Author-email: SiriLV <siriteamrs@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SiriLV/neogram
Project-URL: Repository, https://github.com/SiriLV/neogram
Keywords: telegram,bot,api,onlysq,telegram-bot,curl_cffi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: curl_cffi>=0.5.0
Requires-Dist: bs4>=0.0.2
Dynamic: license-file

# neogram — документация

**neogram** — современная Python-библиотека для работы с [Telegram Bot API](https://core.telegram.org/bots/api), основанная на `curl_cffi`. Поддерживает синхронный и асинхронный режимы работы, все официальные типы данных Telegram, а также набор вспомогательных AI-инструментов.

---

## Содержание

1. [Установка](#установка)
2. [Быстрый старт](#быстрый-старт)
3. [Класс Bot](#класс-bot)
4. [Класс AsyncBot](#класс-asyncbot)
5. [Обработчики событий](#обработчики-событий)
6. [Типы данных Telegram](#типы-данных-telegram)
7. [InputFile — отправка файлов](#inputfile--отправка-файлов)
8. [Обработка ошибок](#обработка-ошибок)
9. [AI-инструменты (ii.py)](#ai-инструменты-iipy)
   - [OnlySQ](#onlysq)
   - [Deef](#deef)
   - [ChatGPT](#chatgpt)
10. [Полный справочник методов Bot API](#полный-справочник-методов-bot-api)

---

## Установка

```bash
pip install curl_cffi beautifulsoup4
```

Затем поместите папку `neogram/` (содержащую `fgram.py`, `ii.py`, `__init__.py`) в директорию вашего проекта.

```python
import neogram
```

---

## Быстрый старт

### Синхронный бот

```python
from neogram import Bot

bot = Bot(token="ВАШ_ТОКЕН")

@bot.message_handler(commands=["start"])
def start(message):
    bot.send_message(message.chat.id, "Привет! Я бот на neogram 🚀")

@bot.message_handler(content_types=["text"])
def echo(message):
    bot.send_message(message.chat.id, f"Вы написали: {message.text}")

bot.infinity_polling()
```

### Асинхронный бот

```python
import asyncio
from neogram import AsyncBot

bot = AsyncBot(token="ВАШ_ТОКЕН")

@bot.message_handler(commands=["start"])
async def start(message):
    await bot.send_message(message.chat.id, "Привет! Я async-бот 🚀")

async def main():
    await bot.infinity_polling()

asyncio.run(main())
```

---

## Класс Bot

Главный клиент Telegram Bot API. Использует `curl_cffi` для HTTP-запросов с имитацией браузера.

### Конструктор

```python
Bot(
    token: str,
    *,
    api_url: str = "https://api.telegram.org",
    timeout: int = 70,
    impersonate: str = "chrome",
    parse_mode: Optional[str] = None,
    proxies: Optional[dict] = None,
    max_retries: int = 3,
    retry_on_flood: bool = True
)
```

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `token` | `str` | — | Токен бота от @BotFather |
| `api_url` | `str` | `https://api.telegram.org` | URL Telegram Bot API (для локального сервера) |
| `timeout` | `int` | `70` | Таймаут HTTP-запросов в секундах |
| `impersonate` | `str` | `"chrome"` | Браузер для имитации (`curl_cffi`) |
| `parse_mode` | `str` | `None` | Режим форматирования по умолчанию (`"HTML"`, `"Markdown"`, `"MarkdownV2"`) |
| `proxies` | `dict` | `None` | Настройки прокси |
| `max_retries` | `int` | `3` | Число повторных попыток при ошибках |
| `retry_on_flood` | `bool` | `True` | Автоматический retry при flood-ошибке (код 429) |

### Пример с настройками

```python
bot = Bot(
    token="ВАШ_ТОКЕН",
    parse_mode="HTML",
    max_retries=5,
    proxies={"http": "socks5://127.0.0.1:1080"}
)
```

### Управление поллингом

```python
# Запустить поллинг (блокирующий)
bot.polling(timeout=30, allowed_updates=["message", "callback_query"])

# Запустить поллинг с автовосстановлением при ошибках
bot.infinity_polling()

# Остановить поллинг из другого потока
bot.stop_polling()
```

---

## Класс AsyncBot

Асинхронная версия `Bot`. Наследует все методы `Bot`, но каждый метод является `async`-функцией, которую нужно вызывать через `await`.

```python
from neogram import AsyncBot

bot = AsyncBot(token="ВАШ_ТОКЕН", parse_mode="HTML")

@bot.message_handler(commands=["help"])
async def help_handler(message):
    await bot.send_message(message.chat.id, "Список команд: /start, /help")

# Закрыть асинхронную сессию
await bot.aclose()
```

---

## Обработчики событий

Используйте декораторы для регистрации обработчиков. Работают одинаково для `Bot` и `AsyncBot`.

### Типы обработчиков

```python
@bot.message_handler(...)          # входящие сообщения
@bot.edited_message_handler(...)   # отредактированные сообщения
@bot.channel_post_handler(...)     # посты в каналах
@bot.callback_query_handler(...)   # нажатия на inline-кнопки
@bot.inline_handler(...)           # inline-запросы
@bot.poll_handler(...)             # обновления опросов
@bot.poll_answer_handler(...)      # ответы на опросы
@bot.my_chat_member_handler(...)   # изменение статуса бота в чате
@bot.chat_member_handler(...)      # изменение статуса участника чата
@bot.chat_join_request_handler(...)# запросы на вступление
@bot.shipping_query_handler(...)   # запросы доставки
@bot.pre_checkout_query_handler(...)# предчекаут платёж
```

### Фильтры для message_handler

```python
@bot.message_handler(commands=["start", "help"])
def cmd_handler(message): ...

@bot.message_handler(content_types=["photo", "video", "document"])
def media_handler(message): ...

@bot.message_handler(regexp=r"^\d+$")
def digits_handler(message): ...

@bot.message_handler(func=lambda m: m.from_user.id == 123456789)
def admin_handler(message): ...

@bot.message_handler(chat_types=["private"])
def private_handler(message): ...
```

**Тип контента** (`content_types`) может быть одним из: `"text"`, `"audio"`, `"document"`, `"photo"`, `"sticker"`, `"video"`, `"video_note"`, `"voice"`, `"contact"`, `"location"`, `"venue"`, `"animation"`, `"poll"`, `"dice"`, `"pinned_message"`, `"invoice"`, `"successful_payment"`, `"story"` и другие.

### Пример: бот с несколькими обработчиками

```python
from neogram import Bot, InputFile

bot = Bot(token="TOKEN", parse_mode="HTML")

@bot.message_handler(commands=["start"])
def start(message):
    bot.send_message(
        message.chat.id,
        f"👋 Привет, <b>{message.from_user.first_name}</b>!"
    )

@bot.message_handler(commands=["photo"])
def send_photo(message):
    with open("photo.jpg", "rb") as f:
        bot.send_photo(message.chat.id, InputFile(f), caption="Вот фото!")

@bot.callback_query_handler(func=lambda cb: cb.data.startswith("btn_"))
def on_button(callback):
    bot.answer_callback_query(callback.id, text="Кнопка нажата!")
    bot.edit_message_text(
        "Вы нажали кнопку!",
        chat_id=callback.message.chat.id,
        message_id=callback.message.message_id
    )

bot.infinity_polling()
```

---

## Типы данных Telegram

Все объекты Telegram API представлены Python-датаклассами. Они автоматически десериализуются из ответов сервера.

### Основные типы

| Класс | Описание |
|---|---|
| `Update` | Входящее обновление |
| `Message` | Сообщение |
| `User` | Пользователь или бот |
| `Chat` | Чат |
| `ChatFullInfo` | Полная информация о чате |
| `MessageEntity` | Специальная сущность в тексте (ссылки, bold и т.д.) |
| `PhotoSize` | Одно фото определённого размера |
| `Audio` | Аудиофайл |
| `Document` | Документ |
| `Video` | Видеофайл |
| `Animation` | GIF или видео без звука |
| `Voice` | Голосовое сообщение |
| `VideoNote` | Видеосообщение (кружок) |
| `Sticker` | Стикер |
| `Location` | Геопозиция |
| `Contact` | Контакт |
| `Poll` | Опрос |
| `Dice` | Кубик/анимированный эмодзи |

### Кнопки и клавиатуры

| Класс | Описание |
|---|---|
| `InlineKeyboardMarkup` | Inline-клавиатура |
| `InlineKeyboardButton` | Кнопка inline-клавиатуры |
| `ReplyKeyboardMarkup` | Обычная клавиатура |
| `KeyboardButton` | Кнопка обычной клавиатуры |
| `ReplyKeyboardRemove` | Убрать клавиатуру |
| `ForceReply` | Принудительный ответ |
| `CallbackQuery` | Нажатие inline-кнопки |

### Пример: создание inline-клавиатуры

```python
from neogram import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup(inline_keyboard=[[
    InlineKeyboardButton(text="✅ Да", callback_data="yes"),
    InlineKeyboardButton(text="❌ Нет", callback_data="no"),
], [
    InlineKeyboardButton(text="🌐 Сайт", url="https://example.com"),
]])

bot.send_message(chat_id, "Ваш выбор?", reply_markup=keyboard)
```

### Пример: обычная клавиатура

```python
from neogram import ReplyKeyboardMarkup, KeyboardButton

keyboard = ReplyKeyboardMarkup(keyboard=[
    [KeyboardButton(text="📞 Поделиться контактом", request_contact=True)],
    [KeyboardButton(text="📍 Моё местоположение", request_location=True)],
], resize_keyboard=True)

bot.send_message(chat_id, "Выберите действие:", reply_markup=keyboard)
```

### Union-типы (дискриминантные объединения)

В некоторых методах API возвращаются объекты разных подтипов. neogram автоматически определяет правильный подтип по полю-дискриминатору:

```python
# ChatMember может быть одним из:
# ChatMemberOwner, ChatMemberAdministrator, ChatMemberMember,
# ChatMemberRestricted, ChatMemberLeft, ChatMemberBanned

member = bot.get_chat_member(chat_id, user_id)
if isinstance(member, ChatMemberAdministrator):
    print("Это администратор")
```

---

## InputFile — отправка файлов

Для отправки файлов используйте объект `InputFile`.

```python
from neogram import InputFile

# Из пути к файлу
bot.send_document(chat_id, InputFile("document.pdf"))

# Из файлового объекта
with open("image.jpg", "rb") as f:
    bot.send_photo(chat_id, InputFile(f))

# Из bytes
with open("audio.ogg", "rb") as f:
    data = f.read()
bot.send_voice(chat_id, data)  # bytes тоже работают

# По file_id (файл уже загружен на серверы Telegram)
bot.send_photo(chat_id, "AgACAgIAAxkBAAI...")

# По URL
bot.send_photo(chat_id, "https://example.com/image.jpg")
```

---

## Обработка ошибок

```python
from neogram import TelegramAPIError

try:
    bot.send_message(-1, "Тест")
except TelegramAPIError as e:
    print(f"Код ошибки: {e.error_code}")
    print(f"Описание: {e.description}")
    print(f"Параметры: {e.parameters}")  # retry_after, migrate_to_chat_id и т.д.
```

### Автоматические повторные попытки

`Bot` автоматически повторяет запросы при:
- Сетевых ошибках транспортного уровня (с экспоненциальной задержкой до 30 сек)
- Ошибках сервера Telegram (код 5xx)
- Flood-ошибках (код 429) — если `retry_on_flood=True`, ждёт `retry_after` секунд

---

## AI-инструменты (ii.py)

### OnlySQ

Клиент для [OnlySQ API](https://my.onlysq.ru/) — генерация текста и изображений.

```python
from neogram import OnlySQ

ai = OnlySQ(key="ВАШ_КЛЮЧ_ONLYSQ")
```

#### Методы

**`get_models()`** — получить список доступных моделей с фильтрацией:

```python
# Все текстовые модели, которые умеют стриминг
models = ai.get_models(modality="text", can_stream=True)

# Только названия бесплатных моделей
free_names = ai.get_models(max_cost=0.0, return_names=True)
```

| Параметр | Описание |
|---|---|
| `modality` | Фильтр по типу: `"text"`, `"image"` и т.д. |
| `can_tools` | Фильтр: поддержка инструментов |
| `can_think` | Фильтр: поддержка режима «думать» |
| `can_stream` | Фильтр: поддержка стриминга |
| `status` | Фильтр по статусу модели |
| `max_cost` | Максимальная стоимость |
| `return_names` | `True` — вернуть читаемые имена, `False` — ключи |

**`generate_answer()`** — генерация текстового ответа:

```python
response = ai.generate_answer(
    model="gpt-5.2-chat",
    messages=[
        {"role": "system", "content": "Ты помощник"},
        {"role": "user", "content": "Расскажи о Python"}
    ]
)
print(response)
```

**`generate_image()`** — генерация изображения:

```python
success = ai.generate_image(
    model="flux",
    prompt="Кот в космосе, реалистично",
    ratio="16:9",
    filename="cat_space.png"
)
if success:
    bot.send_photo(chat_id, InputFile("cat_space.png"))
```

---

### Deef

Набор полезных утилит: перевод, сокращение ссылок, фоновые задачи, AI-запросы.

```python
from neogram import Deef

deef = Deef()
```

#### Методы

**`translate(text, lang)`** — перевод через Google Translate:

```python
translated = deef.translate("Hello, world!", lang="ru")
print(translated)  # "Привет, мир!"

translated = deef.translate("Bonjour", lang="en")
```

**`short_url(long_url)`** — сокращение ссылки через clck.ru:

```python
short = deef.short_url("https://very-long-url.example.com/path?param=value")
bot.send_message(chat_id, f"Ссылка: {short}")
```

**`run_in_bg(func, *args, **kwargs)`** — выполнить функцию в фоновом потоке:

```python
def heavy_task(chat_id, data):
    # долгая операция...
    bot.send_message(chat_id, "Готово!")

# Запустить асинхронно и сразу вернуться
thread = deef.run_in_bg(heavy_task, message.chat.id, some_data)
```

**`encode_base64(path)`** — закодировать файл в Base64:

```python
b64_string = deef.encode_base64("document.pdf")
```

**`perplexity_ask(model, query)`** — запрос к Perplexity AI с источниками:

```python
result = deef.perplexity_ask(
    model="turbo",
    query="Последние новости Python 3.13"
)
print(result["text"])   # текст ответа
for url in result["urls"]:
    print(url)          # источники

# Доступные модели: "turbo", "auto", "o3pro", "research" и другие
```

**`toolchat(prompt, model)`** — генерация через Toolbaz:

```python
answer = deef.toolchat(
    prompt="Объясни концепцию async/await в Python",
    model="gemini-2.5-flash"
)
```

Доступные модели: `gemini-3-flash`, `gemini-2.5-pro`, `gemini-2.5-flash`, `deepseek-v3.1`, `deepseek-r1`, `gpt-5.2`, `gpt-5`, `claude-sonnet-4`, `grok-4-fast`, `toolbaz-v4.5-fast`, `toolbaz-v4`, `Llama-4-Maverick` и другие.

---

### ChatGPT

Универсальный клиент для OpenAI-совместимых API (OpenAI, OpenRouter, LocalAI и т.д.).

```python
from neogram import ChatGPT

client = ChatGPT(
    url="https://api.openai.com/v1",
    headers={"Authorization": "Bearer sk-..."},
    impersonate="chrome"  # опционально
)
```

#### Методы

**`generate_chat_completion()`** — чат-запрос:

```python
response = client.generate_chat_completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Привет!"}],
    temperature=0.7,
    max_tokens=500
)
answer = response["choices"][0]["message"]["content"]
```

**`generate_image()`** — генерация изображения (DALL-E):

```python
result = client.generate_image(
    prompt="Закат над горами, акварель",
    n=1,
    size="1024x1024",
    response_format="url"
)
image_url = result["data"][0]["url"]
```

**`generate_embedding()`** — создание embedding-вектора:

```python
result = client.generate_embedding(
    model="text-embedding-3-small",
    input_data="Пример текста для эмбеддинга"
)
vector = result["data"][0]["embedding"]
```

**`generate_transcription()`** — транскрипция аудио (Whisper):

```python
with open("audio.mp3", "rb") as f:
    result = client.generate_transcription(
        file=f,
        model="whisper-1",
        language="ru"
    )
print(result["text"])
```

**`get_models()`** — список доступных моделей:

```python
models = client.get_models()
for m in models.get("data", []):
    print(m["id"])
```

---

## Полный справочник методов Bot API

Ниже перечислены все доступные методы `Bot` (и `AsyncBot`) с кратким описанием.

### Webhook и поллинг

```python
bot.get_updates(offset, limit, timeout, allowed_updates)
bot.set_webhook(url, certificate, ip_address, max_connections, ...)
bot.delete_webhook(drop_pending_updates)
bot.get_webhook_info()
```

### Информация о боте

```python
bot.get_me()                  # информация о боте
bot.log_out()                 # выход из облачного API
bot.close()                   # закрыть соединение
```

### Отправка сообщений

```python
bot.send_message(chat_id, text, parse_mode, entities, ...)
bot.forward_message(chat_id, from_chat_id, message_id, ...)
bot.forward_messages(chat_id, from_chat_id, message_ids, ...)
bot.copy_message(chat_id, from_chat_id, message_id, ...)
bot.copy_messages(chat_id, from_chat_id, message_ids, ...)
```

### Отправка медиафайлов

```python
bot.send_photo(chat_id, photo, caption, ...)
bot.send_audio(chat_id, audio, caption, duration, performer, title, ...)
bot.send_document(chat_id, document, caption, ...)
bot.send_video(chat_id, video, duration, width, height, ...)
bot.send_animation(chat_id, animation, ...)
bot.send_voice(chat_id, voice, caption, ...)
bot.send_video_note(chat_id, video_note, ...)
bot.send_media_group(chat_id, media, ...)   # альбом
bot.send_sticker(chat_id, sticker, ...)
bot.send_paid_media(chat_id, star_count, media, ...)
```

### Прочие типы сообщений

```python
bot.send_location(chat_id, latitude, longitude, ...)
bot.send_venue(chat_id, latitude, longitude, title, address, ...)
bot.send_contact(chat_id, phone_number, first_name, ...)
bot.send_poll(chat_id, question, options, ...)
bot.send_dice(chat_id, emoji, ...)
bot.send_game(chat_id, game_short_name, ...)
bot.send_invoice(chat_id, title, description, payload, currency, prices, ...)
bot.send_checklist(business_connection_id, chat_id, checklist, ...)
bot.send_chat_action(chat_id, action)       # "typing", "upload_photo" и т.д.
bot.send_message_draft(chat_id, draft_id, text, ...)  # стриминг сообщения
```

### Редактирование сообщений

```python
bot.edit_message_text(text, chat_id, message_id, ...)
bot.edit_message_caption(chat_id, message_id, caption, ...)
bot.edit_message_media(media, chat_id, message_id, ...)
bot.edit_message_reply_markup(chat_id, message_id, reply_markup)
bot.edit_message_live_location(latitude, longitude, chat_id, message_id, ...)
bot.stop_message_live_location(chat_id, message_id, ...)
bot.edit_message_checklist(business_connection_id, chat_id, message_id, checklist)
bot.stop_poll(chat_id, message_id, ...)
bot.delete_message(chat_id, message_id)
bot.delete_messages(chat_id, message_ids)
```

### Реакции

```python
bot.set_message_reaction(chat_id, message_id, reaction, is_big)
```

### Управление чатом

```python
bot.get_chat(chat_id)
bot.get_chat_administrators(chat_id)
bot.get_chat_member_count(chat_id)
bot.get_chat_member(chat_id, user_id)
bot.leave_chat(chat_id)
bot.set_chat_title(chat_id, title)
bot.set_chat_description(chat_id, description)
bot.set_chat_photo(chat_id, photo)
bot.delete_chat_photo(chat_id)
bot.pin_chat_message(chat_id, message_id, ...)
bot.unpin_chat_message(chat_id, ...)
bot.unpin_all_chat_messages(chat_id)
bot.set_chat_permissions(chat_id, permissions, ...)
bot.set_chat_sticker_set(chat_id, sticker_set_name)
bot.delete_chat_sticker_set(chat_id)
```

### Управление участниками

```python
bot.ban_chat_member(chat_id, user_id, until_date, revoke_messages)
bot.unban_chat_member(chat_id, user_id, only_if_banned)
bot.restrict_chat_member(chat_id, user_id, permissions, ...)
bot.promote_chat_member(chat_id, user_id, ...)
bot.set_chat_administrator_custom_title(chat_id, user_id, custom_title)
bot.set_chat_member_tag(chat_id, user_id, tag)
bot.ban_chat_sender_chat(chat_id, sender_chat_id)
bot.unban_chat_sender_chat(chat_id, sender_chat_id)
bot.approve_chat_join_request(chat_id, user_id)
bot.decline_chat_join_request(chat_id, user_id)
```

### Приглашения

```python
bot.export_chat_invite_link(chat_id)
bot.create_chat_invite_link(chat_id, name, expire_date, member_limit, ...)
bot.edit_chat_invite_link(chat_id, invite_link, ...)
bot.revoke_chat_invite_link(chat_id, invite_link)
bot.create_chat_subscription_invite_link(chat_id, subscription_period, ...)
bot.edit_chat_subscription_invite_link(chat_id, invite_link, ...)
```

### Форум-топики

```python
bot.create_forum_topic(chat_id, name, icon_color, ...)
bot.edit_forum_topic(chat_id, message_thread_id, name, ...)
bot.close_forum_topic(chat_id, message_thread_id)
bot.reopen_forum_topic(chat_id, message_thread_id)
bot.delete_forum_topic(chat_id, message_thread_id)
bot.unpin_all_forum_topic_messages(chat_id, message_thread_id)
bot.get_forum_topic_icon_stickers()
# и другие методы для General-топика
```

### Профиль пользователя

```python
bot.get_user_profile_photos(user_id, offset, limit)
bot.get_user_profile_audios(user_id, offset, limit)
bot.set_user_emoji_status(user_id, emoji_status_custom_emoji_id, ...)
```

### Файлы

```python
bot.get_file(file_id)
# Скачать файл: https://api.telegram.org/file/bot{token}/{file_path}
```

### Настройки бота

```python
bot.set_my_commands(commands, scope, language_code)
bot.delete_my_commands(scope, language_code)
bot.get_my_commands(scope, language_code)
bot.set_my_name(name, language_code)
bot.get_my_name(language_code)
bot.set_my_description(description, language_code)
bot.get_my_description(language_code)
bot.set_my_short_description(short_description, language_code)
bot.get_my_short_description(language_code)
bot.set_my_profile_photo(photo)
bot.remove_my_profile_photo()
bot.set_chat_menu_button(chat_id, menu_button)
bot.get_chat_menu_button(chat_id)
bot.set_my_default_administrator_rights(rights, for_channels)
bot.get_my_default_administrator_rights(for_channels)
```

### Inline-режим

```python
bot.answer_inline_query(inline_query_id, results, cache_time, ...)
bot.answer_callback_query(callback_query_id, text, show_alert, url, ...)
bot.answer_web_app_query(web_app_query_id, result)
bot.save_prepared_inline_message(user_id, result, ...)
bot.save_prepared_keyboard_button(user_id, button)
```

### Стикеры

```python
bot.get_sticker_set(name)
bot.get_custom_emoji_stickers(custom_emoji_ids)
bot.upload_sticker_file(user_id, sticker, sticker_format)
bot.create_new_sticker_set(user_id, name, title, stickers, ...)
bot.add_sticker_to_set(user_id, name, sticker)
bot.set_sticker_position_in_set(sticker, position)
bot.delete_sticker_from_set(sticker)
bot.replace_sticker_in_set(user_id, name, old_sticker, sticker)
bot.set_sticker_set_title(name, title)
bot.set_sticker_set_thumbnail(name, user_id, format, thumbnail)
bot.delete_sticker_set(name)
# и другие методы для кастомных эмодзи и масок
```

### Платежи и Stars

```python
bot.send_invoice(chat_id, title, description, payload, currency, prices, ...)
bot.create_invoice_link(title, description, payload, currency, prices, ...)
bot.answer_shipping_query(shipping_query_id, ok, shipping_options, ...)
bot.answer_pre_checkout_query(pre_checkout_query_id, ok, error_message)
bot.get_my_star_balance()
bot.get_star_transactions(offset, limit)
bot.refund_star_payment(user_id, telegram_payment_charge_id)
bot.edit_user_star_subscription(user_id, telegram_payment_charge_id, is_canceled)
```

### Подарки (Gifts)

```python
bot.get_available_gifts()
bot.send_gift(gift_id, user_id, ...)
bot.gift_premium_subscription(user_id, month_count, star_count, ...)
bot.get_user_gifts(user_id, ...)
bot.get_chat_gifts(chat_id, ...)
bot.convert_gift_to_stars(business_connection_id, owned_gift_id)
bot.upgrade_gift(business_connection_id, owned_gift_id, ...)
bot.transfer_gift(business_connection_id, owned_gift_id, new_owner_chat_id, ...)
```

### Бизнес-аккаунт

```python
bot.get_business_connection(business_connection_id)
bot.read_business_message(business_connection_id, chat_id, message_id)
bot.delete_business_messages(business_connection_id, message_ids)
bot.set_business_account_name(business_connection_id, first_name, ...)
bot.set_business_account_bio(business_connection_id, bio)
bot.get_business_account_star_balance(business_connection_id)
bot.transfer_business_account_stars(business_connection_id, star_count)
bot.get_business_account_gifts(business_connection_id, ...)
# и другие методы управления бизнес-аккаунтом
```

### Верификация

```python
bot.verify_user(user_id, custom_description)
bot.verify_chat(chat_id, custom_description)
bot.remove_user_verification(user_id)
bot.remove_chat_verification(chat_id)
```

### Буст чата

```python
bot.get_user_chat_boosts(chat_id, user_id)
```

### Истории (Stories)

```python
bot.post_story(business_connection_id, content, active_period, ...)
bot.edit_story(business_connection_id, story_id, content, ...)
bot.delete_story(business_connection_id, story_id)
bot.repost_story(business_connection_id, from_chat_id, from_story_id, ...)
```

### Passport

```python
bot.set_passport_data_errors(user_id, errors)
```

### Игры

```python
bot.send_game(chat_id, game_short_name, ...)
bot.set_game_score(user_id, score, chat_id, message_id, ...)
bot.get_game_high_scores(user_id, chat_id, message_id, ...)
```

---

## Практические примеры

### Бот с inline-кнопками и callback

```python
from neogram import Bot, InlineKeyboardMarkup, InlineKeyboardButton

bot = Bot(token="TOKEN", parse_mode="HTML")

def make_menu():
    return InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text="📋 О боте", callback_data="about"),
        InlineKeyboardButton(text="❓ Помощь", callback_data="help"),
    ]])

@bot.message_handler(commands=["start"])
def start(message):
    bot.send_message(
        message.chat.id,
        "Выберите раздел:",
        reply_markup=make_menu()
    )

@bot.callback_query_handler(func=lambda cb: True)
def handle_callback(callback):
    if callback.data == "about":
        text = "Я бот на <b>neogram</b>!"
    else:
        text = "Справка: /start — начало"
    bot.edit_message_text(
        text,
        chat_id=callback.message.chat.id,
        message_id=callback.message.message_id,
        reply_markup=make_menu()
    )
    bot.answer_callback_query(callback.id)

bot.infinity_polling()
```

### AI-бот с OnlySQ

```python
from neogram import Bot, OnlySQ

bot = Bot(token="TOKEN")
ai = OnlySQ(key="ONLYSQ_KEY")

@bot.message_handler(content_types=["text"])
def ai_reply(message):
    bot.send_chat_action(message.chat.id, "typing")
    answer = ai.generate_answer(
        model="gpt-5.2-chat",
        messages=[{"role": "user", "content": message.text}]
    )
    bot.send_message(message.chat.id, answer)

bot.infinity_polling()
```

### Асинхронный бот с переводом

```python
import asyncio
from neogram import AsyncBot, Deef

bot = AsyncBot(token="TOKEN")
deef = Deef()

@bot.message_handler(commands=["translate"])
async def translate_cmd(message):
    parts = message.text.split(maxsplit=1)
    if len(parts) < 2:
        await bot.send_message(message.chat.id, "Использование: /translate текст")
        return
    translated = deef.translate(parts[1], lang="en")
    await bot.send_message(message.chat.id, f"🇬🇧 {translated}")

asyncio.run(bot.infinity_polling())
```

---

## Конфигурация логгера

neogram использует стандартный Python `logging` с именем `"neogram"`:

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
)

# Отключить логи neogram
logging.getLogger("neogram").setLevel(logging.WARNING)
```
