GREEN-API Python демо чатбот
Внимание!!!
Текущая версия устарела и оставлена для совместимости. Актуальную версию можно найти по ссылке.
Python демо чатбот это пример чатбота написанного с помощью библиотеки Python chatbot Whatsapp, которая разработана специально для написания чатботов с использованием сервиса Green API.
Чатбот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, локаций и контактов.
Отсканируйте QR-код или перейдите по ссылке для начала общения с чатботом
Для запуска чатбота на собственном Whatsapp аккаунте следуйте инструкциям:
- Установка среды для запуска чатбота
- Запуск чатбота
- Настройка чатбота
- Использование
- Структура кода
- Управление сообщениями
1. Установка среды для запуска чатбота
Для запуска чатбота необходимо произвести установку среды python. Для этого надо пройти по официальный вэбсайт python и загрузить последний релиз подходящий для вашей операционной системы.
После этого загрузится установщик, который надо открыть и начать установку. Следуйте настройкам по умолчанию и завершите установку среды.
После завершения необходимо проверить была ли среда развернута корректно. Для этого откройте командную строку (cmd) и введите запрос:
python --version
Python 3.N.N
Если же вы знакомы с git, то скопировать проект можно следующим запросом:
git clone https://github.com/green-api/whatsapp-demo-chatbot-python.git
cmd
и нажать Enter
. Для запуска чатбота так же необходимо установить модуль whatsapp-chatbot-python и несколько других модулей через менеджер пакетов pip, который установлен в среде по умолчанию.
Список необходимых модулей для чатбота хранятся в файле requirements.txt. Введите следующий запрос в командную строку чтобы установить их
python -m pip install -r requirements.txt
2. Запуск чатбота
Для того, чтобы настроить чатбот на своем аккаунте Whatsapp, Вам необходимо перейти в личный кабинет и зарегистрироваться. Для новых пользователей предоставлена инструкция для настройки аккаунта и получения необходимых для работы чатбота параметров, а именно:
idInstance
apiTokenInstance
bot.py
и введите idInstance
и apiTokenInstance
в следующий объект на 23-й строке. Иниализация данных необходима для связывания бота с Вашим Whatsapp аккаунтом: id_instance = ''
api_token_instance = ''
bot = GreenAPIBot(id_instance, api_token_instance)
python bot.py
В библиотеке whatsapp-chatbot-python прописан механизм изменения настроек инстанса методом SetSettings, который запускается при включении чатбота.
Все настройки по получению уведомлений выключены по умолчанию, чатбот включит следующие настройки:
"incomingWebhook": "yes",
"outgoingMessageWebhook": "yes",
"outgoingAPIMessageWebhook": "yes",
Процесс изменения настроек занимает несколько минут, в течении этого времени инстанс будет недоступен. Сообщения отправленные чатботу в это время не будут обработаны.
После того, как будут применены настройки, произойдет удаление уведомлений о полученных ранее входящих сообщениях. Этот процесс так же прописан в библиотеке whatsapp-chatbot-python и автоматически запускается после изменения настроек.
Это необходимо для того, чтобы чатбот не начал обрабатывать сообщения со старых чатов.
После того, как изменения настроек и удаление входящих уведомлений будут исполнены, чатбот начнет стандартно отвечать на сообщения. Суммарно этот процесс занимает не больше 5 минут.
Чтобы остановить работу чатбота, наведите курсор на командную строку и используйте сочетание клавиш Ctrl + C
3. Настройка чатбота
По умолчанию чатбот использует ссылки для выгрузки файлов из сети, однако пользователи могут добавить свои ссылки на файлы, одну для файла любого расширения pdf / docx /... и одну для картинки.
Ссылки должны вести на файлы из облачного хранилища или открытого доступа. На 101-й строке содержится следующий код:
def option_2(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...png',
fileName='...png',
caption=f'{data["send_file_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
urlFile=""
и задайте имя файлу в fileName=""
. Имя файла должно содержать расширение, например "somefile.pdf". Данная строка после изменения будет в сkедующем формате:
def option_2(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...somefile.pdf',
fileName='somefile.pdf',
caption=f'{data["send_file_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
def option_3(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...someimage.jpg',
fileName='someimage.jpg',
caption=f'{data["send_image_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
4. Использование
Если предыдущие шаги были выполнены, то на вашем аккаунте Whatsapp должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в личном кабинете.
Теперь вы можете отправлять сообщения чатботу!
Чатбот откликнется на любое сообщение отправленное на аккаунт. Так как чатбот поддерживает 2 языка - русский и английский - то прежде чем поприветсвовать собеседника, чатбот попросит выбрать язык общения:
1 - English
2 - Русский
Добро пожаловать в GREEN-API чатбот, пользователь! GREEN-API предоставляет отправку данных следующих видов. Выберите цифру из списка, чтобы проверить как работает метод отправки
1. Текстовое сообщение 📩
2. Файл 📋
3. Картинка 🖼
4. Контакт 📱
5. Геолокация 🌎
Чтобы вернуться в начало напишите стоп
Например, отправив 1, пользователь получит в ответ:
Это сообщение отправлено через sendMessage метод
Чтобы узнать как работает метод, пройдите по ссылке
https://green-api.com/docs/api/sending/SendMessage/
Извините, я не совсем вас понял, напишите меню, чтобы посмотреть возможные опции
Спасибо за использование чатбота GREEN-API, пользователь!
5. Структура кода
Функциональная часть чатбота находится в файле bot.py
. Здесь импортируется класс чатбота GreenAPIBot
и входящее уведомление Notification
для обработки сообщений:
from whatsapp_chatbot_python import (
BaseStates,
GreenAPIBot,
Notification,
filters,
)
bot = GreenAPIBot(
ID_INSTANCE,
API_TOKEN_INSTANCE
)
None
, что фильтруется маршрутизатором: @bot.router.message(type_message=filters.TEXT_TYPES,
state=None)
user
. Данный класс хранится в файле user_manager.py
и имеет 2 поля: @dataclass
class User:
language: Optional[str] = None
ts: Optional[datetime] = None
id
, язык общения, статус авторизации, и время последнего общения с пользователем. Каждое поле используется в логике чатбота, но об этом будет упоминаться позже. Возвращаясь к файлу bot.py
, после того, как пользователь отправит первое сообщение чатботу, чатбот проверяет есть ли данный пользователь в списке пользователей. Если нет, создается новый пользователь, и состояние чата устанавливается в ACTIVE
.
notification.state_manager.update_state(notification.sender,
States.ACTIVE.value)
user = manager.check_user(notification.chat)
notification.answer(data['select_language'])
notification.answer()
это функция библиотеки чатбота, которая проверяет данные о пользователе из входящего уведомления и отправляет ответ данному пользователю. data['select_language']
это один из текстовых ответов чатбота, приготовленных заранее: "1 - English\n2 - Русский"
Чат-бот видит, что у пользователя с таким номером есть активный чат, проверяя фильтр state=States.ACTIVE.value
. Функция устанавливает поле языка пользователя и устанавливает значение состояния в state=States.LANGUAGE_SET.value
, сообщая боту, что язык взаимодействия в этом чате уже выбран.
@bot.router.message(type_message=filters.TEXT_TYPES,
state=States.ACTIVE.value,
text_message=['1', '/1', '1.', '1 '])
def set_eng(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
user.set_language('eng')
notification.state_manager.update_state(notification.sender,
States.LANGUAGE_SET.value)
notification.answer(
f'{data["welcome_message"][user.language]}'
f'{notification.event["senderData"]["senderName"]}'
f'! '
f'{data["menu"][user.language]}'
)
['1', '/1', '1.', '1 ']
, если пользователь отправил избыточные символы. После этого чат-бот устанавливает состояние чата в state=States.LANGUAGE_SET.value
и ожидает команды 1-5 от пользователя. Например, если пользователь отправит 1, следующий код будет запущен:
@bot.router.message(type_message=filters.TEXT_TYPES,
state=States.LANGUAGE_SET.value,
text_message=['1', '/1', '1.', '1 '])
def option_1(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.answer(
f'{data["send_text_message"][user.language]}'
f'{data["links"][user.language]["send_text_documentation"]}'
)
Это сообщение отправлено через sendMessage метод
Чтобы узнать как работает метод, пройдите по ссылке
https://green-api.com/docs/api/sending/SendMessage/
data.yml
и загружены в bot.py
: with open("data.yml", 'r', encoding='utf8') as stream:
data = safe_load(stream)
data['welcome_message']['ru']
вернет приветсвенное сообщение на русском языке, а data['welcome_message']['eng']
- на английском языке: welcome_message:
ru: "Добро пожаловать в GREEN-API чатбот, "
eng: "Welcome the to the GREEN-API chatbot, "
ts
обновляется новым временем: def update_ts(self):
self.ts = datetime.now()
if diff > 120:
self.users.get(chat).set_language(None)
6. Управление сообщениями
Как и указывает чатбот в ответах, все сообщения отправлены через API. Документация по методам отправки сообщений.
Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документация по методам получения сообщений.
Чатбот использует библиотеку whatsapp-chatbot-python, где уже интегрированы методы отправки и получения сообщений, поэтому сообщения вычитываются автоматически, а отправка обычных текстовых сообщений упрощена.
Например, чатбот автоматически отправляет сообщение контакту, от которого получил сообщение:
notification.answer(data["select_language"])
notification.api.sending.sendContact(
chatId=notification.chat,
contact={
"phoneContact": notification.chat.split("@")[0],
"firstName": notification.event["senderData"]["senderName"],
},