Обзор

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

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

Методы

Скачать спецификацию swagger.json

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

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

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

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

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

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

Если вы отправляете запросы на домен botapi.max.ru, перейдите на новый домен platform-api.max.ru до 1 октября. Это важно для стабильной работы ботов

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)

Виды кнопок для чат-бота:

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

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

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

Чтобы добавить кнопки, отправьте сообщение с 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

Markdown	Отображение
курсив	empasized или _empasized_
жирный	strong или __strong__
~~зачёркнутый~~	~~strikethough~~
подчёркнутый	++underline++
`моноширинный`	`code` (переводы строк внутри этого блока обрабатываются как пробелы)
ссылка	[Inline URL](https://dev.max.ru/)
@упоминание пользователя	[User mention](max://max.ru/%user_id%) (ссылка откроется, если у вас установлен 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>
@упоминание пользователя	<a href="max://max.ru/%user_id%">User mention</a> (ссылка откроется, если у вас установлен MAX)

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