Обзор

Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на домен platform-api2.max.ru вместо platform-api.max.ru. Также убедитесь, что добавили сертификат Минцифры в список доверенных

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

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

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

Методы

Начиная с июня 2026 метод GET /chats больше не поддерживается. Вместо него для получения списка всех групповых чатов и каналов, в которые добавлен бот, используйте POST /subscriptions. Подробнее – на странице «Получение списка всех групповых чатов и каналов»

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

Параметры запроса должны содержать HTTP-метод, соответствующий необходимой операции:

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

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

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

GET https://platform-api2.max.ru/messages/{messageId} — получить сообщения
POST https://platform-api2.max.ru/messages — отправить сообщения
PATCH https://platform-api2.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 — сервис недоступен

Тип объекта	Как получить chat_id
Чат или канал	Только через подписку: POST `/subscriptions` или GET `/updates` `chat_id` придёт в объекте Update на выбранные вами события – например, `bot_added` или `bot_started`
Мини-приложение	Либо через подписку (см. описание для чата и канала выше), либо на клиенте через window.WebApp.initData библиотеки MAX Bridge

Команды для чат-бота

Добавить команды для чат-бота можно с помощью метода PATCH /me/commands

Настроить логику сценариев работы чат-бота так, чтобы он выполнял необходимые вам действия в ответ на команды или слова, отправленные в чат, можно с помощью библиотек JavaScript и Golang. Примеры использования библиотек для работы с чат-ботом читайте в разделе «Примеры создания ботов»

Вы можете добавить команды в кнопки с типом callback, которые чат-бот будет присылась сообщением

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

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

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

Вы можете подключить к чат-боту в 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"
            }
          ]
        ]
      }
    }
  ]
}

Как добавить клавиатуру с помощью библиотек, читайте в разделе «Библиотека JavaScript»

Кнопка request_contact

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

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

Данные пользователя (включая номер телефона), полученные с помощью кнопки 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 значение markdown

Обратите внимание: в тексте комментариев не поддерживаются гиперссылки и упоминание пользователей

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

HTML

Если для форматирования текста сообщения вы хотите использовать разметку HTML, при отправке запроса на создание сообщения установите для параметра format значение html

Обратите внимание: в тексте комментариев не поддерживаются гиперссылки и упоминание пользователей

Отображение	HTML
курсив	<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>

Отправка медиафайлов

Для отправки сообщений в чаты и каналы в API используется метод POST /messages

Помимо текста сообщения могут содержать вложения, которые передаются в объекте attachments запроса POST /messages

Типы вложений

Вложения могут быть одного из типов type:

image — изображения
Доступные форматы: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC
Максимальный размер одного изображения: до 50 МБ или не более 7680 x 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 x 7600 px нельзя
video — видеофайлы
Доступные форматы: MP4, MOV, MKV, WEBM
Максимальный размер одного видео: до 250 МБ
audio — аудиофайлы
Доступные форматы: MP3, WAV, M4A и другие
Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя
file — другие медиафайлы
Максимальный размер одного файла: до 4 ГБ
Доступные форматы: TXT, DOC, PDF и другие распространённые форматы
sticker — стикеры
inline_keyboard — кнопки клавиатуры. Подробнее — в разделе о клавиатуре
Максимальное количество: 210 кнопок, сгруппированных в 30 рядов — до 7 кнопок в каждом (до 3, если это кнопки типа link, open_app, request_geo_location или request_contact)
location — геолокация
share — медиафайлы с превью

Параметр type=photo больше не поддерживается. Если вы ранее использовали type=photo — замените его на type=image

О загрузке медиафайлов

При отправке вложений с медиафайлами — image, video, audio, file, share — предварительно их нужно загрузить с помощью метода POST /uploads. В результате загрузки вы получите token, который нужен для отправки вложения в сообщении. При этом одному токену должен соответствовать один медиафайл

Для изображений в качестве альтернативы токену вы можете использовать url — прямую ссылку на изображение в интернете. Для других медиафайлов такой способ недоступен

Подробнее о загрузке медиафайлов и особенностях обработки читайте в описании POST /uploads

Примеры с видео, изображением, файлом

Видео и изображения можно отправить в комбинации друг с другом и одной кнопкой. Общее количество вложений при этом должно быть не более 12

Файл можно отправить только в комбинации с вложением с кнопками — отправка совместно с изображением или видео не поддерживается. При этом к сообщению можно прикрепить только один файл и одно вложение с кнопками

Примеры комбинаций вложений с видео, изображением и кнопкой:

6 видео, 5 изображений, 1 вложение с кнопками
12 видео
12 изображений
11 видео, 1 вложение с кнопками
11 изображений, 1 вложение с кнопками
6 видео, 6 изображений
1 файл, 1 вложение с кнопками

Примеры тела запроса при отправке сообщений с разными типами медиавложений и их комбинациями:

Видео, изображение, кнопки

Изображения (2 способа)

Два видео

Файл, кнопки

JSON

Скопировать

{
"text": "Это сообщение с видео, изображением и кнопками",
"attachments": [
  {
//вложение с видео
      {
    "type": "video",
    "payload": {
      //токен, который вернулся в ответ на запрос POST /uploads
            "token": "nJB5ncI22cjv91bDOH6vooWy3VWVhxyyD" 
    }
//вложение с изображением
  },
      {
    "type": "image",
    "payload": {
      //токен, который вернулся в при загрузке изображения по ссылке, полученной через POST /uploads
            "token": "4mtwu/jlqwJwSz5uYMcpHMCcn/5fqR0="  
    }
  },
// в сообщении с видео или изображением можно передать только одно вложение с кнопками 
   {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "callback",
              "text": "Кнопка 1",
              "payload": "Кнопка 1 нажата"
            },
            {
              "type": "callback",
              "text": "Кнопка 2",
              "payload": "Кнопка 2 нажата"
            },
            {
              "type": "callback",
              "text": "Кнопка 3",
              "payload": "Кнопка 3 нажата"
            }
          ]
        ]
      }
    }
  }
]
}

Как настроить модерацию комментариев к постам в каналах

Функциональность временно недоступна

Чтобы отслеживать новые комментарии в канале через API и отвечать на них, предварительно включите опцию комментариев. Пока эта опция отключена, бот сможет читать, редактировать и удалять только старые комментарии

С помощью API MAX вы можете:

POST /messages/{messageId}/comments — публиковать комментарии к посту
PUT /messages/{messageId}/comments — редактировать свои комментарии и те, что опубликованы от имени канала, — при наличии права администратора edit. Подробнее о правах
GET /messages/{messageId}/comments — получать все комментарии
GET /messages/{messageId}/comments/{commentId} — получить комментарий с указанным ID
DELETE /messages/{messageId}/comments — удалять комментарии. Рекомендуем заранее ознакомить подписчиков со списком стоп-слов для вашего канала

Ниже приведён один из возможных сценариев использования API MAX для комментариев в канале — вы можете придумать и реализовать свой

Как модерировать комментарии с помощью бота и API MAX

Добавьте бота в канал как участника
Назначьте бота администратором канала с правами на чтение, редактирование, публикацию и удаление постов. Это можно сделать:
- В интерфейсе мессенджера МАХ
- Через API c помощью POST /chats/{chatId}/members/admins. В объекте permissions нужно передать соответствующие значения read_all_message, edit, write, delete. Также понадобится ID канала
Готово! Теперь боту доступно чтение, редактирование и удаление всех комментариев в канале: старых и новых, своих и других участников (пользователей и ботов — исключая редактирование комментариев. Бот может редактировать свои комментарии и те, что опубликованы от имени канала)

Пример запроса

BASH

Скопировать

curl -X POST "https://platform-api2.max.ru/chats/{chatId}/members/admins" \
-H "Authorization: {access_token}" \
-H "Content-Type: application/json" \
-d '{
"admins": [
  {
    "user_id": "{bot_id}",
    "permissions": [
      "read_all_messages",
      "edit",
      "write",
      "delete"
    ],
    "alias": "администраторам"
  }
]
}'

Если потребуется, позже вы сможете изменить права бота или удалить его из канала одним из способов, представленных в этом раскрывающемся списке

В интерфейсе МАХ — доступно только администратору, который добавил бота в канал, и владельцу чата
Через API MAX с помощью POST /chats/{chatId}/members/admins для изменения прав и DELETE /chats/{chatId}/members/me — для удаления бота. Для это понадобится токен авторизации этого бота access_tokenи ID канала

Подпишитесь на обновления о событиях с ботом через Webhook с помощью POST /subscriptions. В запросе в объекте update_types укажите список событий, которые вы хотите получать. Для работы с комментариями это:
- message_created — новый комментарий
- message_removed — комментарий удалён
- message_edited — комментарий изменён
После подписки события будут приходить на указанный в запросе Webhook-endpoint. События приходят в виде HTTPS POST-запросов с объектом Update, который содержит идентификатор изменённого комментария в поле message.recipient.post_id

Когда кто-нибудь из подписчиков канала прокомментирует пост, через Webhook вам вернётся Update с событием message_created и текстом комментария в поле body.text.

Пример запроса

BASH

Скопировать

curl -X POST "https://platform-api2.max.ru/subscriptions" \
-H "Authorization: {access_token}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhook",
"update_types": ["message_created", "message_removed","message_edited"],
"secret": "your_secret"
}'

Проверьте, что комментарий соответствует вашим правилам модерации

Например, что в нём отсутствуют стоп-слова и ненормативная лексика. Правила модерации вы задаёте сами. Рекомендуем заранее ознакомить подписчиков с правилами канала

Если комментарий нарушает правила, удалите его с помощью DELETE /messages/{messageId}/comments

После удаления комментарий восстановить нельзя

При успешном удалении вам вернётся Update с событием message_deleted

Пример запроса

BASH

Скопировать

curl -X DELETE "https://platform-api2.max.ru/comments/{commentId}" \
-H "Authorization: {access_token}" \
-H "Content-Type: application/json" \

Отправьте уведомление об удалении комментария и причинах. Это можно сделать с помощью POST /messages/{messageId}/comments

Пример запроса

BASH

Скопировать

curl -X POST "https://platform-api2.max.ru/messages/{messageId}/comments" \
-H "Authorization: {access_token}" \
-H "Content-Type: application/json" \
-d '{
"text": "Комментарий был удалён за нарушение правил модерации канала",
}'

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

Обзор

Методы

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

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

Webhook

Long Polling

Получение chat_id

Команды для чат-бота

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

Типы кнопок

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

Кнопка request_contact

Кнопка clipboard

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

Markdown

заголовок

HTML

заголовок

Отправка медиафайлов

Типы вложений

О загрузке медиафайлов

Примеры с видео, изображением, файлом

Как настроить модерацию комментариев к постам в каналах

Как модерировать комментарии с помощью бота и API MAX

Получение `chat_id`