Чат-бот для ВКонтакте на Python на Callback API
Чат-боты стали уже очень распространенным явлением, и появляются во всех мессенджерах ежедневно.
В этой статье по шагам разберем создание бота с набором простых команд и узнаем, как в дальнейшем можно расширить его функционал. Статья будет полезна для самых новичков, которые никогда не пробовали создавать чат-ботов.
Когда мне захотелось создать бота, я изучила доступные примеры ботов для ВКонтакте и постаралась достигнуть максимального упрощения их структуры.
Для создания бота я использовал Python 3.5 (вероятно, подойдут и другие версии 3-го питона) и дополнительные библиотеки Flask и VK. Их надо будет установить. По установке Flask есть много статей на русском. Если у вас стоит Pycharm, то он, скорее всего, установился вместе с ним.
Начнем с самого API. Для нашего бота будем использовать Callback API, доступный для сообщений групп. Прежде всего, нам нужно создать или уже иметь группу ВКонтакте с подключенными сообщениями.
В разделе управление сообществом → работа с API необходимо создать ключ с доступом к сообщениям сообщества.
Для работы с Callback нужно иметь веб-сервер, который будет принимать запросы о каких-либо событиях от API, обрабатывать их и посылать ответные запросы. То есть мы напишем «сайт», который будет только отвечать на посылаемые ему запросы и посылать свои.
Поскольку пишем на питоне, самое простое, что можно использовать, — это хостинг для питона. Я пользовался бесплатным хостингом для Python. Там нужно зарегистрироваться, а затем создать приложение для питона 3.5 на Flask (создать можно в разделе Web). Будет создан начальный файл:
Единственная функция, которая сейчас есть в файле, отвечает за наполнение страницы по адресу, выданному при регистрации. Если перейти в браузере по адресу username.pythonanywhere.com (со своим ником), то можно увидеть только текст «Hello from Flask!».
В дальнейшем код будет изложен блоками и после завершения целого блока можно будет проверить, а в процессе код может быть помечен средой как ошибочный. Не стоит этого пугаться, лучше просто доделать блок до конца.
Итак, БЛОК 1.
Для обработки запросов, посылаемых сайту, добавим в конце документа следующий код:
Где вместо иксов подставляем «строку, которую должен вернуть сервер». Она указана в управлении группой в разделе Callback API.
Эта функция позволит нам подключить наш сайт для уведомлений к группе.
Теперь можем проверить работу. Только необходимо перезагрузить приложение. На хостинге после того, как файлы были изменены и сохранены, чтобы сайт стал работать с новыми данными, нужно его перезагрузить во вкладке Web. После добавления этого кода можем ввести соответствующий адрес username.pythonanywhere.com в строку адреса сервера в группе ВКонтакте и нажать «Подтвердить».
Должно появиться зеленое уведомление о том, что адрес сервера успешно подключен.
При нажатии «Подтвердить» ВКонтакте пытается связаться с нашим сервером и убедиться, что он действительно принадлежит владельцу группы, и «ждет», что сервер вернет код подтверждения в ответ на запрос.
БЛОК 2
Можем переходить к следующему шагу. Добавим возможность писать сообщения от имени сообщества. Пришло время установить на хостинге библиотеку VK. В разделе Consoles запускаем bash-консоль и исполняем команду (или соответствующую для выбранной версии питона):
Как устанавливать модули описано здесь.
Изменим код нашей функции по обработке входящих запросов:
Сообщение о том, что обработка прошла успешно, нужно серверу ВКонтакте. Если произойдет ошибка, или придет какой-то иной ответ, сервер будет с некоторыми промежутками продолжать посылать уведомление о входящем сообщении (пока мы его не обработаем).
Структура входящего запроса, оповещающего о новом сообщении, такова:
Вконтакте передает нашему сайту несколько объектов: «type», «object», «group_id», а внутри «object» хранится информация о самом сообщении.
Все запросы можно посмотреть в документации ВКонтакте.
Также добавляем новые «import» в начало файла:
Мы создали новый файл в этой же папке settings.py, в котором сохранены необходимые данные для входа:
Их надо заменить на ваши токены. Первый мы создали в начале статьи, второй – код подтверждения, чтобы соединить группу с сервером.
Теперь наш бот может на входящие сообщения здороваться и подтверждать свою принадлежность группе, код которой мы ему дали.
Можем его проверить и написать ему какое-нибудь сообщение, только надо подключить в настройках группы в разделе Callback API уведомления о входящих сообщениях.
Чтобы бот стал слать сообщения, нужно перезагрузить приложение. После этого снова пишем боту и, если все в порядке, переходим к следующему шагу.
БЛОК 3
Если все прошло хорошо, и бот с вами поздоровался в ответ на ваше сообщение, переходим к следующему шагу. Вынесем все взаимодействие с библиотекой vk в другой файл, я назвал его vkapi:
Пока там только одна функция и инициализация сессии ВКонтакте, потом добавим другие. Потенциально функция может также отправлять и вложения. Позже мы воспользуемся этой возможностью.
Дальше заведем файл — обработчик сообщений. Он будет обрабатывать входящие сообщения, определять соответствующие команды, когда они появятся, и выдавать нужные ответы.
Осталось подключить наши новые файлы к основному. Изменяем функцию обработки запросов в главном файле:
И добавляем соответствующий импорт в начало файла:
Можем проверить, что у нас получилось, перезагрузив приложение.
БЛОК 4
Приступим к созданию команд. Создадим класс команд.
У класса есть свойство keys, где будут храниться ключи, по которым можно обратиться к данной команде. Все ключи сохраняются в строчных буквах при задании свойства, и сравнивать их нужно с переведенными в строчную форму сообщениями пользователя, чтобы регистр не влиял на успех вызова команды.
Поле description будем использовать для выдачи информации по командам бота. Функция process будет исполняться для формирования ответного сообщения.
Есть общий список, в который сохраняются все команды при их инициализации. Он находится снаружи класса. Этот список будем использовать для поиска команды, которую запросил пользователь своим сообщением.
Теперь создадим несколько команд для нашего бота. Для удобства загрузки будем помещать файлы, в которых инициализируем команды, в папку «commands».
Я создам несколько файлов, но можно и разместить команды и в одном файле
Для команды, отправляющей котика, нам понадобится новый токен и новая функция и в файле «vkapi», которая возвращает случайную картинку со стены группы или пользователя. В данном случае будем получать случайную фотографию со стены паблика с котами.
Начнем с получения токена. Нам нужен сервисный ключ доступа. Для этого надо создать новое Standalone-приложение. Его можно создать по ссылке. Далее когда приложение будет создано, нужно перейти в его настройки и скопировать то, что находится в поле «Сервисный ключ доступа».
Это нужно внести в наш файл с токенами.
«settings.py»
Теперь перейдем к созданию нового метода vkapi. Здесь немного расширяем спектр используемых методов API.
Этот метод выглядит так:
Дописываем его в файл «vkapi». Также в начало файла «vkapi» надо добавить необходимый импорт:
И последняя команда
Окончательная иерархия файлов:
botFlask — главный файл, который принимает входящие запросы.
Теперь, когда мы описали команды, нужно позаботиться о том, чтобы наш лист команд был наполнен, и мы могли понять, к какой из команд обращался пользователь, так как список “command_list” заполняется только в момент запуска файлов с конкретными командами.
Мы будем автоматически запускать на исполнение все файлы из папки «commands» при запуске нашего бота.
Для этого в файле «messageHandler.py» дописываем функцию:
В этой функции мы загружаем список файлов из директории с командами, отфильтровываем только файлы питона и импортируем их в нашу программу, что обеспечивает заполнение списка командами.
Вызов этой функции добавляем в «create_answer». Теперь изменим функцию «get_answer» так, чтобы она вызывала соответствующий ответ.
Итоговый вид файла:
Все, наш бот готов! Теперь вы знаете, как создать основу для бота и добавить для него новые команды.
БЛОК 5
Дальнейшая часть статьи будет про одно улучшение, которое я считаю необходимым. Однако бот будет работать и без этого.
Приблизительное распознавание команд
Если пользователь допустил ошибку в одном символе, скорее всего, он имел в виду максимально похожую команду. Поэтому было бы хорошо, если бы наш бот все равно давал ответ, а не говорил «не понимаю тебя».
Для приблизительного распознавания будем использовать расстояние Дамерау-Левенштейна. Оно показывает, за сколько операций удаления, вставки, замены и перемещения символов можно перейти от одной строки к другой.
Алгоритм нахождения этого расстояния изложен, например, в Википедии.
Добавляем в файл “messageHandler.py” функцию:
Она реализует алгоритм нахождения этого расстояния, при желании вы можете его изменить или улучшить.
По данным строкам она будет выдавать количество операций для преобразования одной в другую. Теперь изменим метод «get_answer»:
В этой функции мы вычисляем расстояние для сообщения и каждого из ключей. Если совпадение неточное, пишем, как бот распознал каждую из тех команд, которые ему отправили. В случае, если расстояние превысило 40% от длины поданного сообщения, считаем, что пользователь ошибся слишком сильно и возвращаем сообщение по умолчанию, где предлагаем обратиться к помощи.
На этом все, рабочий (на момент написания статьи) код выложен на гитхабе.
Надеюсь, эта статья немного облегчит вам жизнь, если вы решили создать своего бота для VK.
Источник
Как настроить веб хуком для callback api
Callback API — это инструмент для отслеживания активности пользователей в Вашем сообществе ВКонтакте. С его помощью Вы можете реализовать, например:
- Бота для отправки мгновенных ответов на поступающие сообщения.
- Систему автоматической модерации контента.
- Сервис для сбора и обработки показателей вовлеченности аудитории.
Чтобы начать использовать Callback API, подключите свой сервер в настройках сообщества («Управление сообществом» → «Настройки» → «Работа с API»). Выберите типы событий, данные о которых требуется получать, например, новые комментарии и новые фотографии.
Когда в сообществе произойдет событие выбранного типа, ВКонтакте отправит на Ваш сервер запрос с данными в формате JSON с основной информацией об объекте, вызвавшем событие (например, добавленный комментарий).
В ответ на каждое уведомление о событии Ваш сервер должен отправить строку «ok».
Вам больше не нужно регулярно повторять запросы к API, чтобы отслеживать обновления — теперь Вы будете получать их мгновенно.
Для подключения Callback API нужно открыть раздел «Управление сообществом» («Управление страницей», если у Вас публичная страница), перейти во вкладку «Работа с API».
Далее необходимо указать и подтвердить конечный адрес сервера, куда будут направлены все запросы. Вы можете подключить до 10 серверов для Callback API, задать каждому из них отдельный набор событий и версию API.
После указания адреса сервера и нажатия на кнопку «подтвердить» на указанный Вами адрес отправится запрос с уведомлением типа «confirmation». Ваш сервер должен вернуть заданную строку.
Обратите внимание: строка подтверждения меняется время от времени. Если Вы добавляете новый сервер или редактируете настройки старого, то необходимо указать новую строку подтверждения. Получить строку подтверждения можно с помощью метода groups.getCallbackConfirmationCode. Также ее можно посмотреть в управлении сообществом.
Строку подтверждения, которую возвращает метод, можно использовать только для настройки сервера с помощью API. В настройках Вашего сообщества на сайте ВКонтакте код будет отличаться.
После подтверждения адреса сервера Вам станут доступны настройки уведомлений.
Во вкладке «Запросы» Вы сможете видеть историю событий и содержимое запросов, отправленных на Ваш сервер.
Обратите внимание: после получения уведомления Ваш сервер должен возвращать строку «ok» и статус HTTP 200. Если сервер несколько раз подряд вернет ошибку, Callback API временно перестанет отправлять на него уведомления.
Добавлять, удалять и редактировать сервера для Callback API Вы также можете с помощью методов секции groups.
Для удаления сервера Вы можете отправить remove в ответ на уведомление о любом событии.
В зависимости от указанной версии объекты в событиях будут иметь разный формат. Ознакомиться с отличиями версий можно на этой странице.
В поле «Секретный ключ» Вы можете указать произвольную строку, которая будет передаваться в уведомлении на Ваш сервер в поле secret.
Чтобы гарантировать безопасность передачи данных, мы рекомендуем загрузить SSL-сертификат в настройках Callback API Вашего сообщества.
Подробная информация о сертификате доступна на этой странице.
Обратите внимание!
Фактическое время переотправки уведомления о событии может оказаться больше указанного.
Источник
База знаний
- Created: 19.04.2017
В LeadBack предусмотрен вариант интеграции через настройку исходящего webhook. Это позволяет получать данные из сервиса (обратные звонки и чаты) в реальном времени. Информация о том что заказан обратный звонок будет передена на ваш URL-обработчик (он же webhook) в момент когда звонок состоится. Тоже самое относится и к информации по чатам на сайте.
Этот механизм удобно использовать для интеграции с внешней системой (например CRM).
Настройка Webhook
Для настройки вебхука нужно зайти в профиль нужного аккаунта LeadBack и найти подраздел API. В поле URL-адрес обработчика указать адрес куда будут отправляться события.
Настройка адреса URL-обработчика для Webhook
Обратите внимание, чтобы настройки вебхук сохранились, адрес вы должны указать действующий адрес URL-обработчика. В момент сохранения, адрес проверяется на доступность (отправляется тестовый http-запрос). Если ваш обработчик вернет http-статус отличный от 200, настройки не будут сохранены.
Безопасность при использовании Webhook
Чтобы вы могли однозначно понимать что запрос на обработчик пришел от Leadback, используйте секретный параметр в URL (пример URL-обработчика с секретным параметром: https://myserver.com/webhook/leaback.php?key=WsETKhVTeNpiF4uNy2KfDYjMy). В коде обработчика вы будете проверять параметр key на соответствие заданному вами значению и если значение верное, то запрос на обработчик пришел от LeadBack.
Для обеспечения дополнительной безопастности (от перехвата данных) мы рекомендуем использовать https адрес (для этого у вас на сервере должен быть настроен валидный SSL-сертификат для домена).
Типы передаваемых событий
- новый обратный звонок
- новый диалог в онлайн чате (с оператором или ботом)
- проверка вебхук
Структура данных
Для всех событий данные передаются в виде JSON объекта методом POST в поле payload. Ниже показан пример получения данных для php:
Для всех событий JSON-объект имеет единую структуру с 2 полями данных:
- event_type — тип события. Доступны значения:
- pre_call — предварительные данные о новом обратном звонке;
- call — принят или пропущен обратный звонок;
- chat_dialog — состоялся диалог в чате с оператором;
- bot_dialog — состоялся диалог в чате с ботом;
- check_webhook — проверка доступности webhook;
- data — данные по событию.
Новый обратный звонок
Событие срабатывает перед запуском дозвона (event_type=pre_call) и когда был принят или пропущен обратный звонок с сайта (event_type=call).
В данных события доступны следующие поля:
| Поле | Тип | Описание |
|---|---|---|
| id_call | int | ID звонка |
| user_id | int | ID клиента |
| widget_id | int | ID виджета |
| date_create | datetime | Дата и время создания заявки на звонок |
| date_update | datetime | Дата и время последнего обновления информации о звонке |
| callback_phone | string | Номер телефона заказавшего обратный звонок |
| operator_phone | string | Номер телефона сотрудника который принял звонок |
| site | string | Домен сайта на котором заказан обратный звонок |
| user_tariff | string | Тариф клиента |
| tariffed_minutes | int | Потрачено минут связи с баланса аккаунта |
| duration | int | Продолжительность разговора в секундах |
| record_url | string | Ссылка на запись разговора |
| callback_answer | string | Заказавший звонок ответил на него (no — нет, yes — да) |
| visit_uuid | string | ID посетителя |
| visit_id | string | ID визита |
| visit_ip | string | IP заказавшего обратный звонок |
| visit_source | string | Источник звонка |
| delayed_time | datetime | Дата и время на которое перенесен звонок (если звонок заказан в не рабочее время) |
| status | string | Статус звонка (complete — принят, failed — пропущен) |
| call_time | datetime | Дата и время когда состоялся звонок |
| visit_data | object | Полная информация о источнике звонка |
| visit_profile | object | Данные посетителя если были заполнены в форма онлайн чата (имя, email и телефон) |
Информация о источнике звонка visit_data имеет следующие данные (поля для visit_data идентичны для всех типов событий):
| Поле | Тип | Описание |
|---|---|---|
| visit_id | string | ID визита |
| date_visit | datetime | Дата и время визита |
| visit_source | string | Источник звонка (значения: direct, internal, search, social, utm, cpc, email, unknown) |
| referer_url | string | Адрес источника визита |
| page_url | string | Страница входа |
| call_url | string | Страница звонка |
| ga_cid | string | Идентификатор клиента для Google Analytics (Client ID) |
| roistat_visit | string | Roistat номер визита (промокод), передается если на сайте используется код сервиса Roistat |
| visit_ip | string | IP посетителя |
| visit_ua | string | Браузер посетителя (UserAgent) |
| utm_source | string | UTM-метка source (для visit_source=utm или cpc) |
| utm_medium | string | UTM-метка medium (для visit_source=utm или cpc) |
| utm_campaign | string | UTM-метка campaign (для visit_source=utm или cpc) |
| utm_term | string | UTM-метка term (для visit_source=utm или cpc) |
| utm_content | string | UTM-метка content (для visit_source=utm или cpc) |
| search_engine | string | Поисковая система для visit_source=search или cpc (значения: google, yandex, go.mail.ru, bing.com, yahoo.com, about.com, aol.com, ask.com, globososo.com, rambler.ru, tut.by, nigma.ru) |
| search_text | string | Поисковая фраза |
| search_href | string | Ссылка на поисковую выдачу для фразы |
Пример JSON данных для обратного звонка:
Новый диалог в чате с оператором
Отправляется когда завершится диалог в чате с вашим онлайн оператором.
В данных события доступны следующие поля:
| Поле | Тип | Описание |
|---|---|---|
| widget_id | int | ID виджета |
| user_id | int | ID клиента |
| dialog_id | string | ID диалога |
| chat_log | array | Сообщения переписки посетителя с оператором |
| operator | object | Информация о операторе который вел диалог с посетителем |
| visit_data | object | Полная информация о источнике визита посетителя |
| visit_profile | object | Данные посетителя если были заполнены в форма онлайн чата (имя, email и телефон) |
Данные оператора в поле operator:
| Поле | Тип | Описание |
|---|---|---|
| id_operator | int | ID оператора |
| operator_jid | string | Логин оператора |
| operator_name | string | Имя оператора |
| avatar_type | string | Тип аватарки (custom, standart) |
| avatar_url | string | Адрес на аватарку оператора |
История переписки в поле chat_log это массив объектов с полями:
| Поле | Тип | Описание |
|---|---|---|
| id_message | int | ID сообщения |
| date_create | datetime | Дата и время сообщения |
| message_from | string | От кого сообщение |
| message_to | string | Кому сообщение |
| message_type | string | Тип сообщения (visitor, operator) |
| message | string | Текст сообщения |
| answer_time | int | Время ответа оператора на последние сообщение посетителя в секундах (для message_type=operator). |
Поля visit_data и profile_data аналогичны как для события новый обратный звонок.
Пример JSON данных диалога с оператором:
Новый диалог в чате с ботом
Отправляется когда завершится диалог в чате с ботом.
В данных события доступны следующие поля:
| Поле | Тип | Описание |
|---|---|---|
| widget_id | int | ID виджета |
| user_id | int | ID клиента |
| dialog_id | string | ID диалога |
| chat_log | array | Сообщения переписки с посетителя и бота |
| visit_data | object | Полная информация о источнике визита посетителя |
| visit_profile | object | Данные посетителя если были заполнены в форма онлайн чата (имя, email и телефон) |
История переписки в поле chat_log это массив объектов с полями:
| Поле | Тип | Описание |
|---|---|---|
| id_message | int | ID сообщения |
| date_create | datetime | Дата и время сообщения |
| message_type | string | Тип сообщения (visitor, bot) |
| message | string | Текст сообщения |
Поля visit_data и profile_data аналогичны как для события новый обратный звонок.
Пример JSON данных диалога с ботом:
Проверка вебхук адреса
Тестовый запрос. Отправляется во время сохранения адреса webhook адреса, для проверки его доступности.
Источник