Обзор

В этом руководстве вы найдёте базовую информацию о принципах работы MAX Bot API и о подготовке к его использованию.

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

MAX Bot API позволяет ботам взаимодействовать с мессенджером. Методы вызываются отправкой HTTPS-запросов на домен botapi.max.ru.

Методы и объекты

Методы — это условные команды, которые соответствуют той или иной операции с базой данных: получению информации, записи или удалению.

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

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

Параметры запроса указываются в пути, URL-параметрах или теле запроса — в зависимости от конкретного метода.

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

GET https://botapi.max.ru/messages/{messageId}?access_token={your_token} — получение сообщения
POST https://botapi.max.ru/messages?access_token={your_token} — отправка сообщения
PATCH https://botapi.max.ru/chats/{chatId}?access_token={your_token} — изменение информации о чате

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

Клавиатура

Вы можете добавить в чат-бота кнопки. Поддерживаются:

callback — при нажатии сервер MAX отправляет событие с типом message_callback (через WebHook или long polling)
link — при нажатии пользователю будет предложено открыть ссылку в новой вкладке
request_contact — запрашивает у пользователя разрешение на доступ к контактной информации (номер телефона, короткая ссылка, email)
request_geo_location — запрашивает у пользователя его местоположение
chat — создаёт для пользователя и бота чат, связанный с сообщением

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

JSON

{
  "text": "It is message with inline keyboard",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "callback",
              "text": "Press me!",
              "payload": "button1 pressed"
            }
          ],
          [
            {
              "type": "chat",
              "text": "Discuss",
              "chat_title": "Message discussion"
            }
          ]
        ]
      }
    }
  ]
}

Кнопка chat

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

Чат создаётся, когда первый пользователь нажимает на кнопку. Бот получит обновление message_chat_created.

Бот может установить название и описание нового чата, указав свойства chat_title и chat_description.

Клавиатура может содержать несколько кнопок chat. Чтобы различать их между собой, используется свойство uuid. Если вы не передадите uuid, он будет сгенерирован автоматически. Если вы редактируете сообщение, передайте uuid, чтобы система знала, что эта кнопка запускает тот же чат, что и раньше.

Кнопка chat также может содержать start_payload, который будет отправлен боту как часть обновления message_chat_created.

Диплинки

MAX поддерживает глубинные ссылки (диплинки) для ботов. Это позволяет передавать боту дополнительные полезные данные при его запуске. Диплинк может содержать любые данные, закодированные в строку длиной до 128 символов. Более длинные строки будут обрезаны и не передаться боту.

У каждого бота есть стартовая ссылка, которая выглядит так:

https://max.ru/%BOT_USERNAME%/start/%PAYLOAD%

Когда пользователь нажимает на такую ссылку, открывается диалог с ботом, и эти данные передаются боту как часть события bot_started:

JSON

{
    "update_type": "bot_started",
    "timestamp": 1573226679188,
    "chat_id": 1234567890,
    "user": {
        "user_id": 1234567890,
        "name": "Борис",
        "username": "borisd84"
    },
    "payload": "любые данные, важные для бота"
}

Диплинки поддерживаются для iOS версии 2.7.0 и Android версии 2.9.0 и выше.