maxbot-api-client-python 1.1.1__tar.gz → 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. maxbot_api_client_python-1.2.0/PKG-INFO +251 -0
  2. maxbot_api_client_python-1.2.0/README.md +233 -0
  3. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/__init__.py +2 -1
  4. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/api.py +2 -1
  5. maxbot_api_client_python-1.2.0/maxbot_api_client_python/client.py +211 -0
  6. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/exceptions.py +1 -1
  7. maxbot_api_client_python-1.2.0/maxbot_api_client_python/tools/bots.py +54 -0
  8. maxbot_api_client_python-1.2.0/maxbot_api_client_python/tools/chats.py +453 -0
  9. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/tools/helpers.py +92 -70
  10. maxbot_api_client_python-1.2.0/maxbot_api_client_python/tools/messages.py +200 -0
  11. maxbot_api_client_python-1.2.0/maxbot_api_client_python/tools/subscriptions.py +103 -0
  12. maxbot_api_client_python-1.2.0/maxbot_api_client_python/tools/uploads.py +122 -0
  13. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/types/constants.py +1 -1
  14. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/types/models.py +82 -65
  15. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/utils.py +3 -1
  16. maxbot_api_client_python-1.2.0/maxbot_api_client_python.egg-info/PKG-INFO +251 -0
  17. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python.egg-info/SOURCES.txt +1 -1
  18. maxbot_api_client_python-1.2.0/pyproject.toml +25 -0
  19. maxbot_api_client_python-1.1.1/PKG-INFO +0 -266
  20. maxbot_api_client_python-1.1.1/README.md +0 -240
  21. maxbot_api_client_python-1.1.1/maxbot_api_client_python/client.py +0 -195
  22. maxbot_api_client_python-1.1.1/maxbot_api_client_python/tools/bots.py +0 -52
  23. maxbot_api_client_python-1.1.1/maxbot_api_client_python/tools/chats.py +0 -445
  24. maxbot_api_client_python-1.1.1/maxbot_api_client_python/tools/messages.py +0 -194
  25. maxbot_api_client_python-1.1.1/maxbot_api_client_python/tools/subscriptions.py +0 -101
  26. maxbot_api_client_python-1.1.1/maxbot_api_client_python/tools/uploads.py +0 -91
  27. maxbot_api_client_python-1.1.1/maxbot_api_client_python.egg-info/PKG-INFO +0 -266
  28. maxbot_api_client_python-1.1.1/setup.py +0 -27
  29. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/LICENSE +0 -0
  30. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/tools/__init__.py +0 -0
  31. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/types/__init__.py +0 -0
  32. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python.egg-info/dependency_links.txt +0 -0
  33. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python.egg-info/requires.txt +0 -0
  34. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python.egg-info/top_level.txt +0 -0
  35. {maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/setup.cfg +0 -0
maxbot_api_client_python-1.2.0/PKG-INFO ADDED
@@ -0,0 +1,251 @@
1
+ Metadata-Version: 2.4
2
+ Name: maxbot-api-client-python
3
+ Version: 1.2.0
4
+ Summary: Python client for MAX Bot API with Sync and Async support
5
+ Author: Green API
6
+ Project-URL: Homepage, https://github.com/green-api/maxbot-api-client-python
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: License :: OSI Approved :: MIT License
9
+ Classifier: Operating System :: OS Independent
10
+ Requires-Python: >=3.12
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: httpx>=0.24.0
14
+ Requires-Dist: aiofiles>=23.1.0
15
+ Requires-Dist: pydantic>=2.0.0
16
+ Requires-Dist: tenacity>=9.1.2
17
+ Dynamic: license-file
18
+
19
+ # MAX BOT API Client (Python)
20
+
21
+ `maxbot-api-client-python` — это библиотека для интеграции с **MAX BOT API**. Этот проект предоставляет структурированный интерфейс для взаимодействия с конфигурациями бота, управления сообщениями, отправки медиафайлов и подписки на события через *long-polling*.
22
+
23
+ Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
24
+ Ознакомиться с инструкцией можно [по ссылке](https://green-api.com/max-bot-api/docs/before-start/).
25
+
26
+ ## API
27
+
28
+ Документацию по **REST API MAX** можно найти по ссылке [dev.max.ru/docs-api](https://dev.max.ru/docs-api). Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям.
29
+
30
+ Документацию по **MAX BOT API** можно найти по ссылке [green-api.com/max-bot-api/docs](https://green-api.com/max-bot-api/docs/).
31
+
32
+ ## Поддержка
33
+
34
+ [![Support](https://img.shields.io/badge/support@green--bot.com-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:support@green-bot.com)
35
+ [![Support](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/greenapi_support_ru_bot)
36
+ [![Support](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://wa.me/77780739095)
37
+
38
+ ## Руководства и новости
39
+
40
+ [![Guides](https://img.shields.io/badge/YouTube-%23FF0000.svg?style=for-the-badge&logo=YouTube&logoColor=white)](https://www.youtube.com/@green-api)
41
+ [![News](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/green_api)
42
+ [![News](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://whatsapp.com/channel/0029VaHUM5TBA1f7cG29nO1C)
43
+
44
+ ## Установка
45
+
46
+ **Убедитесь, что у вас установлен Python версии 3.12 или выше:**
47
+
48
+ ```shell
49
+ python --version
50
+ ```
51
+
52
+ **Установите библиотеку:**
53
+
54
+ ```bash
55
+ pip install maxbot-api-client-python
56
+ ```
57
+
58
+ **Импорт:**
59
+
60
+ ```python
61
+ from maxbot_api_client_python import API, Config
62
+ ```
63
+
64
+ ## Использование и примеры
65
+
66
+ **Параметры конфигурации:**
67
+
68
+ - `base_url` - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут отправляться по этому корневому адресу. Актуальный адрес указан в [официальной документации](https://dev.max.ru/docs-api).
69
+ - `token` - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после [регистрации или создании бота](https://green-api.com/max-bot-api/docs/before-start/) на платформе [business.max.ru](https://business.max.ru/).
70
+ - `ratelimiter` - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
71
+ - `timeout` - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.
72
+
73
+ **Как инициализировать клиент:**
74
+
75
+ Использование контекстного менеджера (`with` / `async with`) гарантирует, что все сетевые соединения будут автоматически и безопасно закрыты по завершении работы.
76
+
77
+ ```python
78
+ from maxbot_api_client_python import API, Config
79
+
80
+ cfg = Config(
81
+ base_url="https://platform-api.max.ru",
82
+ token="YOUR_BOT_TOKEN",
83
+ ratelimiter=25,
84
+ timeout=30
85
+ )
86
+ # Синхронный режим:
87
+ with API(cfg) as bot:
88
+ pass
89
+ # Асинхронный режим:
90
+ async with API(cfg) as bot:
91
+ pass
92
+ ```
93
+
94
+ **Как получить информацию о боте:**
95
+
96
+ * Ссылка на синхронный пример: [get_bot.py](./examples/sync/get_bot.py)
97
+
98
+ ```python
99
+ with API(cfg) as bot:
100
+ response = bot.bots.get_bot()
101
+ ```
102
+
103
+ * Ссылка на асинхронный пример: [get_bot_async.py](./examples/async/get_bot_async.py)
104
+
105
+ ```python
106
+ async with API(cfg) as bot:
107
+ response = await bot.bots.get_bot_async()
108
+ ```
109
+
110
+ **Как отправить сообщение:**
111
+
112
+ * Ссылка на синхронный пример: [send_message.py](./examples/sync/send_message.py)
113
+
114
+
115
+ ```python
116
+ with API(cfg) as bot:
117
+ response = bot.messages.send_message(SendMessageReq(
118
+ user_id=1234567890,
119
+ text="Hello world!"
120
+ ))
121
+ ```
122
+
123
+ * Ссылка на асинхронный пример: [send_message_async.py](./examples/async/send_message_async.py)
124
+
125
+ ```python
126
+ async with API(cfg) as bot:
127
+ response = await bot.messages.send_message_async(SendMessageReq(
128
+ user_id=1234567890,
129
+ text="Hello world from Async!"
130
+ ))
131
+ ```
132
+
133
+ **Как легко отправить файл (по ссылке или локальный):**
134
+
135
+ * Ссылка на синхронный пример: [send_file.py](./examples/sync/send_file.py)
136
+
137
+ ```python
138
+ with API(cfg) as bot:
139
+ response = bot.helpers.send_file(SendFileReq(
140
+ chat_id=1234567890,
141
+ text="Check this!",
142
+ file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
143
+ ))
144
+ ```
145
+ * Ссылка на асинхронный пример: [send_file_async.py](./examples/async/send_file_async.py)
146
+
147
+ ```python
148
+ async with API(cfg) as bot:
149
+ response = await bot.helpers.send_file_async(SendFileReq(
150
+ chat_id=1234567890,
151
+ text="Посмотри на этот файл!",
152
+ file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
153
+ ))
154
+ ```
155
+
156
+ **Как вручную загрузить файл (для кастомных вложений):**
157
+
158
+ * Ссылка на синхронный пример: [upload_file.py](./examples/sync/upload_file.py)
159
+
160
+ ```python
161
+ with API(cfg) as bot:
162
+ response = bot.uploads.upload_file(UploadFileReq(
163
+ type=UploadType.image,
164
+ file_path="examples/assets/file.jpg"
165
+ ))
166
+ ```
167
+
168
+ * Ссылка на асинхронный пример: [upload_file_async.py](./examples/async/upload_file_async.py)
169
+
170
+ ```python
171
+ async with API(cfg) as bot:
172
+ response = await bot.uploads.upload_file_async(UploadFileReq(
173
+ type=UploadType.image,
174
+ file_path="examples/assets/file.jpg"
175
+ ))
176
+ ```
177
+
178
+ **Как получить входящее уведомление (Long Polling):**
179
+
180
+ * Ссылка на синхронный пример: [get_updates.py](./examples/sync/get_updates.py)
181
+
182
+ ```python
183
+ with API(cfg) as bot:
184
+ response = bot.subscriptions.get_updates(GetUpdatesReq(
185
+ marker=0,
186
+ timeout=30
187
+ ))
188
+ ```
189
+
190
+ * Ссылка на асинхронный пример: [get_updates_async.py](./examples/async/get_updates_async.py)
191
+
192
+ ```python
193
+ async with API(cfg) as bot:
194
+ response = await bot.subscriptions.get_updates_async(GetUpdatesReq(
195
+ marker=0,
196
+ timeout=30
197
+ ))
198
+ ```
199
+
200
+ -----
201
+
202
+ ## Список примеров
203
+
204
+ | Описание | Ссылка на пример |
205
+ | ---------------------------------------------- | ---------------------------------------------------------------- |
206
+ | Как отправить сообщение | [send_message.py](./examples/sync/send_message.py) |
207
+ | Как отправить сообщение *асинхронно* | [get_messages_async.py](./examples/async/get_messages_async.py) |
208
+ | Как получить информацию о боте | [get_bot.py](./examples/sync/get_bot.py) |
209
+ | Как получить информацию о боте *асинхронно* | [get_bot_async.py](./examples/async/get_bot_async.py) |
210
+ | Как загрузить файл | [upload_file.py](./examples/sync/upload_file.py) |
211
+ | Как загрузить файл *асинхронно* | [upload_file_async.py](./examples/async/upload_file_async.py) |
212
+ | Как отправить файл | [send_file.py](./examples/sync/send_file.py) |
213
+ | Как отправить файл *асинхронно* | [send_file_async.py](./examples/async/send_file_async.py) |
214
+ | Как получить входящее уведомление | [get_updates.py](./examples/sync/get_updates.py) |
215
+ | Как получить входящее уведомление *асинхронно* | [get_updates_async.py](./examples/async/get_updates_async.py) |
216
+
217
+ ## Список всех методов библиотеки
218
+
219
+ | Метод API | Описание | Ссылка на документацию MAX | Ссылка на документацию MAX BOT API |
220
+ |-----------------|-------------------------|------------------------------------------------|----------------------------------------------|
221
+ | `bots.get_bot` | Получает информацию о боте | [get_bot](https://dev.max.ru/docs-api/methods/GET/me) | [GetBot](https://green-api.com/max-bot-api/docs/api/bots/GetBot/) |
222
+ | `bots.patch_bot` | Изменяет информацию о боте | | [PatchBot](https://green-api.com/max-bot-api/docs/api/bots/PatchBot/) |
223
+ | `chats.get_chats` | Возвращает список групповых чатов, в которых участвовал бот | [get_chats](https://dev.max.ru/docs-api/methods/GET/chats) | [GetChats](https://green-api.com/max-bot-api/docs/api/chats/GetChats/) |
224
+ | `chats.get_chat` | Возвращает информацию о групповом чате по его ID | [get_chat](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-) | [GetChat](https://green-api.com/max-bot-api/docs/api/chats/GetChat/) |
225
+ | `chats.edit_chat` | Позволяет редактировать информацию о групповом чате | [edit_chat](https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-) | [EditChat](https://green-api.com/max-bot-api/docs/api/chats/EditChat/) |
226
+ | `chats.delete_chat` | Удаляет групповой чат для всех участников | [delete_chat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-) | [DeleteChat](https://green-api.com/max-bot-api/docs/api/chats/DeleteChat/) |
227
+ | `chats.send_action` | Позволяет отправлять следующие действия бота в групповой чат | [send_action](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions) | [SendAction](https://green-api.com/max-bot-api/docs/api/chats/SendAction) |
228
+ | `chats.get_pinned_message` | Возвращает закрепленное сообщение в чате | [get_pinned_message](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin) | [GetPinnedMessage](https://green-api.com/max-bot-api/docs/api/chats/GetPinnedMessage) |
229
+ | `chats.pin_message` | Закрепляет сообщение в групповом чате | [pin_message](https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin) | [PinMessage](https://green-api.com/max-bot-api/docs/api/chats/PinMessage) |
230
+ | `chats.unpin_message` | Удаляет закрепленное сообщение в групповом чате | [unpin_message](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin) | [UnpinMessage](https://green-api.com/max-bot-api/docs/api/chats/UnpinMessage) |
231
+ | `chats.get_chat_membership` | Возвращает членство бота в групповом чате | [get_chat_membership](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me) | [GetChatMembership](https://green-api.com/max-bot-api/docs/api/chats/GetChatMembership) |
232
+ | `chats.leave_chat` | Удаляет бота из группового чата | [leave_chat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me) | [LeaveChat](https://green-api.com/max-bot-api/docs/api/chats/LeaveChat) |
233
+ | `chats.get_chat_admins` | Возвращает список всех администраторов группового чата | [get_chat_admins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins) | [GetChatAdmins](https://green-api.com/max-bot-api/docs/api/chats/GetChatAdmins) |
234
+ | `chats.set_chat_admins` | Назначает участника группы администратором | [set_chat_admins](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins) | [SetChatAdmins](https://green-api.com/max-bot-api/docs/api/chats/SetChatAdmins) |
235
+ | `chats.delete_admin` | Отменяет права администратора пользователя в групповом чате | [delete_admin](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-) | [DeleteAdmin](https://green-api.com/max-bot-api/docs/api/chats/DeleteAdmin) |
236
+ | `chats.get_chat_members` | Возвращает список участников группового чата | [get_chat_members](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members) | [GetChatMembers](https://green-api.com/max-bot-api/docs/api/chats/GetChatMembers) |
237
+ | `chats.add_members` | Добавляет участников в групповой чат | [add_members](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members) | [AddMembers](https://green-api.com/max-bot-api/docs/api/chats/AddMembers) |
238
+ | `chats.delete_member` | Удаляет участника из группового чата | [delete_member](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members) | [DeleteMember](https://green-api.com/max-bot-api/docs/api/chats/DeleteMember) |
239
+ | `subscriptions.get_subscriptions` | Возвращает список подписок на уведомления веб-хуков | [get_subscriptions](https://dev.max.ru/docs-api/methods/GET/subscriptions) | [GetSubscriptions](https://green-api.com/max-bot-api/docs/api/subscriptions/GetSubscriptions) |
240
+ | `subscriptions.subscribe` | Настраивает доставку событий бота через веб-хук | [subscribe](https://dev.max.ru/docs-api/methods/POST/subscriptions) | [Subscribe](https://green-api.com/max-bot-api/docs/api/subscriptions/Subscribe.md) |
241
+ | `subscriptions.unsubscribe` | Отменяет подписку бота на получение обновлений через веб-хук | [unsubscribe](https://dev.max.ru/docs-api/methods/DELETE/subscriptions) | [Unsubscribe](https://green-api.com/max-bot-api/docs/api/subscriptions/Unsubscribe) |
242
+ | `subscriptions.get_updates` | Получает входящие обновления | [get_updates](https://dev.max.ru/docs-api/methods/GET/updates) | [GetUpdates](https://green-api.com/max-bot-api/docs/api/subscriptions/GetUpdates) |
243
+ | `upload.upload_file` | Загружает файл на серверы MAX для последующей передачи | [upload_file](https://dev.max.ru/docs-api/methods/POST/uploads) | [UploadFile](https://green-api.com/max-bot-api/docs/upload/UploadFile) |
244
+ | `helpers.send_file` | Упрощает отправку файлов, автоматически определяя URL или путь | | [SendFile](https://green-api.com/max-bot-api/docs/helpers/SendFile) |
245
+ | `messages.get_messages` | Возвращает информацию о сообщении или массив сообщений из чата | [get_messages](https://dev.max.ru/docs-api/methods/GET/messages) | [GetMessages](https://green-api.com/max-bot-api/docs/api/messages/GetMessages) |
246
+ | `messages.send_message` | Отправляет текстовое или медиа-сообщение указанному пользователю или в чат | [send_message](https://dev.max.ru/docs-api/methods/POST/messages) | [SendMessage](https://green-api.com/max-bot-api/docs/api/messages/SendMessage) |
247
+ | `messages.edit_message` | Редактирует текст или медиафайл ранее отправленного сообщения | [edit_message](https://dev.max.ru/docs-api/methods/PUT/messages) | [EditMessage](https://green-api.com/max-bot-api/docs/api/messages/EditMessage) |
248
+ | `messages.delete_message` | Удаляет сообщение из чата | [delete_message](https://dev.max.ru/docs-api/methods/DELETE/messages) | [DeleteMessage](https://green-api.com/max-bot-api/docs/api/messages/DeleteMessage) |
249
+ | `messages.get_message` | Извлекает содержимое и метаданные конкретного сообщения по его ID | [get_message](https://dev.max.ru/docs-api/methods/GET/messages/-messageId-) | [GetMessage](https://green-api.com/max-bot-api/docs/api/messages/GetMessage) |
250
+ | `messages.get_video_info` | Возвращает подробную информацию о прикрепленном видео | [get_video_info](https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-) | [GetVideoInfo](https://green-api.com/max-bot-api/docs/api/messages/GetVideoInfo) |
251
+ | `messages.answer_callback` | Отправляет ответ после того, как пользователь нажмет кнопку | [answer_callback](https://dev.max.ru/docs-api/methods/POST/answers) | [AnswerCallback](https://green-api.com/max-bot-api/docs/api/messages/AnswerCallback )|
maxbot_api_client_python-1.2.0/README.md ADDED
@@ -0,0 +1,233 @@
1
+ # MAX BOT API Client (Python)
2
+
3
+ `maxbot-api-client-python` — это библиотека для интеграции с **MAX BOT API**. Этот проект предоставляет структурированный интерфейс для взаимодействия с конфигурациями бота, управления сообщениями, отправки медиафайлов и подписки на события через *long-polling*.
4
+
5
+ Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
6
+ Ознакомиться с инструкцией можно [по ссылке](https://green-api.com/max-bot-api/docs/before-start/).
7
+
8
+ ## API
9
+
10
+ Документацию по **REST API MAX** можно найти по ссылке [dev.max.ru/docs-api](https://dev.max.ru/docs-api). Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям.
11
+
12
+ Документацию по **MAX BOT API** можно найти по ссылке [green-api.com/max-bot-api/docs](https://green-api.com/max-bot-api/docs/).
13
+
14
+ ## Поддержка
15
+
16
+ [![Support](https://img.shields.io/badge/support@green--bot.com-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:support@green-bot.com)
17
+ [![Support](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/greenapi_support_ru_bot)
18
+ [![Support](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://wa.me/77780739095)
19
+
20
+ ## Руководства и новости
21
+
22
+ [![Guides](https://img.shields.io/badge/YouTube-%23FF0000.svg?style=for-the-badge&logo=YouTube&logoColor=white)](https://www.youtube.com/@green-api)
23
+ [![News](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/green_api)
24
+ [![News](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://whatsapp.com/channel/0029VaHUM5TBA1f7cG29nO1C)
25
+
26
+ ## Установка
27
+
28
+ **Убедитесь, что у вас установлен Python версии 3.12 или выше:**
29
+
30
+ ```shell
31
+ python --version
32
+ ```
33
+
34
+ **Установите библиотеку:**
35
+
36
+ ```bash
37
+ pip install maxbot-api-client-python
38
+ ```
39
+
40
+ **Импорт:**
41
+
42
+ ```python
43
+ from maxbot_api_client_python import API, Config
44
+ ```
45
+
46
+ ## Использование и примеры
47
+
48
+ **Параметры конфигурации:**
49
+
50
+ - `base_url` - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут отправляться по этому корневому адресу. Актуальный адрес указан в [официальной документации](https://dev.max.ru/docs-api).
51
+ - `token` - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после [регистрации или создании бота](https://green-api.com/max-bot-api/docs/before-start/) на платформе [business.max.ru](https://business.max.ru/).
52
+ - `ratelimiter` - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
53
+ - `timeout` - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.
54
+
55
+ **Как инициализировать клиент:**
56
+
57
+ Использование контекстного менеджера (`with` / `async with`) гарантирует, что все сетевые соединения будут автоматически и безопасно закрыты по завершении работы.
58
+
59
+ ```python
60
+ from maxbot_api_client_python import API, Config
61
+
62
+ cfg = Config(
63
+ base_url="https://platform-api.max.ru",
64
+ token="YOUR_BOT_TOKEN",
65
+ ratelimiter=25,
66
+ timeout=30
67
+ )
68
+ # Синхронный режим:
69
+ with API(cfg) as bot:
70
+ pass
71
+ # Асинхронный режим:
72
+ async with API(cfg) as bot:
73
+ pass
74
+ ```
75
+
76
+ **Как получить информацию о боте:**
77
+
78
+ * Ссылка на синхронный пример: [get_bot.py](./examples/sync/get_bot.py)
79
+
80
+ ```python
81
+ with API(cfg) as bot:
82
+ response = bot.bots.get_bot()
83
+ ```
84
+
85
+ * Ссылка на асинхронный пример: [get_bot_async.py](./examples/async/get_bot_async.py)
86
+
87
+ ```python
88
+ async with API(cfg) as bot:
89
+ response = await bot.bots.get_bot_async()
90
+ ```
91
+
92
+ **Как отправить сообщение:**
93
+
94
+ * Ссылка на синхронный пример: [send_message.py](./examples/sync/send_message.py)
95
+
96
+
97
+ ```python
98
+ with API(cfg) as bot:
99
+ response = bot.messages.send_message(SendMessageReq(
100
+ user_id=1234567890,
101
+ text="Hello world!"
102
+ ))
103
+ ```
104
+
105
+ * Ссылка на асинхронный пример: [send_message_async.py](./examples/async/send_message_async.py)
106
+
107
+ ```python
108
+ async with API(cfg) as bot:
109
+ response = await bot.messages.send_message_async(SendMessageReq(
110
+ user_id=1234567890,
111
+ text="Hello world from Async!"
112
+ ))
113
+ ```
114
+
115
+ **Как легко отправить файл (по ссылке или локальный):**
116
+
117
+ * Ссылка на синхронный пример: [send_file.py](./examples/sync/send_file.py)
118
+
119
+ ```python
120
+ with API(cfg) as bot:
121
+ response = bot.helpers.send_file(SendFileReq(
122
+ chat_id=1234567890,
123
+ text="Check this!",
124
+ file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
125
+ ))
126
+ ```
127
+ * Ссылка на асинхронный пример: [send_file_async.py](./examples/async/send_file_async.py)
128
+
129
+ ```python
130
+ async with API(cfg) as bot:
131
+ response = await bot.helpers.send_file_async(SendFileReq(
132
+ chat_id=1234567890,
133
+ text="Посмотри на этот файл!",
134
+ file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
135
+ ))
136
+ ```
137
+
138
+ **Как вручную загрузить файл (для кастомных вложений):**
139
+
140
+ * Ссылка на синхронный пример: [upload_file.py](./examples/sync/upload_file.py)
141
+
142
+ ```python
143
+ with API(cfg) as bot:
144
+ response = bot.uploads.upload_file(UploadFileReq(
145
+ type=UploadType.image,
146
+ file_path="examples/assets/file.jpg"
147
+ ))
148
+ ```
149
+
150
+ * Ссылка на асинхронный пример: [upload_file_async.py](./examples/async/upload_file_async.py)
151
+
152
+ ```python
153
+ async with API(cfg) as bot:
154
+ response = await bot.uploads.upload_file_async(UploadFileReq(
155
+ type=UploadType.image,
156
+ file_path="examples/assets/file.jpg"
157
+ ))
158
+ ```
159
+
160
+ **Как получить входящее уведомление (Long Polling):**
161
+
162
+ * Ссылка на синхронный пример: [get_updates.py](./examples/sync/get_updates.py)
163
+
164
+ ```python
165
+ with API(cfg) as bot:
166
+ response = bot.subscriptions.get_updates(GetUpdatesReq(
167
+ marker=0,
168
+ timeout=30
169
+ ))
170
+ ```
171
+
172
+ * Ссылка на асинхронный пример: [get_updates_async.py](./examples/async/get_updates_async.py)
173
+
174
+ ```python
175
+ async with API(cfg) as bot:
176
+ response = await bot.subscriptions.get_updates_async(GetUpdatesReq(
177
+ marker=0,
178
+ timeout=30
179
+ ))
180
+ ```
181
+
182
+ -----
183
+
184
+ ## Список примеров
185
+
186
+ | Описание | Ссылка на пример |
187
+ | ---------------------------------------------- | ---------------------------------------------------------------- |
188
+ | Как отправить сообщение | [send_message.py](./examples/sync/send_message.py) |
189
+ | Как отправить сообщение *асинхронно* | [get_messages_async.py](./examples/async/get_messages_async.py) |
190
+ | Как получить информацию о боте | [get_bot.py](./examples/sync/get_bot.py) |
191
+ | Как получить информацию о боте *асинхронно* | [get_bot_async.py](./examples/async/get_bot_async.py) |
192
+ | Как загрузить файл | [upload_file.py](./examples/sync/upload_file.py) |
193
+ | Как загрузить файл *асинхронно* | [upload_file_async.py](./examples/async/upload_file_async.py) |
194
+ | Как отправить файл | [send_file.py](./examples/sync/send_file.py) |
195
+ | Как отправить файл *асинхронно* | [send_file_async.py](./examples/async/send_file_async.py) |
196
+ | Как получить входящее уведомление | [get_updates.py](./examples/sync/get_updates.py) |
197
+ | Как получить входящее уведомление *асинхронно* | [get_updates_async.py](./examples/async/get_updates_async.py) |
198
+
199
+ ## Список всех методов библиотеки
200
+
201
+ | Метод API | Описание | Ссылка на документацию MAX | Ссылка на документацию MAX BOT API |
202
+ |-----------------|-------------------------|------------------------------------------------|----------------------------------------------|
203
+ | `bots.get_bot` | Получает информацию о боте | [get_bot](https://dev.max.ru/docs-api/methods/GET/me) | [GetBot](https://green-api.com/max-bot-api/docs/api/bots/GetBot/) |
204
+ | `bots.patch_bot` | Изменяет информацию о боте | | [PatchBot](https://green-api.com/max-bot-api/docs/api/bots/PatchBot/) |
205
+ | `chats.get_chats` | Возвращает список групповых чатов, в которых участвовал бот | [get_chats](https://dev.max.ru/docs-api/methods/GET/chats) | [GetChats](https://green-api.com/max-bot-api/docs/api/chats/GetChats/) |
206
+ | `chats.get_chat` | Возвращает информацию о групповом чате по его ID | [get_chat](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-) | [GetChat](https://green-api.com/max-bot-api/docs/api/chats/GetChat/) |
207
+ | `chats.edit_chat` | Позволяет редактировать информацию о групповом чате | [edit_chat](https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-) | [EditChat](https://green-api.com/max-bot-api/docs/api/chats/EditChat/) |
208
+ | `chats.delete_chat` | Удаляет групповой чат для всех участников | [delete_chat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-) | [DeleteChat](https://green-api.com/max-bot-api/docs/api/chats/DeleteChat/) |
209
+ | `chats.send_action` | Позволяет отправлять следующие действия бота в групповой чат | [send_action](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions) | [SendAction](https://green-api.com/max-bot-api/docs/api/chats/SendAction) |
210
+ | `chats.get_pinned_message` | Возвращает закрепленное сообщение в чате | [get_pinned_message](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin) | [GetPinnedMessage](https://green-api.com/max-bot-api/docs/api/chats/GetPinnedMessage) |
211
+ | `chats.pin_message` | Закрепляет сообщение в групповом чате | [pin_message](https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin) | [PinMessage](https://green-api.com/max-bot-api/docs/api/chats/PinMessage) |
212
+ | `chats.unpin_message` | Удаляет закрепленное сообщение в групповом чате | [unpin_message](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin) | [UnpinMessage](https://green-api.com/max-bot-api/docs/api/chats/UnpinMessage) |
213
+ | `chats.get_chat_membership` | Возвращает членство бота в групповом чате | [get_chat_membership](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me) | [GetChatMembership](https://green-api.com/max-bot-api/docs/api/chats/GetChatMembership) |
214
+ | `chats.leave_chat` | Удаляет бота из группового чата | [leave_chat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me) | [LeaveChat](https://green-api.com/max-bot-api/docs/api/chats/LeaveChat) |
215
+ | `chats.get_chat_admins` | Возвращает список всех администраторов группового чата | [get_chat_admins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins) | [GetChatAdmins](https://green-api.com/max-bot-api/docs/api/chats/GetChatAdmins) |
216
+ | `chats.set_chat_admins` | Назначает участника группы администратором | [set_chat_admins](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins) | [SetChatAdmins](https://green-api.com/max-bot-api/docs/api/chats/SetChatAdmins) |
217
+ | `chats.delete_admin` | Отменяет права администратора пользователя в групповом чате | [delete_admin](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-) | [DeleteAdmin](https://green-api.com/max-bot-api/docs/api/chats/DeleteAdmin) |
218
+ | `chats.get_chat_members` | Возвращает список участников группового чата | [get_chat_members](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members) | [GetChatMembers](https://green-api.com/max-bot-api/docs/api/chats/GetChatMembers) |
219
+ | `chats.add_members` | Добавляет участников в групповой чат | [add_members](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members) | [AddMembers](https://green-api.com/max-bot-api/docs/api/chats/AddMembers) |
220
+ | `chats.delete_member` | Удаляет участника из группового чата | [delete_member](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members) | [DeleteMember](https://green-api.com/max-bot-api/docs/api/chats/DeleteMember) |
221
+ | `subscriptions.get_subscriptions` | Возвращает список подписок на уведомления веб-хуков | [get_subscriptions](https://dev.max.ru/docs-api/methods/GET/subscriptions) | [GetSubscriptions](https://green-api.com/max-bot-api/docs/api/subscriptions/GetSubscriptions) |
222
+ | `subscriptions.subscribe` | Настраивает доставку событий бота через веб-хук | [subscribe](https://dev.max.ru/docs-api/methods/POST/subscriptions) | [Subscribe](https://green-api.com/max-bot-api/docs/api/subscriptions/Subscribe.md) |
223
+ | `subscriptions.unsubscribe` | Отменяет подписку бота на получение обновлений через веб-хук | [unsubscribe](https://dev.max.ru/docs-api/methods/DELETE/subscriptions) | [Unsubscribe](https://green-api.com/max-bot-api/docs/api/subscriptions/Unsubscribe) |
224
+ | `subscriptions.get_updates` | Получает входящие обновления | [get_updates](https://dev.max.ru/docs-api/methods/GET/updates) | [GetUpdates](https://green-api.com/max-bot-api/docs/api/subscriptions/GetUpdates) |
225
+ | `upload.upload_file` | Загружает файл на серверы MAX для последующей передачи | [upload_file](https://dev.max.ru/docs-api/methods/POST/uploads) | [UploadFile](https://green-api.com/max-bot-api/docs/upload/UploadFile) |
226
+ | `helpers.send_file` | Упрощает отправку файлов, автоматически определяя URL или путь | | [SendFile](https://green-api.com/max-bot-api/docs/helpers/SendFile) |
227
+ | `messages.get_messages` | Возвращает информацию о сообщении или массив сообщений из чата | [get_messages](https://dev.max.ru/docs-api/methods/GET/messages) | [GetMessages](https://green-api.com/max-bot-api/docs/api/messages/GetMessages) |
228
+ | `messages.send_message` | Отправляет текстовое или медиа-сообщение указанному пользователю или в чат | [send_message](https://dev.max.ru/docs-api/methods/POST/messages) | [SendMessage](https://green-api.com/max-bot-api/docs/api/messages/SendMessage) |
229
+ | `messages.edit_message` | Редактирует текст или медиафайл ранее отправленного сообщения | [edit_message](https://dev.max.ru/docs-api/methods/PUT/messages) | [EditMessage](https://green-api.com/max-bot-api/docs/api/messages/EditMessage) |
230
+ | `messages.delete_message` | Удаляет сообщение из чата | [delete_message](https://dev.max.ru/docs-api/methods/DELETE/messages) | [DeleteMessage](https://green-api.com/max-bot-api/docs/api/messages/DeleteMessage) |
231
+ | `messages.get_message` | Извлекает содержимое и метаданные конкретного сообщения по его ID | [get_message](https://dev.max.ru/docs-api/methods/GET/messages/-messageId-) | [GetMessage](https://green-api.com/max-bot-api/docs/api/messages/GetMessage) |
232
+ | `messages.get_video_info` | Возвращает подробную информацию о прикрепленном видео | [get_video_info](https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-) | [GetVideoInfo](https://green-api.com/max-bot-api/docs/api/messages/GetVideoInfo) |
233
+ | `messages.answer_callback` | Отправляет ответ после того, как пользователь нажмет кнопку | [answer_callback](https://dev.max.ru/docs-api/methods/POST/answers) | [AnswerCallback](https://green-api.com/max-bot-api/docs/api/messages/AnswerCallback )|
{maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/__init__.py RENAMED
@@ -1,5 +1,6 @@
1
1
  from maxbot_api_client_python.api import API
2
- from maxbot_api_client_python.client import Config, Client
2
+ from maxbot_api_client_python.client import Client
3
+ from maxbot_api_client_python.types.models import Config
3
4
  from maxbot_api_client_python.types import models
4
5
  from maxbot_api_client_python.types import constants
5
6
  from maxbot_api_client_python import utils
{maxbot_api_client_python-1.1.1 → maxbot_api_client_python-1.2.0}/maxbot_api_client_python/api.py RENAMED
@@ -1,6 +1,7 @@
1
1
  from typing import Any, Self
2
2
 
3
- from maxbot_api_client_python.client import Client, Config
3
+ from maxbot_api_client_python.client import Client
4
+ from maxbot_api_client_python.types.models import Config
4
5
  from maxbot_api_client_python import tools
5
6
 
6
7
  class API: