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

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

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

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

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

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

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

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

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

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

python --version

Python 3.N.N

Если же вы знакомы с git, то скопировать проект можно следующим запросом:

git clone https://github.com/green-api/whatsapp-demo-chatbot-python.git

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

Список необходимых модулей для чатбота хранятся в файле requirements.txt. Введите следующий запрос в командную строку чтобы установить их

python -m pip install -r requirements.txt

2. Запуск чатбота#

Для того, чтобы настроить чатбот на своем аккаунте Whatsapp, Вам необходимо перейти в личный кабинет и зарегистрироваться. Для новых пользователей предоставлена инструкция для настройки аккаунта и получения необходимых для работы чатбота параметров, а именно:

idInstance
apiTokenInstance

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 /... и одну для картинки.

Ссылки должны вести на файлы из облачного хранилища или открытого доступа. На 81-й строке содержится следующий код:

elif message == "2":
    notification.api.sending.sendFileByUrl(
        chatId=notification.chat,
        urlFile="https://....png",
        fileName="corgi.png",
        caption=f'{data["send_file_message"][user.language]}'
                f'{data["links"][user.language]["send_file_documentation"]}',
    )

Данная строка после изменения будет в сkедующем формате:

elif message == "2":
    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"]}',
    )

elif message == "3":
    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 GreenAPIBot, Notification

bot = GreenAPIBot(id_instance, api_token_instance)

@bot.router.message(type_message=filters.TEXT_TYPES)
def message_handler(notification: Notification) -> None:

class User:
    def __init__(
        self,
        id: str,
        language: str = None,
        authorized: bool = None,
        last_updated: datetime = None,
    ):
        self.id = id
        self.language = language
        self.authorized = authorized
        self.last_updated = last_updated

Возвращаясь к файлу bot.py, после того, как пользователь отправит первое сообщение чатботу, чатбот проверяет есть ли данный пользователь в списке пользователей. Если нет, то новый пользователь создается.

Потом, чатбот ставит статус авторизации данного пользователя на True, чтобы обозначить что данный чат активен и просит пользователя выбрать язык общения:

if not user.authorized:
    user.authorize()
    notification.answer(data['select_language'])

"1 - English\n2 - Русский"

Чатбот принимает входящее уведомление и видит, что чат с данным пользователем активен проверив статус авторизации. После этого чатбот передает входящее уведомление в локальную функцию set_language, устанавливает язык общения с пользователем:

if message == "1":
    user.set_language("eng")
    notification.answer(
        f'{data["welcome_message"][user.language]}'
        f'{notification.event["senderData"]["senderName"]}'
        f'! '
        f'{data["menu"][user.language]}'
    )

message = "".join(
    i
    for i in notification.message_text
    if i not in ["/", ".", " ", "<", ">", "[", "]"]
).lower()

Например, если пользователь отправит 1, следующий код будет запущен:

if message == "1":
    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/

with open("data.yml", 'r', encoding='utf8') as stream:
    data = safe_load(stream)

welcome_message:
  ru: "Добро пожаловать в GREEN-API чатбот, "
  eng: "Welcome the to the GREEN-API chatbot, "

user.last_updated = datetime.now()

diff = datetime.now() - user.last_updated
if diff.seconds > 120:
    user.unauthorize()

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

Как и указывает чатбот в ответах, все сообщения отправлены через API. Документацию по методам отправки сообщений можно найти на сайте green-api.com/docs/api/sending.

Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документацию по методам получения сообщений можно найти на сайте green-api.com/docs/api/receiving/technology-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"],
    },