Перейти к содержанию

GREEN-API Python демо чатбот

Внимание!!!

Текущая версия устарела и оставлена для совместимости. Актуальную версию можно найти по ссылке.

Python демо чатбот это пример чатбота написанного с помощью библиотеки Python chatbot Whatsapp, которая разработана специально для написания чатботов с использованием сервиса Green API.

Чатбот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, локаций и контактов.

Отсканируйте QR-код или перейдите по ссылке для начала общения с чатботом

chatbot-QR

Ссылка на бота

Для запуска чатбота на собственном Whatsapp аккаунте следуйте инструкциям:

  1. Установка среды для запуска чатбота
  2. Запуск чатбота
  3. Настройка чатбота
  4. Использование
  5. Структура кода
  6. Управление сообщениями

1. Установка среды для запуска чатбота

Для запуска чатбота необходимо произвести установку среды python. Для этого надо пройти по официальный вэбсайт python и загрузить последний релиз подходящий для вашей операционной системы.

После этого загрузится установщик, который надо открыть и начать установку. Следуйте настройкам по умолчанию и завершите установку среды.

После завершения необходимо проверить была ли среда развернута корректно. Для этого откройте командную строку (cmd) и введите запрос:

python --version
Ответом на введеный запрос должна быть версия python в следующем формате:
Python 3.N.N
После того, как вы убедились, что среда python установлена на ваш компьютер, надо скачать зип-файл проекта whatsapp-demo-chatbot-python и распаковать его.

Если же вы знакомы с 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
Среда для запуска чатбота готова, теперь необходимо произвести настройку и запустить чатбот на вашем аккаунте Whatsapp.

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"]}',
        )
Таким же образом введите ссылку и название для картинки на 120-й строке:
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"]}',
    )
Все изменения должны быть сохранены, после чего можно запускать чатбот. Для запуска чатбота вернитесь к пункту 2.

4. Использование

Если предыдущие шаги были выполнены, то на вашем аккаунте Whatsapp должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в личном кабинете.

Теперь вы можете отправлять сообщения чатботу!

Чатбот откликнется на любое сообщение отправленное на аккаунт. Так как чатбот поддерживает 2 языка - русский и английский - то прежде чем поприветсвовать собеседника, чатбот попросит выбрать язык общения:

1 - English
2 - Русский
Ответьте 1 или 2, чтобы выбрать язык для дальнейшего общения. После того, как вы отправите 2, чатбот пришлет приветственное сообщение на русском языке:
Добро пожаловать в GREEN-API чатбот, пользователь! GREEN-API предоставляет отправку данных следующих видов. Выберите цифру из списка, чтобы проверить как работает метод отправки

1. Текстовое сообщение 📩
2. Файл 📋
3. Картинка 🖼
4. Контакт 📱
5. Геолокация 🌎

Чтобы вернуться в начало напишите стоп
Выбрав число из списка и отправив его, чатбот ответит каким API был отправлен данный тип сообщения и поделится ссылкой на информацию об API.

Например, отправив 1, пользователь получит в ответ:

Это сообщение отправлено через sendMessage метод

Чтобы узнать как работает метод, пройдите по ссылке 

https://green-api.com/docs/api/sending/SendMessage/
Если отправить что-то помимо чисел 1-5, то чатбот лаконично ответит:
Извините, я не совсем вас понял, напишите меню, чтобы посмотреть возможные опции
Так же пользователь может вызвать меню, отправив сообщение содержащее "меню". И отправив "стоп", пользователь завершит беседу с чатботом и получит сообщение:
Спасибо за использование чатбота GREEN-API, пользователь!

5. Структура кода

Функциональная часть чатбота находится в файле bot.py. Здесь импортируется класс чатбота GreenAPIBot и входящее уведомление Notification для обработки сообщений:

from whatsapp_chatbot_python import (
    BaseStates,
    GreenAPIBot,
    Notification,
    filters,
)
Инициализация чатбота происходит на 26-й строке:
bot = GreenAPIBot(
    ID_INSTANCE,
    API_TOKEN_INSTANCE
)
Также есть маршрутизатор, который прослушивает уведомления, вызываемые каждый раз, когда отправляется текстовое сообщение чат-боту. Сообщения обрабатываются далее, если они проходят через установленные фильтры. Например, каждый раз, когда пользователь отправляет сообщение, состояние чата равно None, что фильтруется маршрутизатором:
@bot.router.message(type_message=filters.TEXT_TYPES,
                    state=None)
Обработчик получает сообщения через входящие уведомления типа webhook. Проверив данные о пользователе, который отправил сообщение, чатбот сохраняет отправителя в объекте класса 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 - Русский"
Пользователь отправляет 1 или 2, тем самым выбрав язык общения с чатботом.

Чат-бот видит, что у пользователя с таким номером есть активный чат, проверяя фильтр 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]}'
    )
Фильтр text_message обрабатывает ['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()
Это сделано для того, чтобы проверять когда пользователь обращался в последний раз. Если прошло более 2 минут с последнего обращения, значит чатбот сбросит авторизацию и язык общения, и начнет чат заново:
if diff > 120:
    self.users.get(chat).set_language(None)

6. Управление сообщениями

Как и указывает чатбот в ответах, все сообщения отправлены через API. Документация по методам отправки сообщений.

Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документация по методам получения сообщений.

Чатбот использует библиотеку whatsapp-chatbot-python, где уже интегрированы методы отправки и получения сообщений, поэтому сообщения вычитываются автоматически, а отправка обычных текстовых сообщений упрощена.

Например, чатбот автоматически отправляет сообщение контакту, от которого получил сообщение:

notification.answer(data["select_language"])
Однако другие методы отправки можно вызвать напрямую из библиотеки whatsapp-api-client-python. Как, например, при отправке контакта:
notification.api.sending.sendContact(
    chatId=notification.chat,
    contact={
        "phoneContact": notification.chat.split("@")[0],
        "firstName": notification.event["senderData"]["senderName"],
    },