API MAX: Справочник для разработчиков чат-ботов

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

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

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

Методы

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 — сервис недоступен

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

Когда вы настраиваете получение обновлений о действиях в чат-боте, используйте:

• Long Polling — для разработки и тестирования
• только Webhook — для production-окружения

Для стабильной работы сервисов MAX убедитесь, что максимальное количество запросов в секунду на platform-api.max.ru — 30 rps

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

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

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

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

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

Типы кнопок

• callback — сервер MAX отправляет событие с типом message_callback (через Webhook или Long polling)

Обратите внимание: для отправки вебхуков поддерживается только протокол HTTPS, включая самоподписанные сертификаты. HTTP не поддерживается

• link — позволяет открыть ссылку в новой вкладке
• request_contact — запрашивает у пользователя его контакт и номер телефона
• request_geo_location — запрашивает у пользователя его местоположение
• open_app — открывает мини-приложение
• message — отправляет боту текстовое сообщение
• clipboard — копирует текст, указанный в свойстве payload, в буфер обмена

Кнопка clipboard

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

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

JSON

Скопировать

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

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

Чтобы добавить кнопки, отправьте сообщение с InlineKeyboardAttachment

JSON

Скопировать

{
"text": "It is message with inline keyboard",
"attachments": [
{
"type": "inline_keyboard",
"payload": {
"buttons": [
[
{
"type": "callback", // Тип кнопки
"text": "Press me!", // Текст кнопки
"payload": "button1 pressed" // Описание действия
}
]
]
}
}
]
}

Форматирование текста

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

Markdown

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

HTML

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

 или 

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