Python ΡΠ°Ρ-Π±ΠΎΡ Π΄Π»Ρ ΠΎΡΠΈΡΠΈΠ°Π»ΡΠ½ΠΎΠ³ΠΎ API MAX#
maxbot-chatbot-python β ΡΡΠΎ Π°ΡΠΈΠ½Ρ ΡΠΎΠ½Π½ΡΠΉ ΡΡΠ΅ΠΉΠΌΠ²ΠΎΡΠΊ Π΄Π»Ρ ΡΠΎΠ·Π΄Π°Π½ΠΈΡ ΠΌΠ°ΡΡΡΠ°Π±ΠΈΡΡΠ΅ΠΌΡΡ Π±ΠΎΡΠΎΠ² Π΄Π»Ρ MAX BOT API Π½Π° ΡΠ·ΡΠΊΠ΅ Python.
ΠΠΎΡΡΡΠΎΠ΅Π½Π½Π°Ρ Π½Π° ΠΎΡΠ½ΠΎΠ²Π΅ maxbot_api_client_python, ΡΡΠ° Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΠ° ΠΏΡΠ΅Π΄ΠΎΡΡΠ°Π²Π»ΡΠ΅Ρ ΡΠΈΡΡΡΠΉ ΠΌΠ°ΡΡΡΡΡΠΈΠ·Π°ΡΠΎΡ, Π°Π²ΡΠΎΠΌΠ°ΡΠΈΡΠ΅ΡΠΊΠΎΠ΅ ΠΏΠΎΠ»ΡΡΠ΅Π½ΠΈΠ΅ ΠΎΠ±Π½ΠΎΠ²Π»Π΅Π½ΠΈΠΉ (Long Polling) ΠΈ Π½Π°Π΄Π΅ΠΆΠ½ΡΠΉ ΠΌΠ΅Π½Π΅Π΄ΠΆΠ΅Ρ ΡΠΎΡΡΠΎΡΠ½ΠΈΠΉ (FSM) Π΄Π»Ρ ΠΏΠΎΡΡΡΠΎΠ΅Π½ΠΈΡ ΠΌΠ½ΠΎΠ³ΠΎΡΠ°Π³ΠΎΠ²ΡΡ Π΄ΠΈΠ°Π»ΠΎΠ³ΠΎΠ²ΡΡ ΡΡΠ΅Π½Π°ΡΠΈΠ΅Π².
API#
ΠΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΠΈΡ ΠΊ REST API MAX Π½Π°Ρ ΠΎΠ΄ΠΈΡΡΡ ΠΏΠΎ ΡΡΡΠ»ΠΊΠ΅. ΠΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΠ° ΡΠ²Π»ΡΠ΅ΡΡΡ ΠΎΠ±ΡΡΡΠΊΠΎΠΉ ΠΊ REST API, ΠΏΠΎΡΡΠΎΠΌΡ Π΄ΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΠΈΡ ΠΏΠΎ ΡΡΡΠ»ΠΊΠ΅ Π²ΡΡΠ΅ ΠΏΡΠΈΠΌΠ΅Π½ΠΈΠΌΠ° ΠΈ ΠΊ ΡΠ°ΠΌΠΎΠΉ Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΠ΅.
ΠΠ²ΡΠΎΡΠΈΠ·Π°ΡΠΈΡ#
ΠΠ»Ρ ΠΈΡΠΏΠΎΠ»ΡΠ·ΠΎΠ²Π°Π½ΠΈΡ Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΠΈ ΠΏΠΎΡΡΠ΅Π±ΡΠ΅ΡΡΡ ΠΏΠΎΠ»ΡΡΠΈΡΡ ΡΠΎΠΊΠ΅Π½ Π±ΠΎΡΠ° Π² ΠΊΠΎΠ½ΡΠΎΠ»ΠΈ ΡΠ°Π·ΡΠ°Π±ΠΎΡΡΠΈΠΊΠ° MAX API.
Π‘ΠΎΠ΄Π΅ΡΠΆΠ°Π½ΠΈΠ΅#
ΠΠ°ΠΊ ΠΈΠΌΠΏΠΎΡΡΠΈΡΠΎΠ²Π°ΡΡ Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΡ ΠΈ ΠΈΠ½ΠΈΡΠΈΠΈΡΠΎΠ²Π°ΡΡ ΡΠ²ΠΎΠ΅Π³ΠΎ Π±ΠΎΡΠ°#
ΠΠ°ΡΡΡΡΡΠΈΠ·Π°ΡΠΈΡ ΠΊΠΎΠΌΠ°Π½Π΄ ΠΈ ΡΠΎΠΎΠ±ΡΠ΅Π½ΠΈΠΉ#
Π£ΠΏΡΠ°Π²Π»Π΅Π½ΠΈΠ΅ ΡΠΎΡΡΠΎΡΠ½ΠΈΡΠΌΠΈ ΠΈ ΡΡΠ΅Π½Ρ#
ΠΡΠ²Π΅Ρ Ρ ΠΌΠ΅Π΄ΠΈΠ°ΡΠ°ΠΉΠ»Π°ΠΌΠΈ#
ΠΡΠΈΠΌΠ΅Ρ ΡΡ ΠΎ-Π±ΠΎΡΠ°#
ΠΠΈΡΠ΅Π½Π·ΠΈΡ#
ΠΠ°ΠΊ ΠΈΠΌΠΏΠΎΡΡΠΈΡΠΎΠ²Π°ΡΡ Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΡ ΠΈ ΠΈΠ½ΠΈΡΠΈΠΈΡΠΎΠ²Π°ΡΡ ΡΠ²ΠΎΠ΅Π³ΠΎ Π±ΠΎΡΠ°#
Π£Π±Π΅Π΄ΠΈΡΠ΅ΡΡ, ΡΡΠΎ Ρ Π²Π°Ρ ΡΡΡΠ°Π½ΠΎΠ²Π»Π΅Π½Π° Π²Π΅ΡΡΠΈΡ Python Π½Π΅ Π½ΠΈΠΆΠ΅ 3.12:
python --version
Π£ΡΡΠ°Π½ΠΎΠ²ΠΊΠ° Π±ΠΈΠ±Π»ΠΈΠΎΡΠ΅ΠΊΠΈ:
pip install maxbot-chatbot-python
ΠΠ°ΠΊ ΠΈΠ½ΠΈΡΠΈΠ°Π»ΠΈΠ·ΠΈΡΠΎΠ²Π°ΡΡ ΠΎΠ±ΡΠ΅ΠΊΡ#
ΠΠ»Ρ ΠΈΠ½ΠΈΡΠΈΠ°Π»ΠΈΠ·Π°ΡΠΈΠΈ Π±ΠΎΡΠ° Π½ΡΠΆΠ½ΠΎ ΠΏΠ΅ΡΠ΅Π΄Π°ΡΡ Π² ΡΡΠ½ΠΊΡΠΈΡ main Π°Π΄ΡΠ΅Ρ ΠΏΠ»Π°ΡΡΠΎΡΠΌΡ MaxBot, MAX token, Π° ΡΠ°ΠΊ ΠΆΠ΅ Π·Π°Π΄Π°ΡΡ Π·Π½Π°ΡΠ΅Π½ΠΈΡ Π΄Π»Ρ RateLimiter ΠΈ Timeout.
ΠΠ°ΡΠ°ΠΌΠ΅ΡΡΡ ΠΊΠΎΠ½ΡΠΈΠ³ΡΡΠ°ΡΠΈΠΈ:
BaseURL- ΠΠ°Π·ΠΎΠ²ΡΠΉ URL-Π°Π΄ΡΠ΅Ρ ΡΠ΅ΡΠ²Π΅ΡΠΎΠ² ΠΏΠ»Π°ΡΡΠΎΡΠΌΡ MaxBot. ΠΡΠ΅ ΠΌΠ΅ΡΠΎΠ΄Ρ API Π±ΡΠ΄ΡΡ ΠΌΠ°ΡΡΡΡΡΠΈΠ·ΠΈΡΠΎΠ²Π°ΡΡΡΡ ΠΏΠΎ ΡΡΠΎΠΌΡ ΠΊΠΎΡΠ½Π΅Π²ΠΎΠΌΡ Π°Π΄ΡΠ΅ΡΡ. ΠΠΊΡΡΠ°Π»ΡΠ½ΡΠΉ Π°Π΄ΡΠ΅Ρ ΡΠΊΠ°Π·Π°Π½ Π² ΠΎΡΠΈΡΠΈΠ°Π»ΡΠ½ΠΎΠΉ Π΄ΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΠΈΠΈ.Token- Π£Π½ΠΈΠΊΠ°Π»ΡΠ½ΡΠΉ ΡΠ΅ΠΊΡΠ΅ΡΠ½ΡΠΉ ΠΊΠ»ΡΡ Π°Π²ΡΠΎΡΠΈΠ·Π°ΡΠΈΠΈ (API-ΠΊΠ»ΡΡ) Π²Π°ΡΠ΅Π³ΠΎ Π±ΠΎΡΠ°. ΠΠΎΠ»ΡΡΠΈΡΡ Π΅Π³ΠΎ ΠΌΠΎΠΆΠ½ΠΎ Π² Π»ΠΈΡΠ½ΠΎΠΌ ΠΊΠ°Π±ΠΈΠ½Π΅ΡΠ΅ ΠΏΠΎΡΠ»Π΅ ΡΠ΅Π³ΠΈΡΡΡΠ°ΡΠΈΠΈ ΠΈΠ»ΠΈ ΡΠΎΠ·Π΄Π°Π½ΠΈΠΈ Π±ΠΎΡΠ° Π½Π° ΠΏΠ»Π°ΡΡΠΎΡΠΌΠ΅ business.max.ru. Π§ΠΈΡΠ°ΠΉΡΠ΅ ΠΏΠ΅ΡΠ΅Π΄ Π½Π°ΡΠ°Π»ΠΎΠΌ ΡΠ°Π±ΠΎΡΡ, ΡΡΠΎΠ±Ρ ΠΏΠΎΠ»ΡΡΠΈΡΡ ΡΠΎΠΊΠ΅Π½.RateLimiter- ΠΡΡΡΠΎΠ΅Π½Π½ΡΠΉ ΠΎΠ³ΡΠ°Π½ΠΈΡΠΈΡΠ΅Π»Ρ ΡΠ°ΡΡΠΎΡΡ Π·Π°ΠΏΡΠΎΡΠΎΠ². ΠΠ½ ΠΊΠΎΠ½ΡΡΠΎΠ»ΠΈΡΡΠ΅Ρ ΠΊΠΎΠ»ΠΈΡΠ΅ΡΡΠ²ΠΎ ΠΈΡΡ ΠΎΠ΄ΡΡΠΈΡ Π·Π°ΠΏΡΠΎΡΠΎΠ² Π² ΡΠ΅ΠΊΡΠ½Π΄Ρ (RPS), Π·Π°ΡΠΈΡΠ°Ρ Π±ΠΎΡΠ° ΠΎΡ Π±Π»ΠΎΠΊΠΈΡΠΎΠ²ΠΊΠΈ ΡΠΎ ΡΡΠΎΡΠΎΠ½Ρ ΡΠ΅ΡΠ²Π΅ΡΠ° Π·Π° ΠΏΡΠ΅Π²ΡΡΠ΅Π½ΠΈΠ΅ Π»ΠΈΠΌΠΈΡΠΎΠ². Π Π΅ΠΊΠΎΠΌΠ΅Π½Π΄ΡΠ΅ΠΌΠΎΠ΅ Π·Π½Π°ΡΠ΅Π½ΠΈΠ΅ β Π½Π΅ ΠΌΠ΅Π½Π΅Π΅ 25, Π½ΠΎ Π½Π΅ Π±ΠΎΠ»Π΅Π΅ 30.Timeout- ΠΠ°ΠΊΡΠΈΠΌΠ°Π»ΡΠ½ΠΎΠ΅ Π²ΡΠ΅ΠΌΡ ΠΎΠΆΠΈΠ΄Π°Π½ΠΈΡ ΠΎΡΠ²Π΅ΡΠ° ΠΎΡ ΡΠ΅ΡΠ²Π΅ΡΠ° (Π² ΡΠ΅ΠΊΡΠ½Π΄Π°Ρ ). ΠΡΠ»ΠΈ ΡΠ΅ΡΠ²Π΅Ρ Π½Π΅ ΠΎΡΠ²Π΅ΡΠΈΡ Π² ΡΠ΅ΡΠ΅Π½ΠΈΠ΅ ΡΡΠΎΠ³ΠΎ Π²ΡΠ΅ΠΌΠ΅Π½ΠΈ, Π·Π°ΠΏΡΠΎΡ Π±ΡΠ΄Π΅Ρ Π·Π°Π²Π΅ΡΡΠ΅Π½ Ρ ΠΎΡΠΈΠ±ΠΊΠΎΠΉ. ΠΠΏΡΠΈΠΌΠ°Π»ΡΠ½ΠΎΠ΅ Π·Π½Π°ΡΠ΅Π½ΠΈΠ΅ β 30 ΡΠ΅ΠΊΡΠ½Π΄.
async def main():
cfg = Config(
base_url="https://platform-api.max.ru/",
token="YOUR_BOT_TOKEN",
ratelimiter=25,
timeout=35
)
ΠΡΠΈΠΌΠ΅Ρ ΠΈΠ½ΠΈΡΠΈΠ°Π»ΠΈΠ·Π°ΡΠΈΠΈ Π±ΠΎΡΠ°#
import asyncio
from maxbot_api_client_python import API, Config
from maxbot_chatbot_python import Bot, MapStateManager
async def main():
cfg = Config(
base_url="https://platform-api.max.ru/",
token="YOUR_BOT_TOKEN",
ratelimiter=25,
timeout=35
)
async with API(cfg) as api_client:
bot = Bot(api_client)
bot.state_manager = MapStateManager(init_data={})
polling_task = asyncio.create_task(bot.start_polling())
try:
await polling_task
except asyncio.CancelledError:
pass
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Bot stopped by user")
ΠΠ°ΡΡΡΡΡΠΈΠ·Π°ΡΠΈΡ ΠΊΠΎΠΌΠ°Π½Π΄ ΠΈ ΡΠΎΠΎΠ±ΡΠ΅Π½ΠΈΠΉ#
ΠΡΡΡΠΎΠ΅Π½Π½ΡΠΉ ΠΌΠ°ΡΡΡΡΡΠΈΠ·Π°ΡΠΎΡ (Router) ΠΏΠΎΠ·Π²ΠΎΠ»ΡΠ΅Ρ Π»Π΅Π³ΠΊΠΎ ΠΎΠ±ΡΠ°Π±Π°ΡΡΠ²Π°ΡΡ ΠΊΠΎΠ½ΠΊΡΠ΅ΡΠ½ΡΠ΅ ΠΊΠΎΠΌΠ°Π½Π΄Ρ (Π½Π°ΡΠΈΠ½Π°ΡΡΠΈΠ΅ΡΡ ΡΠΎ ΡΠ»ΡΡΠ° /) ΠΈ Π½Π°ΠΆΠ°ΡΠΈΡ Π½Π° inline-ΠΊΠ½ΠΎΠΏΠΊΠΈ (ΠΊΠΎΠ»Π»Π±ΡΠΊΠΈ).
@bot.router.command("/start")
async def start_command(notification):
await notification.reply("Hello! Welcome to the MAX Bot.")
@bot.router.register("message_created")
async def ping_handler(notification):
try:
if notification.text() == "ping":
await notification.reply("pong")
except ValueError:
pass
@bot.router.callback("accept_rules")
async def rules_callback(notification):
await notification.reply("*Thank you for accepting the rules!*", format_type="markdown")
await notification.answer_callback("Success!")
Π£ΠΏΡΠ°Π²Π»Π΅Π½ΠΈΠ΅ ΡΠΎΡΡΠΎΡΠ½ΠΈΡΠΌΠΈ ΠΈ ΡΡΠ΅Π½Ρ#
ΠΠ»Ρ ΡΠ»ΠΎΠΆΠ½ΡΡ ΠΌΠ½ΠΎΠ³ΠΎΡΠ°Π³ΠΎΠ²ΡΡ Π΄ΠΈΠ°Π»ΠΎΠ³ΠΎΠ² (Π½Π°ΠΏΡΠΈΠΌΠ΅Ρ, ΡΠ΅Π³ΠΈΡΡΡΠ°ΡΠΈΡ ΠΈΠ»ΠΈ Π°Π½ΠΊΠ΅ΡΠΈΡΠΎΠ²Π°Π½ΠΈΠ΅) ΠΈΡΠΏΠΎΠ»ΡΠ·ΡΠΉΡΠ΅ ΠΠ΅Π½Π΅Π΄ΠΆΠ΅Ρ ΡΠΎΡΡΠΎΡΠ½ΠΈΠΉ (StateManager) ΠΈ Π‘ΡΠ΅Π½Ρ (Scene).
from maxbot_chatbot_python import Scene
class RegistrationScene(Scene):
async def start(self, notification):
try:
text = notification.text()
except ValueError:
return
if text == "/start":
await notification.reply("Let's register! What is your *login*?", "markdown")
return
if len(text) >= 4:
if notification.state_manager:
notification.state_manager.update_state_data(notification.state_id, {"login": text})
await notification.reply(f"**Login** `{text}` accepted. Now enter your **password**:", "markdown")
notification.activate_next_scene(PasswordScene())
else:
await notification.reply("Login must be **at least 4 characters long**.", "markdown")
class PasswordScene(Scene):
async def start(self, notification):
try:
password = notification.text()
except ValueError:
return
state_data = notification.state_manager.get_state_data(notification.state_id)
login = state_data.get("login", "Unknown")
await notification.reply(f"Success! Profile created.\nLogin: `{login}`\nPass: `{password}`", "markdown")
notification.activate_next_scene(RegistrationScene())
@bot.router.register("message_created")
async def fsm_handler(notification):
if not notification.state_manager.get(notification.state_id):
notification.state_manager.create(notification.state_id)
current_scene = notification.get_current_scene()
if current_scene:
await current_scene.start(notification)
ΠΡΠ²Π΅Ρ Ρ ΠΌΠ΅Π΄ΠΈΠ°ΡΠ°ΠΉΠ»Π°ΠΌΠΈ#
ΠΠ±Π΅ΡΡΠΊΠ° Notification ΡΠΎΠ΄Π΅ΡΠΆΠΈΡ Π³ΠΎΡΠΎΠ²ΡΠ΅ Π°ΡΠΈΠ½Ρ
ΡΠΎΠ½Π½ΡΠ΅ ΠΌΠ΅ΡΠΎΠ΄Ρ Π΄Π»Ρ ΠΎΡΠΏΡΠ°Π²ΠΊΠΈ ΡΠ°ΠΉΠ»ΠΎΠ², Π³Π΅ΠΎΠ»ΠΎΠΊΠ°ΡΠΈΠΉ, ΡΡΠΈΠΊΠ΅ΡΠΎΠ² ΠΈ ΡΡΠ°ΡΡΡΠΎΠ² Π½Π°Π±ΠΎΡΠ° ΡΠ΅ΠΊΡΡΠ°.
@bot.router.command("/photo")
async def send_photo(notification):
await notification.show_action("sending_photo")
await notification.reply_with_media(
text="Check out this image!",
format_type="markdown",
file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
)
ΠΡΠΈΠΌΠ΅Ρ ΡΡ ΠΎ-Π±ΠΎΡΠ°#
ΠΠ»Ρ ΠΏΡΠΈΠΌΠ΅ΡΠ° ΡΠΎΠ³ΠΎ, ΠΊΠ°ΠΊ ΡΠ°Π±ΠΎΡΠ°ΡΡ Ρ MAX BOT API, ΠΏΡΠ΅Π΄Π»Π°Π³Π°Π΅ΠΌ Π²Π°ΠΌ ΠΊΠΎΠ΄ ΡΡ ΠΎ ΡΠ°Ρ-Π±ΠΎΡΠ°:
import asyncio
from maxbot_api_client_python import API, Config
from maxbot_chatbot_python import Bot, MapStateManager
async def main():
cfg = Config(
base_url="https://platform-api.max.ru/",
token="YOUR_BOT_TOKEN",
ratelimiter=25
)
async with API(cfg) as api_client:
bot = Bot(api_client)
bot.state_manager = MapStateManager(init_data={})
@bot.router.register("message_created")
async def echo_handler(notification):
try:
text = notification.text()
await notification.reply(f"**Echo:** {text}", "markdown")
except Exception as e:
print(f"Error handling message: {e}")
polling_task = asyncio.create_task(bot.start_polling())
try:
await polling_task
except asyncio.CancelledError:
pass
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Bot stopped by user (KeyboardInterrupt)")
ΠΠΈΡΠ΅Π½Π·ΠΈΡ#
ΠΠΈΡΠ΅Π½Π·ΠΈΡΠΎΠ²Π°Π½ΠΎ Π² ΡΠΎΠΎΡΠ²Π΅ΡΡΡΠ²ΠΈΠΈ Ρ MIT.