Как сделать кнопки быстрых ответов(keyboard) для ботов в ВК

Недавно Вконтакте опубликовала новый функционал для ботов ВК — кнопки быстрых ответов или же keyboard.

ВАЖНО! Более свежая версия статьи находится здесь

Наша команда «ботописцев» сразу заинтересовалась этим нововведением и начала изучать официальную API, чтобы рассказать вам и показать подробную инструкцию по созданию бота использующего keyboard. В ходе этой статьи получится бот, посмотреть работу которого вы можете в нашей группе GameTips в ВК. Так же вы можете присоединиться к беседе-комьюнити в вк, где вам могут помочь с возникшей проблемой.

Оглавление:

1. Создание и настройка сообщества
2. Настройка сервера
3. Как работает Callback API и keyboard
4. Работа с библиотекой
5. Полный код бота
6. Поехали!
7. FAQ

Создание и настройка сообщества

После создания сообщества в ВК проследуйте по этому пути:
«Управление сообществом» →«Сообщения» и включите диалоги сообщества. Теперь в подменю «Настройки для бота» включите «Возможности ботов» и кнопку «Начать».

Писать будем используя Сallback api(отправляет каждое действие в сообществе по отдельности на сервер). Поэтому его тоже следует настроить. Переходим в
«Управление сообществом» →»Работа с API». Для работы бота нужно зарегистрировать ключ доступа. Нажимаете «Создать ключ» и выбираете необходимые права доступа, для этого бота нужны только права на сообщения. Подтверждаем номер телефона и сохраняем куда нибудь ключ доступа. Теперь переходим во вкладку Callback API. Ставим свое название сервера и выбираем последнюю версию API(на данный момент она 5.80, и именно с ней ниже представленный бот будет работать 100%) . Во вкладке «Типы запросов» выбираем только входящие сообщения.

Настройка сервера

Теперь вам понадобится сервер для хостинга своего бота. Вы можете использовать бесплатные хостинги, например 000webhost.

Если вы будете использовать дешевые/бесплатные хостинги, то вероятнее всего на них будет отключен cURL(вы не сможете отправлять ботом медиа файлы, только текст), и его нельзя включить. У 000webhost все с этим нормально, можете использовать . Если у вас свой сервер или хороший купленный, то вам надо подключить cURL для полноценной работы бота из нашего примера.

Как работает Callback API и keyboard

Проведу краткий экскурс как все работает. Сallback API отсылает на ваш сервер любое событие, которое происходит в группе виде JSON. Полный список событий можно посмотреть во вкладке «Сallback API» → «Типы событий». Вот так выглядит JSON запрос когда пользователь отправляет сообщение, в данном случае он нажал на кнопку:

{"type":"message_new","object":{"date":1529668584,"from_id":89846036,"id":1522,"out":1,"peer_id":89846036,"text":"Золотая рыбка","conversation_message_id":305,"fwd_messages":[],"important":false,"random_id":0,"attachments":[],"payload":"{\"animals\":\"Goldfish\"}","is_hidden":false},"group_id":101461081}

Тут есть несколько интересных полей, которые можно обработать: id пользователя, текст сообщения(text), полезная нагрузка кнопки(payload).

Отправка сообщений пользователю происходит с помощью метода messages.send. Если вы отправляете клавиатуру, то после всех стандартных параметров вы добавляете параметр keyboard, который содержит json кнопок, вот как он выглядит:

keyboard: {
   "one_time": false,
   "buttons": [
     [{
       "action": {
         "type": "text",
         "payload": "{\"button\": \"1\"}",
         "label": "Red"
       },
       "color": "negative"
     },
    {
       "action": {
         "type": "text",
         "payload": "{\"button\": \"2\"}",
         "label": "Green"
       },
       "color": "positive"
     }]

Работа с библиотекой

Для работы бота мы используем самописную библиотеку на PHP. Здесь (Если ссылка не работает, то вот архив)вы можете найти документацию к библиотеке и скачать саму библиотеку. Вот короткий листинг готовых функций для написания бота, подробнее ищите по ссылке выше. Если вы хотите узнавать об изменениях в библиотеке, то напишите хотя бы одно сообщение нашему боту в ВК, через него мы будет вас оповещать об изменениях.

$vk = new vk_api(vk_key, version_api) — инициализация бота. Параметры: ключ сообщества(vk_key), версия API(version_api).

sendMessage(id, text) — функция отправки сообщений юзеру. Параметры: id пользователя(id), текст сообщения(text).

sendImage(id, patch) — функция отправки изображений. Параметры: id пользователя(id), путь до изображения(patch).

sendButton(id, text, buttons, one_time) — функция отправки сообщения с кнопками. Параметры: id пользователя(id), текст сообщения(не может быть пустым)(text), массив с кнопками(buttons), не обязательный параметр one_time, по дефолту false, если поставить true, то после нажатия на любую кнопку клавиатура скроется.

request(method, array_arguments) — универсальная функция работы с методами. Параметры: method — название метода из официального api, array_arguments — массив параметров.

sendOK() — Бета функция. Используется вместо echo «ok», помогает в тех случаях, когда время работы скрипта долгое, и бот начинает повторять сообщения по несколько раз.
ВАЖНО: есть использовать эту функцию, то у вас не будет отображаться вывод ошибок. Во время дебага заменяйте на echo «ok»

Полный код бота на PHP

Теперь перейдем собственно к коду, где прокомментирована почти каждая строка.
Данный код поддерживается на PHP 5.6+
В блоке CONFIG укажите свой ключ доступа сообщества, ключ для подтверждения сервера а так же выбранную вами версию API.

<?php
include "vk_api.php"; //Подключаем библиотеку для работы с api vk

//**********CONFIG**************
const VK_KEY = "your_key"; //тот самый длинный ключ доступа сообщества
const ACCESS_KEY = "your_key"; //например c40b9566, введите свой
const VERSION = "5.80"; //ваша версия используемого api
//******************************

const BTN_FISH =  [["animals" => 'Fish'], "А какие бывают?", "blue"]; //Код кнопки 'Fish'
const BTN_BACK =  [["command" => 'start'], "<< Назад", "red"]; // Код кнопки '<< Назад'
const BTN_SALMON = [["animals" => 'Pink_salmon'], "Горбуша", "white"]; // Код кнопки 'Горбуша'
const BTN_GOLDFISH = [["animals" => 'Goldfish'], "Золотая рыбка", "blue"]; // Код кнопки 'Золотая рыбка'
const BTN_PLOTVA = [["animals" => 'Plotva'], "Плотва", "green"]; // Код кнопки 'Плотва'

$vk = new vk_api(VK_KEY, VERSION); // создание экземпляра класса работы с api, принимает ключ и версию api
$data = json_decode(file_get_contents('php://input')); //Получает и декодирует JSON пришедший из ВК

if ($data->type == 'confirmation') { //Если vk запрашивает ключ
  exit(ACCESS_KEY); //Завершаем скрипт отправкой ключа
}

$vk->sendOK(); //Говорим vk, что мы приняли callback

if (isset($data->type) and $data->type == 'message_new') { //Проверяем, если это сообщение от пользователя
  $id = $data->object->from_id; //Получаем id пользователя, который написал сообщение
  $message = $data->object->text;

  if (isset($data->object->peer_id))
        $peer_id = $data->object->peer_id; // Получаем peer_id чата, откуда прилитело сообщение
    else
        $peer_id = $id;
  
  if (isset($data->object->payload)){  //получаем payload
        	$payload = json_decode($data->object->payload, True);
   	} else {
      		$payload = null;
   	}
  
  if (isset($payload['command']) or mb_strtolower($message) == 'начать') { //Если нажата кнопка начать или << назад
    $vk->sendButton($peer_id, 'Хочешь посмотреть на рыбок?', [[BTN_FISH]]); //Отправляем кнопку пользователю
  } else {
    if ($payload != null) { // если payload существует
      switch ($payload['animals']) { //Смотрим что в payload кнопках
        case 'Fish': //Если это Fish
          $vk->sendButton($peer_id, 'Вот такие, выбирай', [ //Отправляем кнопки пользователю
            [BTN_SALMON, BTN_GOLDFISH, BTN_PLOTVA],
            [BTN_BACK]
          ]);
          break;
        case 'Pink_salmon': //Если это Горбуша
          $vk->sendMessage($peer_id, "Держи свою горбушу!"); //отправляем сообщение
          $vk->sendImage($peer_id, "img/pink_salmon.jpg"); //отправляем картинку
          break;
        case 'Goldfish': //Если это Золотая рыбка
          $vk->sendMessage($peer_id, "Она исполнит твои желания...");
          $vk->sendImage($peer_id, "img/goldfish.jpg");
          break;
        case 'Plotva': //Если это Плотва
          $vk->sendMessage($peer_id, "Ой, похоже картинку перепутали)");
          $vk->sendImage($peer_id, "img/plotva.jpg");
          break;
        default:
          break;
      }
    }
  }
}
?>

Теперь вы знаете как работает код, и можете подстроить его под себя.

Стартуем!

Заливайте свой скрипт и библиотеку на сервер. Теперь заходим в настройках во вкладку Callback API, вписываем в поле адреса путь до своего скрипта и жмем подтвердить. Если вы все сделали правильно, то рядом с адресом появится зеленая галочка.

FAQ:

Вопрос: Вообще ничего не работает!
Ответ: Значит где-то накосячили. Перечитайте еще раз внимательно статью, и проверьте, все ли вы сделали. Любой шаг влево может привести к ошибке…

Вопрос: У меня все работает, но не отправляются картинки.
Ответ: Проверьте, добавили ли вы папку img с изобажениями. Так же, возможно вы используете сервер, где не поддерживается cURL.

Вопрос: Я изменил версию на 5.78 или любую другую. У меня ничего не работает.
Ответ: Используйте другие версии api кроме 5.80 на свой страх и риск. Например на версии 5.78 от ВК приходят другие названия переменных(например вместо object->text идет object->body), поэтому скрипт крашится. Все изменения api ищите здесь.

Вопрос: Бот дублирует сообщения.
Ответ: Ваш скрипт долго выполняется. Проверьте что вы используете функцию sendOK. Если все же проблема не решена, то это может быть косяк функции, она еще находится тестировании.

Вопрос: Не появляется кнопка Начать.
Ответ: Недавно мы тоже столкнулись с такой проблемой. После разговора с поддержкой было отмечено, что это баг ВК, который присутствует в некоторых группах. Если у вас именно эта проблема, то уберите приветственное сообщение в настройках группы, и кнопка появится. Если кнопки еще нет, то вы забыли включить ее в настройках 🙂

Вопрос: Как отправить чисто кнопки, без сообщения?
Ответ: API предусматривает отправку кнопок только вместе с каким то сообщением, без него нельзя.

Вопрос: Как мне добавить свой функционал? У меня плохо с программированием…
Ответ: Мы делаем ботов на заказ от 500р, если хотите, то пишите насчет этого в группу ВК.

Остались еще какие-то вопросы? Пишите их нам в группу, обязательно поможем, если связано с примером из статьи или библиотекой.

Ну вот и все, у вас теперь тоже есть бот с клавиатурой 🙂

Делитесь этими знаниями с вашими друзьями и не забывайте подписаться на нашу группу ВК, там будет еще много интересного!