max-chatbot-python - библиотека для интеграции с мессенджером MAX через API сервиса green-api.com. Чтобы воспользоваться библиотекой, нужно получить регистрационный токен и ID аккаунта в личном кабинете. Есть бесплатный тариф аккаунта разработчика.
Документация к REST API находится по ссылке. Библиотека является обёрткой к REST API, поэтому документация по ссылке выше применима и к самой библиотеке.
Чтобы отправить сообщение или выполнить другие методы GREEN API, аккаунт MAX в приложении телефона должен быть в авторизованном состоянии. Для авторизации аккаунта перейдите в личный кабинет, запросите SMS код. Введите SMS код, после чего инстанс будет авторизован.
Установка:
python -m pip install max-chatbot-pythonfrom max_chatbot_python import GreenAPIBot, Notification
Перед запуском бота необходимо удалить (при наличии) адрес отправки уведомлений (URL) из личного кабинета или выставив пустой webhookUrl с помощью метода SetSettings. Следующие настройки будут включены ботом автоматически:
{
"incomingWebhook": "yes",
"outgoingMessageWebhook": "yes",
"outgoingAPIMessageWebhook": "yes"
}bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345"
)
bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345",
bot_debug_mode=True
)
Также можно включить режим отладки API:
bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345",
debug_mode=True, bot_debug_mode=True
)
Чтобы начать получать входящие уведомления, нужно настроить инстанс. Открываем страницу личного кабинета по ссылке. Выбираем инстанс из списка и кликаем на него. Нажимаем Изменить. В категории Уведомления включаем все что необходимо получать.
Чтобы начать получать сообщения, вам нужно создать функцию-обработчик с одним параметром (notification).
Параметр notification это класс в котором хранится объект уведомления (event) и функции для ответа на сообщение.
Чтобы отправить текстовое сообщение в ответ на уведомление, вам нужно вызвать функцию notification.answer и передать
туда текст сообщения. Параметр chatId указывать не нужно, так как он автоматически подставляется из уведомления.
Далее нужно добавить функцию-обработчик в список обработчиков. Сделать это можно с помощью
декоратора bot.router.message как в примере или с помощью функции bot.router.message.add_handler. Декоратор
обязательно нужно вызвать с помощью скобок.
Чтобы запустить бота, нужно вызвать функцию bot.run_forever.
Остановить бота можно с помощью сочетания клавиш Ctrl + C.
В этом примере бот ответит только на сообщение message.
Ссылка на пример: base.py.
@bot.router.message(text_message="message")
def message_handler(notification: Notification) -> None:
notification.answer("Hello")
bot.run_forever()
Получать можно не только входящие сообщения, но и исходящие. Также можно получать статус отправленного сообщения.
- Чтобы получать исходящие сообщения, нужно использовать объект
bot.router.outgoing_message; - Чтобы получать исходящие API сообщения, нужно использовать объект
bot.router.outgoing_api_message; - Чтобы получать статус отправленного сообщения, нужно использовать объект
bot.router.outgoing_message_status.
Тело уведомления находится в notification.event. В этом примере мы отправляем в консоль тело нового уведомления.
В этом примере бот получает все входящие сообщения.
Ссылка на пример: event.py.
@bot.router.message()
def message_handler(notification: Notification) -> None:
print(notification.event)
bot.run_forever()
Сообщения можно фильтровать по чату, по отправителю, по типу и тексту сообщения. Для фильтров чата, отправителя и типа
сообщения можно использовать строку (str) или список из строк (list[str]). Текст сообщения можно фильтровать по
тексту, по команде и регулярным выражениям. Ниже таблица с названиями фильтров и возможными значениями.
| Название фильтра | Описание | Возможные значения |
|---|---|---|
from_chat |
Чат или чаты от которых нужно получать сообщения | "[email protected]" или ["[email protected]", 10000000"] |
from_sender |
Отправитель или отправители от которых нужно получать сообщения | "[email protected]" или ["[email protected]", "10000000"] |
type_message |
Тип или типы сообщения, которые нужно обрабатывать | "textMessage" или ["textMessage", "extendedTextMessage"] |
text_message |
Ваша функция будет выполнена если текст полностью соответствует тексту | "message" или ["message", "MESSAGE"] |
regexp |
Ваша функция будет выполнена если текст полностью соответствует шаблону регулярного выражения | r"message" или (r"message", re.IGNORECASE) |
command |
Ваша функция будет выполнена если префикс и команда полностью соответствуем вашим значениям | "help" или ("help", "!/") |
@bot.router.message(command="command")
bot.router.message.add_handler(handler, command="command")
Чтобы фильтровать сообщения по чату, отправителю или типу сообщения, нужно добавить строку (str) или список из
строк (list[str]).
from_chat = "10000000"
from_sender = "10000000"
type_message = ["textMessage", "extendedTextMessage"]
Чтобы фильтровать сообщения по тексту сообщения, регулярным выражениям или команде, нужно добавить строку (str).
text_message = "Привет. Мне нужна помощь"
regexp = r"Привет. Мне нужна помощь"
Чтобы фильтровать сообщения по команде, нужно добавить строку (str) или кортеж (tuple). Вам нужно указать либо
название команды, либо название команды и строку префиксов. Префикс по умолчанию: /.
command = "help"
command = ("help", "!/")
В этом примере бот отправит фотографию в ответ на команду rates.
Ссылка на пример: filters.py.
@bot.router.message(command="rates")
def message_handler(notification: Notification) -> None:
notification.answer_with_file(file="data/rates.png")
bot.run_forever()
В качестве примера был создан бот для регистрации пользователя.
Чтобы управлять состоянием пользователя, нужно создать состояния. Импортируем класс BaseStates и наследуемся от него.
Для управления состоянием нужно использовать notification.state_manager. В менеджере есть методы получения, установки,
обновления и удаления состояния. Также у вас есть возможность сохранить данные пользователя в его состоянии.
| Метод менеджера | Описание |
|---|---|
get_state |
Возвращает класс состояния в котором есть имя состояния и данные пользователя |
set_state |
Устанавливает состояние для пользователя. Если состояние существует то данные будут удалены |
update_state |
Если состояние существует то изменяет его. Если нет то создает новое состояние |
delete_state |
Удаляет состояние пользователя. Не забудьте получить данные перед удалением |
get_state_data |
Если состояние существует то возвращает данные в виде словаря (dict) |
set_state_data |
Если состояние существует то изменяет данные на новые |
update_state_data |
Если состояние существует то обновляет данные. Если данных нет то данные будут созданы |
delete_state_data |
Если состояние существует то удаляет данные |
Первым аргументом является ID отправителя. Его можно получить обратившись к notification.sender.
Ссылка на пример: states.py.
from max_chatbot_python import BaseStates, GreenAPIBot, Notification
bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345"
)
class States(BaseStates):
USERNAME = "username"
PASSWORD = "password"
@bot.router.message(state=None)
def message_handler(notification: Notification) -> None:
sender = notification.sender
notification.state_manager.set_state(sender, States.USERNAME.value)
notification.answer("Hello. Tell me your username.")
@bot.router.message(command="cancel")
def cancel_handler(notification: Notification) -> None:
sender = notification.sender
state = notification.state_manager.get_state(sender)
if not state:
return None
else:
notification.state_manager.delete_state(sender)
notification.answer("Bye")
@bot.router.message(state=States.USERNAME.value)
def username_handler(notification: Notification) -> None:
sender = notification.sender
username = notification.message_text
if not 5 <= len(username) <= 20:
notification.answer("Invalid username.")
else:
notification.state_manager.update_state(sender, States.PASSWORD.value)
notification.state_manager.set_state_data(
sender, {"username": username}
)
notification.answer("Tell me your password.")
@bot.router.message(state=States.PASSWORD.value)
def password_handler(notification: Notification) -> None:
sender = notification.sender
password = notification.message_text
if not 8 <= len(password) <= 20:
notification.answer("Invalid password.")
else:
data = notification.state_manager.get_state_data(sender)
username = data["username"]
notification.answer(
(
"Successful account creation.\n\n"
f"Your username: {username}.\n"
f"Your password: {password}."
)
)
notification.state_manager.delete_state(sender)
bot.run_forever()- Как вызвать методы API?
bot.api.account.getSettings()
Или
notification.api.account.getSettings()
- Как отключить вызов ошибок?
bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345",
raise_errors=False
)
- Как подписаться только на текстовые сообщения?
Нужно сначала импортировать нужные константы:
from max_chatbot_python.filters import TEXT_TYPES
Затем добавить этот фильтр: type_message=TEXT_TYPES.
- Как получить текст сообщения и ID отправителя?
Эти данные есть в объекте уведомления (notification):
@bot.router.message()
def message_handler(notification: Notification) -> None:
print(notification.sender)
print(notification.message_text)
В качестве примера был создан бот для поддержки GREEN API. Список команд:
- start (бот поздоровается и отправит список команд)
- 1 или Report a problem (бот отправит ссылку на создание ошибки на GitHub)
- 2 или Show available rates (бот отправит картинку с тарифами)
- 3 или Call a support operator (бот отправит текстовое сообщение)
Чтобы отправить текстовое сообщение, нужно использовать метод notification.answer.
Чтобы отправить сообщение с файлом, нужно использовать метод notification.answer_with_file.
В этом примере бот отвечает только на команды из списка выше.
Ссылка на пример: full.py.
from max_chatbot_python import GreenAPIBot, Notification
bot = GreenAPIBot(
"3100000001", "d75b3a66374942c5b3c019c698abc2067e151558acbd412345"
)
@bot.router.message(command="start")
def message_handler(notification: Notification) -> None:
sender_data = notification.event["senderData"]
sender_name = sender_data["senderName"]
notification.answer(
(
f"Hello, {sender_name}. Here's what I can do:\n\n"
"1. Report a problem\n"
"2. Show available rates\n"
"3. Call a support operator\n\n"
"Choose a number and send to me."
)
)
@bot.router.message(text_message=["1", "Report a problem"])
def report_problem_handler(notification: Notification) -> None:
notification.answer(
"https://github.com/green-api/issues/issues/new", link_preview=False
)
@bot.router.message(text_message=["2", "Show available rates"])
def show_available_rates_handler(notification: Notification) -> None:
notification.answer_with_file("data/rates.png")
@bot.router.message(text_message=["3", "Call a support operator"])
def call_support_operator_handler(notification: Notification) -> None:
notification.answer("Good. A tech support operator will contact you soon.")
bot.run_forever()Документация по методам сервиса
Лицензировано на условиях Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) . LICENSE.