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

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"],
    },