Клавиатура бота в MAX: пульт на 210 кнопок под сообщением

Кнопки вместо сообщений: что такое клавиатура бота

Обзор API MAX объясняет назначение клавиатуры одной фразой:

То есть речь не о клавиатуре телефона и не о наборе текста. Клавиатура бота — это панель кнопок, закреплённая под его сообщением: пользователь не печатает ответ, а нажимает готовый вариант. Страница библиотеки JavaScript описывает ту же конструкцию бытовым сравнением:

У пульта есть обязательные правила вёрстки, и документация перечисляет их до всякого кода: текст на кнопке выравнивается по центру и обрезается, если выходит за границы; кнопки в одной строке всегда одинаковой ширины; ряд кнопок растягивается на всю ширину клавиатуры, а высота у кнопок по умолчанию одна и та же. Владельцу бота отсюда следует практичный вывод: длинные подписи на кнопках жить не будут — их срежет сама вёрстка. Как бот вообще появляется на свет и где живут его настройки, мы разбирали в руководстве о создании ботов в MAX.

Арифметика пульта: тридцать рядов по семь кнопок

Потолок у клавиатуры задан числами, и числа эти щедрые:

Арифметика сходится ровно: тридцать рядов по семь дают заявленный потолок. Но у него есть оговорка, которую легко пропустить: до семи кнопок в ряд можно ставить не всегда. Для четырёх типов — link, open_app, request_geo_location и request_contact — лимит ряда жёстче — до трёх кнопок. Если собрать клавиатуру целиком из таких кнопок, вместо 210 позиций останется девяносто.

Ограничен и размер того, что кнопка несёт внутри: для кнопки-ссылки максимальная длина адреса — 2048 символов. А на случай, когда рядов слишком много, у библиотеки готов ответ:

Иными словами, к пульту на две сотни кнопок прилагается прокрутка: платформа заранее допускает, что целиком он на экран не поместится.

Семь типов кнопок в API, шесть — в библиотеке

Обзор API перечисляет семь типов кнопок. Вот весь набор: callback — отправляет серверу событие о нажатии; link — открывает ссылку в новой вкладке; request_contact — запрашивает у пользователя его контакт и номер телефона; request_geo_location — просит поделиться местоположением; open_app — открывает мини-приложение; message — отправляет боту текстовое сообщение; clipboard — копирует текст в буфер обмена.

А теперь замер, ради которого стоило читать оба раздела подряд. Страница библиотеки JavaScript в разделе «Типы кнопок» описывает шесть классов: CallbackButton, LinkButton, RequestContactButton, RequestGeoLocationButton, OpenAppButton и MessageButton. Слово clipboard на этой странице не встречается ни разу — мы проверили поиском по всему её тексту. Седьмой тип кнопки существует только на этаже «голого» API: собрать такую кнопку библиотечным конструктором по документации нельзя, только руками в JSON.

Когда именно седьмой тип появился, официальная история изменений не сообщает: в журнале API MAX записи о clipboard нет. Сам журнал и то, что платформа открыла API для разработчиков, мы разбирали в материале об открытии API MAX.

Кнопка clipboard: текст сразу в буфер обмена

Седьмой тип заслуживает отдельного разбора — это единственная кнопка, которая ничего не отправляет и никуда не ведёт. При нажатии текст из её свойства payload копируется в буфер обмена устройства. Документация прямо подсказывает, что туда класть:

Сценарий очевиден: бот присылает код или номер отправления, пользователь забирает его одним нажатием — без выделения текста пальцем и без ошибок ручного набора. Забавная деталь: пользовательская справка MAX не употребляет слово «буфер» ни в одной из своих статей — сама возможность описана только в документации для разработчиков.

Кнопка с контактом: поле hash как замена авторизации

Самая нагруженная кнопка пульта — request_contact. По нажатию пользователь отправляет боту свой контакт и номер телефона, привязанный к аккаунту. Вместе с контактом в сообщение приходит поле hash — криптографическая подпись: бот считает HMAC-SHA256(access_token, vcf_info) и сравнивает с присланным значением. Совпало — значит, пользователь поделился номером, который привязан к его аккаунту. Документация оценивает приём без ложной скромности: полученный так номер

Важна и обратная сторона. Если пользователь отправит номер боту любым другим способом — например, решит переслать из телефонной книги, — сообщение не будет содержать поля hash, и подтвердить принадлежность номера не получится. Проверяемым контакт делает именно кнопка: тот же самый номер, присланный не через неё, для бота остаётся словом без подписи. Документация при этом очерчивает границы: данные, полученные кнопкой, можно использовать только для взаимодействия с текущим ботом — программа лояльности, статус заказа, идентификация внутри сервиса.

Кнопки едут только внутри сообщения

Отдельного метода «отправить клавиатуру» в API нет. Мы обошли весь раздел «Методы API» — в нём двадцать девять страниц — и картина такая: вложение inline_keyboard упоминают три страницы (отправка сообщений, их редактирование и ответ на callback), а слово «клавиатура» встречается ровно на одной — в отправке сообщений, и то ссылкой на обзор. Кнопки всегда приезжают как вложение: в теле запроса POST /messages передаётся объект attachments с типом inline_keyboard и массивом кнопок. В списке типов вложений на той же странице клавиатура записана буднично: «сообщение или пост с кнопкой» — в одном перечне со стикерами и файлами.

Зато у кнопочных сообщений есть привилегия, которой нет у обычных. Страница редактирования сообщений оговаривает особый режим для диалогов с ботом:

Обычное сообщение в диалоге бот может править только первую неделю после отправки — дальше оно застывает. Сообщение с клавиатурой можно перерисовывать бесконечно: старое меню годичной давности остаётся живым пультом, и бот может менять на нём кнопки хоть каждый день. О том, как бот вообще узнаёт о нажатиях — и почему без подписки на события он молчит, — мы писали в разборе о подписке бота на события.

Справка молчит: ноль статей о клавиатуре

Теперь этаж пользователя. В справке MAX сто девяносто две статьи; слова «клавиатура» нет ни в одном заголовке и ни в одном тексте — ноль употреблений на весь корпус. Кнопки как элемент интерфейса справка, конечно, упоминает — в десятках статей, — но всё это кнопки приложения: позвонить, настроить, удалить. Кнопочный пульт бота, его типы и лимиты для пользователя не описаны нигде: человек нажимает на «Поделиться контактом», не имея ни одной справочной страницы о том, что это за механика и что она отправит.

Для владельца бота это означает простую вещь: объяснять пульт придётся самому боту. Подпись на кнопке — единственная документация, которую увидит пользователь, и тем важнее, что вёрстка её обрежет, если текст выйдет за границы кнопки. Короткие глаголы работают лучше описаний. А если бот живёт в групповом чате, помните: там свои правила входа и прав — мы разбирали их в материале о групповых чатах в MAX.

Частые вопросы