Библиотека MAX Bridge даёт мини-приложению доступ к системным возможностям — от сканера QR-кодов до запроса телефона пользователя. У чат-бота для той же цели есть своя кнопка, разобранная в материале о клавиатуре бота. Метод мини-приложения устроен иначе: другое окно запроса, другой набор полей в ответе и, самое важное, — собственная формула проверки хеша со своей ловушкой.
Модальное окно вместо кнопки в чате
В документации MAX Bridge (dev.max.ru) раздел «Запрос номера телефона» сразу оговаривает: у чат-бота для той же задачи есть своя кнопка, и её работа описана на отдельной странице:
Обратите внимание: отправка номера телефона в чат-бот описана на странице API.
dev.max.ru, раздел «Запрос номера телефона»Для мини-приложения способ другой — не сообщение с кнопкой, а вызов метода библиотеки, который открывает системное окно поверх интерфейса:
Запрашивает номер телефона пользователя в модальном окне нативного клиента MAX.
window.WebApp.requestContact(), dev.max.ruТо есть пользователь не нажимает кнопку в переписке, а видит нативный диалог поверх мини-приложения — и решает в нём, делиться номером или нет.
Что возвращает requestContact() — и для чего это можно использовать
Если пользователь соглашается, промис метода отдаёт три поля:
Promise<{ phone: string; authDate: string; hash: string }>, где authDate — timestamp создания hash.
window.WebApp.requestContact(), dev.max.ruДокументация сразу ограничивает, где эти данные разрешено применять — рамка та же, что и у номера, полученного через кнопку бота, но сформулирована для мини-приложения отдельно:
Данные пользователя (включая номер телефона), полученные с помощью метода requestContact(), могут использоваться только для взаимодействия с текущим мини-приложением. Например, их можно применять для регистрации в программе лояльности, проверки статуса заказа, идентификации пользователя.
dev.max.ru, раздел «Запрос номера телефона»Значит, даже два мини-приложения одного разработчика не могут просто переиспользовать один и тот же подтверждённый номер: каждое обязано запросить его отдельно.
Формула хеша и её ловушка с «+»
Чтобы убедиться, что номер настоящий, документация предлагает сверить два значения:
Значение поля hash, полученное от клиента. Значение функции HMAC_SHA256(authDate + phone + userId, botToken), где: HMAC_SHA256 — стандартная для большинства языков программирования криптографическая функция.
dev.max.ru, раздел «Запрос номера телефона»Порядок полей внутри строки для хеширования — не произвольный, документация прямо описывает, как её собрать:
authDate + phone + userId — параметры в алфавитном порядке, используемые для вычисления хеша: сформируйте строку, объединив пары key=value с разделителем \n.
Ключ для HMAC — не общий секрет приложения, а токен конкретного бота:
botToken — токен бота, чьё мини-приложение запрашивает номер телефона пользователя.
dev.max.ru, раздел «Запрос номера телефона»Если оба значения совпали — номер настоящий:
Если значения совпадают, это подтверждает, что пользователь поделился номером телефона, привязанным к его аккаунту в MAX.
dev.max.ru, раздел «Запрос номера телефона»А дальше — деталь, из-за которой чужой код проверки, скопированный без внимания к мелкому шрифту, будет молча выдавать неверный хеш. Номер в поле phone приходит в международном формате, но при подсчёте хеша знак плюса нужно убрать:
При вычислении хеша значение phone не должно содержать +: вместо +7********** используется 7**********.
dev.max.ru, раздел «Запрос номера телефона»То есть значение, которое разработчик получил в phone, и значение, которое нужно подставить в строку для хеша, — не одна и та же строка. Разница в один символ, а результат HMAC при этом расходится полностью: хеш — это не сумма цифр, а криптографическая функция, для которой «+79991234567» и «79991234567» — два совершенно разных входа.
Если пользователь отказался поделиться номером
Документация отдельно описывает, что приходит вместо номера, если пользователь закрыл окно или запрос не выполнился:
Если пользователь отказывается поделиться номером телефона или запрос завершился ошибкой, возвращает: { "error": { "code": "client.request_phone.<reason>" } }.
dev.max.ru, раздел «Запрос номера телефона»Формат кода ошибки описывает два разных сценария под одним префиксом:
client.request_phone.user_refused_provide_phone_number(код 01) — пользователь отказался предоставить номер телефонаclient.request_phone.request_error(код 02) — ошибка при выполнении запроса: нет сети или не ответил backend
Разница практическая: первую ошибку решать нечем — это осознанный выбор пользователя, а вторую имеет смысл дать повторить кнопкой «Попробовать снова».
Частые вопросы
Чем requestContact() в MAX Bridge отличается от кнопки request_contact у бота?
Кнопка бота отправляет номер сообщением в чат, а requestContact() мини-приложения открывает модальное окно нативного клиента и возвращает результат промисом — с собственным набором полей и собственной формулой проверки хеша.
Как проверить, что номер из requestContact() настоящий?
Сравнить присланный hash со значением HMAC_SHA256(authDate + phone + userId, botToken), где параметры соединены в строку в алфавитном порядке через key=value с разделителем \n.
Почему хеш номера телефона в MAX Bridge не совпадает?
Частая причина — символ «+» в номере: при вычислении хеша phone нужно передавать без плюса, вместо +7********** использовать 7**********.
Что возвращает requestContact(), если пользователь отказался?
Ошибку с кодом client.request_phone и одной из двух причин: user_refused_provide_phone_number (отказ) или request_error (сбой запроса).
Развиваете канал или бота в MAX?
Добавьте его в каталог MaxOfficial — читатели находят каналы через поиск и подборки, а статистика копится автоматически.
Добавить канал в каталог
