Обзор

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

API (Application Programming Interface) — это посредник между разработчиком приложений и средой, с которой это приложение должно взаимодействовать. API упрощает написание кода за счёт набора готовых классов, функций или структур для работы с данными

API MAX — это интерфейс, который позволяет ботам взаимодействовать с платформой и получать необходимые данные с помощью HTTPS-запросов к серверу. В этом разделе расскажем, как подготовиться к использованию API MAX

Методы

HTTPS-запросы на домен platform-api.max.ru вызывают методы — условные команды, которые соответствуют той или иной операции с базой данных. Например, получение, запись или удаление какой-либо информации
Параметры запроса должны содержать HTTP-метод, соответствующий необходимой операции:

GET — получить ресурсы
POST — создать ресурсы (например, отправить новые сообщения)
PUT — редактировать ресурсы
DELETE — удалить ресурсы
PATCH — исправить ресурсы

В зависимости от конкретного метода, параметры запроса будут отображаться в пути, URL-параметрах или теле запроса

Примеры запросов:

GET https://platform-api.max.ru/messages/{messageId} — получить сообщения
POST https://platform-api.max.ru/messages — отправить сообщения
PATCH https://platform-api.max.ru/chats/{chatId} — изменить информацию о чате
В ответ сервер вернёт JSON-объект с запрошенными данными или сообщение об ошибке, если что-то пойдёт не так

JSON — это формат записи данных в виде пар <ИМЯ_СВОЙСТВА>: <ЗНАЧЕНИЕ>. Прочитайте об особенностях формата JSON, если вы ещё не работали с ним
Пример ответа на запрос к методу GET /me:

JSON

Скопировать

{
	"user_id": 1,
	"name": "My Bot",
	"username": "my_bot",
	"is_bot": true,
	"last_activity_time": 1737500130100
}

Также, помимо JSON, сервер вернёт трёхзначный HTTP-код, информирующий об успешном выполнении запроса или ошибке

HTTP-коды ответов

200 — успешный запрос
400 — недействительный запрос
401 — ошибка аутентификации
404 — ресурс не найден
405 — метод не допускается
429 — превышено количество запросов
503 — сервис недоступен

Клавиатура для чат-бота

Клавиатура позволяет отправлять боту запросы кнопками, а не сообщениями. Чтобы клавиатура была удобной для пользователей, рекомендуем заранее продумать её наполнение и учитывать обязательные параметры:

Текст на кнопке выравнивается по центру и обрезается, если выходит за её границы
Кнопки в одной строке всегда одинаковой ширины
Ширина каждого ряда кнопок равна ширине клавиатуры
Высота у всех кнопок по умолчанию одинаковая

Вы можете подключить к чат-боту в MAX inline-клавиатуру. Она позволяет разместить под сообщением бота до 210 кнопок, сгруппированных в 30 рядов — до 7 кнопок в каждом (до 3, если это кнопки типа link, open_app, request_geo_location или request_contact)

Для кнопки с видом link максимальный размер ссылки составляет 2048 символов

Типы кнопок

callback — сервер MAX отправляет событие с типом message_callback, если подписаны на обновления через Webhook или Long Polling. Подробнее о получении событий в боте
Подробнее о рекомендациях и ограничениях при работе с Webhook и Long Polling — в разделе «Рекомендации по работе с API»
link — позволяет открыть ссылку в новой вкладке
request_contact — запрашивает у пользователя его контакт и номер телефона
request_geo_location — запрашивает у пользователя его местоположение
open_app — открывает мини-приложение
message — отправляет боту текстовое сообщение
clipboard — копирует текст, указанный в свойстве payload, в буфер обмена

Как добавить кнопки

Чтобы добавить кнопки, отправьте сообщение POST-методом /messages

В теле запроса передайте объект attachments с типом inline_keyboard и массивом кнопок payload.buttons. Для каждой кнопки обязательно укажите её текст в параметре text. Также в зависимости от типа кнопки могут потребоваться и другие параметры

Одна кнопка

Несколько кнопок в столбце

Несколько кнопок в строке

JSON

Скопировать

{
  "text": "Это сообщение с кнопкой-ссылкой",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "link",
              "text": "Откройте сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
}

Кнопка request_contact

При нажатии на кнопку с типом request_contact пользователь отправит в чат-бот свой контакт и номер телефона, привязанный к аккаунту в МАКС

Сообщение с контактом содержит поле hash — оно позволяет проверить, что пользователь поделился номером телефона, совпадающим с его номером в МАКС. Благодаря этому получение номера пользователя через сообщение с типом request_contact можно использовать, например, как альтернативу авторизации

Обратите внимание: отправка номера телефона в мини-приложение описана на странице MAX Bridge

Другие способы отправки контакта в чат-бот

Если отправить номер телефона в диалог с чат-ботом другим способом, например, поделиться через 📎 в интерфейсе МАКС или переслать из телефонной книги, сообщение не будет содержать поля hash. В этом случае подтвердить, что номер принадлежит пользователю, не получится

Возможный сценарий взаимодействия пользователя и чат-бота

Чат-бот отправляет пользователю запрос POST /messages с кнопкой типа request_contact
Пользователь получает сообщение с кликабельной кнопкой Поделиться контактом
Пользователь нажимает на кнопку, тем самым отправляя в чат-бот свой номер телефона в МАКС
Чат-бот получает номер телефона пользователя из сообщения — запрос GET /messages
Чат-бот проверяет, что полученный в сообщении номер телефона совпадает с номером, привязанным к аккаунту пользователя в МАКС. Для этого сравнивает:
- Значение поля hash, полученное в сообщении в массиве attachments.payload:
  
  JSON
  Скопировать
  "attachments": [ { "payload": { "vcf_info": "string", // Строковая информация о пользователе "max_info": { // Информация о пользователе }, "hash": "string" // Хеш информации о пользователе из поля `vcf_info` }, "type": "contact" } ]
- Значение функции HMAC-SHA256(access_token, vcf_info), где:
  - HMAC-SHA256 — стандартная для большинства языков программирования криптографическая функция
  - access_token — токен чат-бота
  - vcf_info — информация о контакте в формате:
  Код
  Скопировать
  "vcf_info": "BEGIN:VCARD\r\nVERSION:3.0\r\nPRODID:ez-vcard 0.10.3\r\nTEL;TYPE=cell:79990000000\r\nFN:Ivan Ivanov\r\nEND:VCARD\r\n"
Если значения совпадают, это подтверждает, что пользователь поделился номером телефона, привязанным к его аккаунту в МАКС

Обратите внимание: перед хешированием необходимо преобразовать символы \r\n поля vcf_info в реальные переносы строк

Кнопка clipboard

При нажатии на кнопку с типом clipboard текст, указанный в свойстве payload, копируется в буфер обмена

В свойстве payload можно передать любой текст, например промокод, трек-номер, платёжные реквизиты

JSON

Скопировать

{
  "type": "clipboard", // Тип кнопки
  "text": "Скопировать", // Текст кнопки
  "payload": "123456" // Текст, который будет скопирован
}

Форматирование текста в сообщениях

Текст сообщения в чат-боте можно улучшить с помощью базового форматирования. Для этого вы можете использовать либо Markdown, либо HTML

Markdown

Чтобы включить разбор Markdown, установите свойство format в NewMessageBody на значение markdown

Markdown	Отображение
курсив	empasized или _empasized_
жирный	strong или __strong__
~~зачёркнутый~~	~~strikethough~~
подчёркнутый	++underline++
`моноширинный`	`code` (переводы строк внутри этого блока обрабатываются как пробелы)
ссылка	[Inline URL](https://dev.max.ru/)
@упоминание пользователя	"text": "[Имя Фамилия](max://user/user_id)", "format": "markdown" Вместо `User mention` указывайте полное имя пользователя из профиля в MAX, в том числе фамилию. Если фамилия отсутствует — только имя
заголовок	# заголовок
	> Цитата

HTML

Чтобы включить разбор HTML, установите свойство format в NewMessageBody на значение html

Markdown	Отображение
курсив	<i> или <em>
жирный	<b> или <strong>
~~зачёркнутый~~	<del> или <s>
подчёркнутый	<ins> или <u>
`моноширинный`	<pre> или <code>
ссылка	<a href="https://dev.max.ru">Docs</a>
@упоминание пользователя	"text": "<a href=\"max://user/user_id\">Имя Фамилия</a>", "format": "html" Вместо `User mention` указывайте полное имя пользователя из профиля в MAX, в том числе фамилию. Если фамилия отсутствует — только имя
выделенный	<mark>выделенный</mark>
заголовок	<h1>, <h2>, <h3>, <h4>, <h1>, <h1> — теги всех уровней отображаются одинаково
	<blockquote> Цитата </blockquote>

Если у вас возникли вопросы, посмотрите раздел с ответами

Обзор

Методы

HTTP-коды ответов

Рекомендации по работе с API

Клавиатура для чат-бота

Типы кнопок

Как добавить кнопки

Кнопка request_contact

Кнопка clipboard

Форматирование текста в сообщениях

Markdown

заголовок

HTML

заголовок