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

Обзор API MAX

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

[!IMPORTANT] Аутентификация: Передача токена через query-параметры больше не поддерживается. Используйте заголовок Authorization: <token> во всех ваших запросах.

Основные методы и запросы

Все запросы отправляются на домен platform-api.max.ru. Мы поддерживаем стандартные типы HTTP-методов:

Метод	Описание
GET	Получение ресурсов (информация о боте, чате, сообщениях)
POST	Создание новых ресурсов (отправка сообщений, создание кнопок)
PUT	Полное редактирование существующих ресурсов
PATCH	Частичное исправление или обновление ресурсов
DELETE	Удаление сообщений или других объектов

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

GET https://platform-api.max.ru/me — получить информацию о своём боте.
POST https://platform-api.max.ru/messages — отправить сообщение пользователю.

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

MAX поддерживает два формата разметки текста в сообщениях: Markdown и HTML. Выбор формата осуществляется через свойство format в теле сообщения.

Markdown

Для включения используйте "format": "markdown".

**жирный** или __жирный__
*курсив* или _курсив_
~~зачёркнутый~~
[Текст ссылки](https://max.ru)

HTML

Для включения используйте "format": "html". Поддерживаются теги: <b>, <i>, <s>, <u>, <code>, <a>.

Интерактивные клавиатуры

Клавиатуры (Inline Keyboards) позволяют пользователям взаимодействовать с ботом нажатием кнопок вместо ввода текста.

Типы кнопок:

callback: Отправляет событие боту без видимого сообщения в чате.
link: Открывает внешнюю ссылку.
open_app: Запускает мини-приложение.
request_contact: Запрашивает номер телефона (только в диалогах).
request_geo_location: Запрашивает текущую геопозицию.
clipboard: Копирует заданный текст (промокод, ID) в буфер обмена.

Коды ответов сервера

Код	Значение	Описание
200	OK	Успешное выполнение операции
400	Bad Request	Ошибка в параметрах запроса
401	Unauthorized	Неверный или просроченный токен
403	Forbidden	Нет доступа к данному ресурсу
429	Too Many Requests	Превышен лимит запросов (лимит: 30 RPS)
503	Service Unavailable	Временные технические работы на сервере