maxbot-api-client-python 1.1.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.
- maxbot_api_client_python-1.1.0/LICENSE +21 -0
- maxbot_api_client_python-1.1.0/PKG-INFO +241 -0
- maxbot_api_client_python-1.1.0/README.md +215 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/__init__.py +7 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/api.py +35 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/client.py +195 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/exceptions.py +36 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/__init__.py +8 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/bots.py +52 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/chats.py +445 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/helpers.py +259 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/messages.py +194 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/subscriptions.py +101 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/tools/uploads.py +91 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/types/__init__.py +4 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/types/constants.py +109 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/types/models.py +458 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python/utils.py +68 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python.egg-info/PKG-INFO +241 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python.egg-info/SOURCES.txt +23 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python.egg-info/dependency_links.txt +1 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python.egg-info/requires.txt +4 -0
- maxbot_api_client_python-1.1.0/maxbot_api_client_python.egg-info/top_level.txt +1 -0
- maxbot_api_client_python-1.1.0/setup.cfg +4 -0
- maxbot_api_client_python-1.1.0/setup.py +27 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 GREEN-API
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: maxbot-api-client-python
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Python client for MAX Bot API with Sync and Async support
|
|
5
|
+
Home-page: https://github.com/green-api/maxbot-api-client-python
|
|
6
|
+
Author: Green API
|
|
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: author
|
|
18
|
+
Dynamic: classifier
|
|
19
|
+
Dynamic: description
|
|
20
|
+
Dynamic: description-content-type
|
|
21
|
+
Dynamic: home-page
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
Dynamic: requires-dist
|
|
24
|
+
Dynamic: requires-python
|
|
25
|
+
Dynamic: summary
|
|
26
|
+
|
|
27
|
+
# MAX BOT API Client (Python)
|
|
28
|
+
|
|
29
|
+
`maxbot-api-client-python` — это библиотека для интеграции с MAX BOT API. Этот проект предоставляет структурированный интерфейс для взаимодействия с конфигурациями бота, управления сообщениями, отправки медиафайлов и подписки на события через long-polling.
|
|
30
|
+
|
|
31
|
+
Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
|
|
32
|
+
|
|
33
|
+
## API
|
|
34
|
+
|
|
35
|
+
Документацию по REST API MAX можно найти по ссылке https://dev.max.ru/docs-api. Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям и параметрам запроса.
|
|
36
|
+
|
|
37
|
+
## Поддержка
|
|
38
|
+
|
|
39
|
+
[](mailto:support@green-bot.com)
|
|
40
|
+
[](https://t.me/greenapi_support_ru_bot)
|
|
41
|
+
[](https://wa.me/77780739095)
|
|
42
|
+
|
|
43
|
+
## Руководства и новости
|
|
44
|
+
|
|
45
|
+
[](https://www.youtube.com/@green-api)
|
|
46
|
+
[](https://t.me/green_api)
|
|
47
|
+
[](https://whatsapp.com/channel/0029VaHUM5TBA1f7cG29nO1C)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
## Установка
|
|
51
|
+
|
|
52
|
+
**Убедитесь, что у вас установлен Python версии 3.8 или выше:**
|
|
53
|
+
|
|
54
|
+
```shell
|
|
55
|
+
python --version
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Установите библиотеку:**
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install maxbot-api-client-python
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Импорт:**
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from maxbot_api_client_python import API, Config
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Использование и примеры
|
|
71
|
+
|
|
72
|
+
**Параметры конфигурации:**
|
|
73
|
+
|
|
74
|
+
- `base_url` - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в [официальной документации](https://dev.max.ru/docs-api).
|
|
75
|
+
- `token` - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после [регистрации или создании бота](https://green-api.com/max-bot-api/docs/before-start/) на платформе [business.max.ru](https://business.max.ru/).
|
|
76
|
+
- `ratelimiter` - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
|
|
77
|
+
- `timeout` - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.
|
|
78
|
+
|
|
79
|
+
**Как инициализировать клиент:**
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
try:
|
|
83
|
+
bot = API(Config(
|
|
84
|
+
base_url="https://platform-bot.max.ru",
|
|
85
|
+
token="YOUR_BOT_TOKEN", # Замените на ваш токен
|
|
86
|
+
ratelimiter=25,
|
|
87
|
+
timeout=30
|
|
88
|
+
))
|
|
89
|
+
except ValueError as e:
|
|
90
|
+
print(f"Initialization error: {e}")
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**Как получить информацию о боте:**
|
|
94
|
+
|
|
95
|
+
* Ссылка на синхронный пример: [GetBot.py](./examples/sync/GetBot.py)
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
response = bot.bots.GetBot()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
* Ссылка на асинхронный пример: [GetBotAsync.py](./examples/async/GetBotAsync.py)
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
|
|
105
|
+
response = await bot.bots.GetBotAsync()
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**Как отправить сообщение:**
|
|
109
|
+
|
|
110
|
+
* Ссылка на синхронный пример: [SendMessage.py](./examples/sync/SendMessage.py)
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
response = bot.messages.SendMessage(SendMessageReq(
|
|
114
|
+
user_id=1234567890,
|
|
115
|
+
text="Hello world!"
|
|
116
|
+
))
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
* Ссылка на асинхронный пример: [SendMessage.py](./examples/async/SendMessageAsync.py)
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
response = await bot.messages.SendMessageAsync(SendMessageReq(
|
|
123
|
+
user_id=1234567890,
|
|
124
|
+
text="Hello world from Async!"
|
|
125
|
+
))
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Как легко отправить файл (по ссылке или локальный):**
|
|
129
|
+
|
|
130
|
+
* Ссылка на синхронный пример: [SendFile.py](./examples/sync/SendFile.py)
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
response = bot.helpers.SendFile(SendFileReq(
|
|
134
|
+
chat_id=1234567890,
|
|
135
|
+
text="Check this!",
|
|
136
|
+
file_source="https://example.com/image.png"
|
|
137
|
+
))
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
* Ссылка на асинхронный пример: [SendFileAsync.py](./examples/async/SendFileAsync.py)
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
response = await bot.helpers.SendFileAsync(SendFileReq(
|
|
144
|
+
chat_id=1234567890,
|
|
145
|
+
text="Посмотри на этот файл!",
|
|
146
|
+
file_source="https://example.com/image.png"
|
|
147
|
+
))
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**Как вручную загрузить файл (для кастомных вложений):**
|
|
151
|
+
|
|
152
|
+
* Ссылка на синхронный пример: [UploadFile.py](./examples/sync/UploadFile.py)
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
response = bot.uploads.UploadFile(UploadFileReq(
|
|
156
|
+
type=UploadType.IMAGE,
|
|
157
|
+
file_path="examples/assets/file.png"
|
|
158
|
+
))
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
* Ссылка на асинхронный пример: [UploadFileAsync.py](./examples/async/UploadFileAsync.py)
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
response = await bot.uploads.UploadFileAsync(UploadFileReq(
|
|
165
|
+
type=UploadType.IMAGE,
|
|
166
|
+
file_path="examples/assets/file.png"
|
|
167
|
+
))
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**Как получить входящее уведомление:**
|
|
171
|
+
|
|
172
|
+
* Ссылка на синхронный пример: [GetUpdates.py](./examples/sync/GetUpdates.py)
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
response = bot.subscriptions.GetUpdates(GetUpdatesReq(
|
|
176
|
+
marker=0,
|
|
177
|
+
timeout=30
|
|
178
|
+
))
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
* Ссылка на асинхронный пример: [GetUpdatesAsync.py](./examples/async/GetUpdatesAsync.py)
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
response = await bot.subscriptions.GetUpdatesAsync(GetUpdatesReq(
|
|
185
|
+
marker=0,
|
|
186
|
+
timeout=30
|
|
187
|
+
))
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
-----
|
|
191
|
+
|
|
192
|
+
## Список примеров
|
|
193
|
+
|
|
194
|
+
| Описание | Ссылка на пример |
|
|
195
|
+
| ---------------------------------------------- | ------------------------------------------------------------ |
|
|
196
|
+
| Как отправить сообщение | [SendMessage.py](./examples/sync/SendMessage.py) |
|
|
197
|
+
| Как отправить сообщение *асинхронно* | [SendMessageAsync.py](./examples/async/SendMessageAsync.py) |
|
|
198
|
+
| Как получить информацию о боте | [GetBot.py](./examples/sync/GetBot.py) |
|
|
199
|
+
| Как получить информацию о боте *асинхронно* | [GetBotAsync.py](./examples/async/GetBotAsync.py) |
|
|
200
|
+
| Как загрузить файл | [UploadFile.py](./examples/sync/UploadFile.py) |
|
|
201
|
+
| Как загрузить файл *асинхронно* | [UploadFileAsync.py](./examples/async/UploadFileAsync.py) |
|
|
202
|
+
| Как отправить файл | [SendFile.py](./examples/sync/SendFile.py) |
|
|
203
|
+
| Как отправить файл *асинхронно* | [SendFileAsync.py](./examples/async/SendFileAsync.py) |
|
|
204
|
+
| Как получить входящее уведомление | [GetUpdates.py](./examples/sync/GetUpdates.py) |
|
|
205
|
+
| Как получить входящее уведомление *асинхронно* | [GetUpdates.py](./examples/async/GetUpdatesAsync.py) |
|
|
206
|
+
|
|
207
|
+
## Список всех методов библиотеки
|
|
208
|
+
|
|
209
|
+
| Метод API | Описание | Ссылка на документацию MAX | Ссылка на документацию библиотеки |
|
|
210
|
+
|-----------------|-------------------------|------------------------------------------------|----------------------------------------------|
|
|
211
|
+
| `Bots.GetBot` | Получает информацию о боте | [GetBot](https://dev.max.ru/docs-api/methods/GET/me) | [GetBot](./docs/bots/GetBot.md) |
|
|
212
|
+
| `Bots.PatchBot` | Изменяет информацию о боте | | [PatchBot](./docs/bots/PatchBot.md) |
|
|
213
|
+
| `Chats.GetChats` | Возвращает список групповых чатов, в которых участвовал бот | [GetChats](https://dev.max.ru/docs-api/methods/GET/chats) | [GetChats](./docs/chats/GetChats.md) |
|
|
214
|
+
| `Chats.GetChat` | Возвращает информацию о групповом чате по его ID | [GetChat](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-) | [GetChat](./docs/chats/GetChat..md) |
|
|
215
|
+
| `Chats.EditChat` | Позволяет редактировать информацию о групповом чате | [EditChat](https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-) | [EditChat](./docs/chats/EditChat.md) |
|
|
216
|
+
| `Chats.DeleteChat` | Удаляет групповой чат для всех участников | [DeleteChat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-) | [DeleteChat](./docs/chats/DeleteChat.md) |
|
|
217
|
+
| `Chats.SendAction` | Позволяет отправлять следующие действия бота в групповой чат | [SendAction](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions) | [SendAction](./docs/chats/SendAction.md) |
|
|
218
|
+
| `Chats.GetPinnedMessage` | Возвращает закрепленное сообщение в чате | [GetPinnedMessage](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin) | [GetPinnedMessage](./docs/chats/GetPinnedMessage.md) |
|
|
219
|
+
| `Chats.PinMessage` | Закрепляет сообщение в групповом чате | [PinMessage](https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin) | [PinMessage](./docs/chats/PinMessage.md) |
|
|
220
|
+
| `Chats.UnpinMessage` | Удаляет закрепленное сообщение в групповом чате | [UnpinMessage](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin) | [UnpinMessage](./docs/chats/UnpinMessage.md) |
|
|
221
|
+
| `Chats.GetChatMembership` | Возвращает членство бота в групповом чате | [GetChatMembership](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me) | [GetChatMembership](./docs/chats/GetChatMembership.md) |
|
|
222
|
+
| `Chats.LeaveChat` | Удаляет бота из группового чата | [LeaveChat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me) | [LeaveChat](./docs/chats/LeaveChat.md) |
|
|
223
|
+
| `Chats.GetChatAdmins` | Возвращает список всех администраторов группового чата | [GetChatAdmins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins) | [GetChatAdmins](./docs/chats/GetChatAdmins.md) |
|
|
224
|
+
| `Chats.SetChatAdmins` | Назначает участника группы администратором | [SetChatAdmins](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins) | [SetChatAdmins](./docs/chats/SetChatAdmins.md) |
|
|
225
|
+
| `Chats.DeleteAdmin` | Отменяет права администратора пользователя в групповом чате | [DeleteAdmin](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-) | [DeleteAdmin](./docs/chats/DeleteAdmin.md) |
|
|
226
|
+
| `Chats.GetChatMembers` | Возвращает список участников группового чата | [GetChatMembers](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members) | [GetChatMembers](./docs/chats/GetChatMembers.md) |
|
|
227
|
+
| `Chats.AddMembers` | Добавляет участников в групповой чат | [AddMembers](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members) | [AddMembers](./docs/chats/AddMembers.md) |
|
|
228
|
+
| `Chats.DeleteMember` | Удаляет участника из группового чата | [DeleteMember](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members) | [DeleteMember](./docs/chats/DeleteMember.md) |
|
|
229
|
+
| `Subscriptions.GetSubscriptions` | Возвращает список подписок на уведомления веб-хуков | [GetSubscriptions](https://dev.max.ru/docs-api/methods/GET/subscriptions) | [GetSubscriptions](./docs/subscriptions/GetSubscriptions.md) |
|
|
230
|
+
| `Subscriptions.Subscribe` | Настраивает доставку событий бота через веб-хук | [Subscribe](https://dev.max.ru/docs-api/methods/POST/subscriptions) | [Subscribe](./docs/subscriptions/Subscribe.md) |
|
|
231
|
+
| `Subscriptions.Unsubscribe` | Отменяет подписку бота на получение обновлений через веб-хук | [Unsubscribe](https://dev.max.ru/docs-api/methods/DELETE/subscriptions) | [Unsubscribe](./docs/subscriptions/Unsubscribe.md)|
|
|
232
|
+
| `Subscriptions.GetUpdates` | Получает входящие обновления | [GetUpdates](https://dev.max.ru/docs-api/methods/GET/updates) | [GetUpdates](./docs/subscriptions/GetUpdates.md) |
|
|
233
|
+
| `Upload.UploadFile` | Загружает файл на серверы MAX для последующей передачи | [UploadFile](https://dev.max.ru/docs-api/methods/POST/uploads) | [UploadFile](./docs/upload/UploadFile.md) |
|
|
234
|
+
| `Helpers.SendFile` | Упрощает отправку файлов, автоматически определяя URL или путь | | [SendFile](./docs/helpers/SendFile.md) |
|
|
235
|
+
| `Messages.GetMessages` | Возвращает информацию о сообщении или массив сообщений из чата | [GetMessages](https://dev.max.ru/docs-api/methods/GET/messages) | [GetMessages](./docs/messages/GetMessages.md) |
|
|
236
|
+
| `Messages.SendMessage` | Отправляет текстовое или медиа-сообщение указанному пользователю или в чат | [SendMessage](https://dev.max.ru/docs-api/methods/POST/messages) | [SendMessage](./docs/messages/SendMessage.md) |
|
|
237
|
+
| `Messages.EditMessage` | Редактирует текст или медиафайл ранее отправленного сообщения | [EditMessage](https://dev.max.ru/docs-api/methods/PUT/messages) | [EditMessage](./docs/messages/EditMessage.md) |
|
|
238
|
+
| `Messages.DeleteMessage` | Удаляет сообщение из чата | [DeleteMessage](https://dev.max.ru/docs-api/methods/DELETE/messages) | [DeleteMessage](./docs/messages/DeleteMessage.md) |
|
|
239
|
+
| `Messages.GetMessage` | Извлекает содержимое и метаданные конкретного сообщения по его ID | [GetMessage](https://dev.max.ru/docs-api/methods/GET/messages/-messageId-) | [GetMessage](./docs/messages/GetMessage.md) |
|
|
240
|
+
| `Messages.GetVideoInfo` | Возвращает подробную информацию о прикрепленном видео | [GetVideoInfo](https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-) | [GetVideoInfo](./docs/messages/GetVideoInfo.md) |
|
|
241
|
+
| `Messages.AnswerCallback` | Отправляет ответ после того, как пользователь нажмет кнопку | [AnswerCallback](https://dev.max.ru/docs-api/methods/POST/answers) | [AnswerCallback](./docs/messages/AnswerCallback.md)|
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# MAX BOT API Client (Python)
|
|
2
|
+
|
|
3
|
+
`maxbot-api-client-python` — это библиотека для интеграции с MAX BOT API. Этот проект предоставляет структурированный интерфейс для взаимодействия с конфигурациями бота, управления сообщениями, отправки медиафайлов и подписки на события через long-polling.
|
|
4
|
+
|
|
5
|
+
Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
|
|
6
|
+
|
|
7
|
+
## API
|
|
8
|
+
|
|
9
|
+
Документацию по REST API MAX можно найти по ссылке https://dev.max.ru/docs-api. Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям и параметрам запроса.
|
|
10
|
+
|
|
11
|
+
## Поддержка
|
|
12
|
+
|
|
13
|
+
[](mailto:support@green-bot.com)
|
|
14
|
+
[](https://t.me/greenapi_support_ru_bot)
|
|
15
|
+
[](https://wa.me/77780739095)
|
|
16
|
+
|
|
17
|
+
## Руководства и новости
|
|
18
|
+
|
|
19
|
+
[](https://www.youtube.com/@green-api)
|
|
20
|
+
[](https://t.me/green_api)
|
|
21
|
+
[](https://whatsapp.com/channel/0029VaHUM5TBA1f7cG29nO1C)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
## Установка
|
|
25
|
+
|
|
26
|
+
**Убедитесь, что у вас установлен Python версии 3.8 или выше:**
|
|
27
|
+
|
|
28
|
+
```shell
|
|
29
|
+
python --version
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Установите библиотеку:**
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install maxbot-api-client-python
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Импорт:**
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from maxbot_api_client_python import API, Config
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Использование и примеры
|
|
45
|
+
|
|
46
|
+
**Параметры конфигурации:**
|
|
47
|
+
|
|
48
|
+
- `base_url` - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в [официальной документации](https://dev.max.ru/docs-api).
|
|
49
|
+
- `token` - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после [регистрации или создании бота](https://green-api.com/max-bot-api/docs/before-start/) на платформе [business.max.ru](https://business.max.ru/).
|
|
50
|
+
- `ratelimiter` - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
|
|
51
|
+
- `timeout` - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.
|
|
52
|
+
|
|
53
|
+
**Как инициализировать клиент:**
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
try:
|
|
57
|
+
bot = API(Config(
|
|
58
|
+
base_url="https://platform-bot.max.ru",
|
|
59
|
+
token="YOUR_BOT_TOKEN", # Замените на ваш токен
|
|
60
|
+
ratelimiter=25,
|
|
61
|
+
timeout=30
|
|
62
|
+
))
|
|
63
|
+
except ValueError as e:
|
|
64
|
+
print(f"Initialization error: {e}")
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Как получить информацию о боте:**
|
|
68
|
+
|
|
69
|
+
* Ссылка на синхронный пример: [GetBot.py](./examples/sync/GetBot.py)
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
response = bot.bots.GetBot()
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
* Ссылка на асинхронный пример: [GetBotAsync.py](./examples/async/GetBotAsync.py)
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
|
|
79
|
+
response = await bot.bots.GetBotAsync()
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Как отправить сообщение:**
|
|
83
|
+
|
|
84
|
+
* Ссылка на синхронный пример: [SendMessage.py](./examples/sync/SendMessage.py)
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
response = bot.messages.SendMessage(SendMessageReq(
|
|
88
|
+
user_id=1234567890,
|
|
89
|
+
text="Hello world!"
|
|
90
|
+
))
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
* Ссылка на асинхронный пример: [SendMessage.py](./examples/async/SendMessageAsync.py)
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
response = await bot.messages.SendMessageAsync(SendMessageReq(
|
|
97
|
+
user_id=1234567890,
|
|
98
|
+
text="Hello world from Async!"
|
|
99
|
+
))
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Как легко отправить файл (по ссылке или локальный):**
|
|
103
|
+
|
|
104
|
+
* Ссылка на синхронный пример: [SendFile.py](./examples/sync/SendFile.py)
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
response = bot.helpers.SendFile(SendFileReq(
|
|
108
|
+
chat_id=1234567890,
|
|
109
|
+
text="Check this!",
|
|
110
|
+
file_source="https://example.com/image.png"
|
|
111
|
+
))
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
* Ссылка на асинхронный пример: [SendFileAsync.py](./examples/async/SendFileAsync.py)
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
response = await bot.helpers.SendFileAsync(SendFileReq(
|
|
118
|
+
chat_id=1234567890,
|
|
119
|
+
text="Посмотри на этот файл!",
|
|
120
|
+
file_source="https://example.com/image.png"
|
|
121
|
+
))
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Как вручную загрузить файл (для кастомных вложений):**
|
|
125
|
+
|
|
126
|
+
* Ссылка на синхронный пример: [UploadFile.py](./examples/sync/UploadFile.py)
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
response = bot.uploads.UploadFile(UploadFileReq(
|
|
130
|
+
type=UploadType.IMAGE,
|
|
131
|
+
file_path="examples/assets/file.png"
|
|
132
|
+
))
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
* Ссылка на асинхронный пример: [UploadFileAsync.py](./examples/async/UploadFileAsync.py)
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
response = await bot.uploads.UploadFileAsync(UploadFileReq(
|
|
139
|
+
type=UploadType.IMAGE,
|
|
140
|
+
file_path="examples/assets/file.png"
|
|
141
|
+
))
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**Как получить входящее уведомление:**
|
|
145
|
+
|
|
146
|
+
* Ссылка на синхронный пример: [GetUpdates.py](./examples/sync/GetUpdates.py)
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
response = bot.subscriptions.GetUpdates(GetUpdatesReq(
|
|
150
|
+
marker=0,
|
|
151
|
+
timeout=30
|
|
152
|
+
))
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
* Ссылка на асинхронный пример: [GetUpdatesAsync.py](./examples/async/GetUpdatesAsync.py)
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
response = await bot.subscriptions.GetUpdatesAsync(GetUpdatesReq(
|
|
159
|
+
marker=0,
|
|
160
|
+
timeout=30
|
|
161
|
+
))
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
-----
|
|
165
|
+
|
|
166
|
+
## Список примеров
|
|
167
|
+
|
|
168
|
+
| Описание | Ссылка на пример |
|
|
169
|
+
| ---------------------------------------------- | ------------------------------------------------------------ |
|
|
170
|
+
| Как отправить сообщение | [SendMessage.py](./examples/sync/SendMessage.py) |
|
|
171
|
+
| Как отправить сообщение *асинхронно* | [SendMessageAsync.py](./examples/async/SendMessageAsync.py) |
|
|
172
|
+
| Как получить информацию о боте | [GetBot.py](./examples/sync/GetBot.py) |
|
|
173
|
+
| Как получить информацию о боте *асинхронно* | [GetBotAsync.py](./examples/async/GetBotAsync.py) |
|
|
174
|
+
| Как загрузить файл | [UploadFile.py](./examples/sync/UploadFile.py) |
|
|
175
|
+
| Как загрузить файл *асинхронно* | [UploadFileAsync.py](./examples/async/UploadFileAsync.py) |
|
|
176
|
+
| Как отправить файл | [SendFile.py](./examples/sync/SendFile.py) |
|
|
177
|
+
| Как отправить файл *асинхронно* | [SendFileAsync.py](./examples/async/SendFileAsync.py) |
|
|
178
|
+
| Как получить входящее уведомление | [GetUpdates.py](./examples/sync/GetUpdates.py) |
|
|
179
|
+
| Как получить входящее уведомление *асинхронно* | [GetUpdates.py](./examples/async/GetUpdatesAsync.py) |
|
|
180
|
+
|
|
181
|
+
## Список всех методов библиотеки
|
|
182
|
+
|
|
183
|
+
| Метод API | Описание | Ссылка на документацию MAX | Ссылка на документацию библиотеки |
|
|
184
|
+
|-----------------|-------------------------|------------------------------------------------|----------------------------------------------|
|
|
185
|
+
| `Bots.GetBot` | Получает информацию о боте | [GetBot](https://dev.max.ru/docs-api/methods/GET/me) | [GetBot](./docs/bots/GetBot.md) |
|
|
186
|
+
| `Bots.PatchBot` | Изменяет информацию о боте | | [PatchBot](./docs/bots/PatchBot.md) |
|
|
187
|
+
| `Chats.GetChats` | Возвращает список групповых чатов, в которых участвовал бот | [GetChats](https://dev.max.ru/docs-api/methods/GET/chats) | [GetChats](./docs/chats/GetChats.md) |
|
|
188
|
+
| `Chats.GetChat` | Возвращает информацию о групповом чате по его ID | [GetChat](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-) | [GetChat](./docs/chats/GetChat..md) |
|
|
189
|
+
| `Chats.EditChat` | Позволяет редактировать информацию о групповом чате | [EditChat](https://dev.max.ru/docs-api/methods/PATCH/chats/-chatId-) | [EditChat](./docs/chats/EditChat.md) |
|
|
190
|
+
| `Chats.DeleteChat` | Удаляет групповой чат для всех участников | [DeleteChat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-) | [DeleteChat](./docs/chats/DeleteChat.md) |
|
|
191
|
+
| `Chats.SendAction` | Позволяет отправлять следующие действия бота в групповой чат | [SendAction](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/actions) | [SendAction](./docs/chats/SendAction.md) |
|
|
192
|
+
| `Chats.GetPinnedMessage` | Возвращает закрепленное сообщение в чате | [GetPinnedMessage](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/pin) | [GetPinnedMessage](./docs/chats/GetPinnedMessage.md) |
|
|
193
|
+
| `Chats.PinMessage` | Закрепляет сообщение в групповом чате | [PinMessage](https://dev.max.ru/docs-api/methods/PUT/chats/-chatId-/pin) | [PinMessage](./docs/chats/PinMessage.md) |
|
|
194
|
+
| `Chats.UnpinMessage` | Удаляет закрепленное сообщение в групповом чате | [UnpinMessage](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/pin) | [UnpinMessage](./docs/chats/UnpinMessage.md) |
|
|
195
|
+
| `Chats.GetChatMembership` | Возвращает членство бота в групповом чате | [GetChatMembership](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/me) | [GetChatMembership](./docs/chats/GetChatMembership.md) |
|
|
196
|
+
| `Chats.LeaveChat` | Удаляет бота из группового чата | [LeaveChat](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/me) | [LeaveChat](./docs/chats/LeaveChat.md) |
|
|
197
|
+
| `Chats.GetChatAdmins` | Возвращает список всех администраторов группового чата | [GetChatAdmins](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members/admins) | [GetChatAdmins](./docs/chats/GetChatAdmins.md) |
|
|
198
|
+
| `Chats.SetChatAdmins` | Назначает участника группы администратором | [SetChatAdmins](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins) | [SetChatAdmins](./docs/chats/SetChatAdmins.md) |
|
|
199
|
+
| `Chats.DeleteAdmin` | Отменяет права администратора пользователя в групповом чате | [DeleteAdmin](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members/admins/-userId-) | [DeleteAdmin](./docs/chats/DeleteAdmin.md) |
|
|
200
|
+
| `Chats.GetChatMembers` | Возвращает список участников группового чата | [GetChatMembers](https://dev.max.ru/docs-api/methods/GET/chats/-chatId-/members) | [GetChatMembers](./docs/chats/GetChatMembers.md) |
|
|
201
|
+
| `Chats.AddMembers` | Добавляет участников в групповой чат | [AddMembers](https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members) | [AddMembers](./docs/chats/AddMembers.md) |
|
|
202
|
+
| `Chats.DeleteMember` | Удаляет участника из группового чата | [DeleteMember](https://dev.max.ru/docs-api/methods/DELETE/chats/-chatId-/members) | [DeleteMember](./docs/chats/DeleteMember.md) |
|
|
203
|
+
| `Subscriptions.GetSubscriptions` | Возвращает список подписок на уведомления веб-хуков | [GetSubscriptions](https://dev.max.ru/docs-api/methods/GET/subscriptions) | [GetSubscriptions](./docs/subscriptions/GetSubscriptions.md) |
|
|
204
|
+
| `Subscriptions.Subscribe` | Настраивает доставку событий бота через веб-хук | [Subscribe](https://dev.max.ru/docs-api/methods/POST/subscriptions) | [Subscribe](./docs/subscriptions/Subscribe.md) |
|
|
205
|
+
| `Subscriptions.Unsubscribe` | Отменяет подписку бота на получение обновлений через веб-хук | [Unsubscribe](https://dev.max.ru/docs-api/methods/DELETE/subscriptions) | [Unsubscribe](./docs/subscriptions/Unsubscribe.md)|
|
|
206
|
+
| `Subscriptions.GetUpdates` | Получает входящие обновления | [GetUpdates](https://dev.max.ru/docs-api/methods/GET/updates) | [GetUpdates](./docs/subscriptions/GetUpdates.md) |
|
|
207
|
+
| `Upload.UploadFile` | Загружает файл на серверы MAX для последующей передачи | [UploadFile](https://dev.max.ru/docs-api/methods/POST/uploads) | [UploadFile](./docs/upload/UploadFile.md) |
|
|
208
|
+
| `Helpers.SendFile` | Упрощает отправку файлов, автоматически определяя URL или путь | | [SendFile](./docs/helpers/SendFile.md) |
|
|
209
|
+
| `Messages.GetMessages` | Возвращает информацию о сообщении или массив сообщений из чата | [GetMessages](https://dev.max.ru/docs-api/methods/GET/messages) | [GetMessages](./docs/messages/GetMessages.md) |
|
|
210
|
+
| `Messages.SendMessage` | Отправляет текстовое или медиа-сообщение указанному пользователю или в чат | [SendMessage](https://dev.max.ru/docs-api/methods/POST/messages) | [SendMessage](./docs/messages/SendMessage.md) |
|
|
211
|
+
| `Messages.EditMessage` | Редактирует текст или медиафайл ранее отправленного сообщения | [EditMessage](https://dev.max.ru/docs-api/methods/PUT/messages) | [EditMessage](./docs/messages/EditMessage.md) |
|
|
212
|
+
| `Messages.DeleteMessage` | Удаляет сообщение из чата | [DeleteMessage](https://dev.max.ru/docs-api/methods/DELETE/messages) | [DeleteMessage](./docs/messages/DeleteMessage.md) |
|
|
213
|
+
| `Messages.GetMessage` | Извлекает содержимое и метаданные конкретного сообщения по его ID | [GetMessage](https://dev.max.ru/docs-api/methods/GET/messages/-messageId-) | [GetMessage](./docs/messages/GetMessage.md) |
|
|
214
|
+
| `Messages.GetVideoInfo` | Возвращает подробную информацию о прикрепленном видео | [GetVideoInfo](https://dev.max.ru/docs-api/methods/GET/videos/-videoToken-) | [GetVideoInfo](./docs/messages/GetVideoInfo.md) |
|
|
215
|
+
| `Messages.AnswerCallback` | Отправляет ответ после того, как пользователь нажмет кнопку | [AnswerCallback](https://dev.max.ru/docs-api/methods/POST/answers) | [AnswerCallback](./docs/messages/AnswerCallback.md)|
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
from maxbot_api_client_python.api import API
|
|
2
|
+
from maxbot_api_client_python.client import Config, Client
|
|
3
|
+
from maxbot_api_client_python.types import models
|
|
4
|
+
from maxbot_api_client_python.types import constants
|
|
5
|
+
from maxbot_api_client_python import utils
|
|
6
|
+
|
|
7
|
+
__all__ = ["API", "Config", "Client", "models", "constants", "utils"]
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
from typing import Any, Self
|
|
2
|
+
|
|
3
|
+
from maxbot_api_client_python.client import Client, Config
|
|
4
|
+
from maxbot_api_client_python import tools
|
|
5
|
+
|
|
6
|
+
class API:
|
|
7
|
+
def __init__(self, cfg: Config) -> None:
|
|
8
|
+
self.client = Client(cfg)
|
|
9
|
+
|
|
10
|
+
self.bots = tools.Bots(self.client)
|
|
11
|
+
self.chats = tools.Chats(self.client)
|
|
12
|
+
self.helpers = tools.Helpers(self.client)
|
|
13
|
+
self.messages = tools.Messages(self.client)
|
|
14
|
+
self.subscriptions = tools.Subscriptions(self.client)
|
|
15
|
+
self.uploads = tools.Uploads(self.client)
|
|
16
|
+
|
|
17
|
+
def __enter__(self) -> Self:
|
|
18
|
+
self.client.__enter__()
|
|
19
|
+
return self
|
|
20
|
+
|
|
21
|
+
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
|
|
22
|
+
self.client.__exit__(exc_type, exc_val, exc_tb)
|
|
23
|
+
|
|
24
|
+
async def __aenter__(self) -> Self:
|
|
25
|
+
await self.client.__aenter__()
|
|
26
|
+
return self
|
|
27
|
+
|
|
28
|
+
async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
|
|
29
|
+
await self.client.__aexit__(exc_type, exc_val, exc_tb)
|
|
30
|
+
|
|
31
|
+
def close(self) -> None:
|
|
32
|
+
self.client.close()
|
|
33
|
+
|
|
34
|
+
async def aclose(self) -> None:
|
|
35
|
+
await self.client.aclose()
|