Вернуться на главную

API Документация

Полное руководство по интеграции и использованию API платформы MAX Чат-боты для разработчиков

Обзор API

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

Все запросы и ответы используют формат JSON. API поддерживает как синхронные, так и асинхронные операции, что обеспечивает гибкость при работе с длительными процессами, такими как массовая рассылка или генерация аналитических отчётов. Базовый URL для всех запросов: https://api.max-ai-bot.ru/v1. Мы рекомендуем всегда использовать последнюю версию API и указывать версию явно в URL запроса.

Платформа также поддерживает webhook-уведомления, которые позволяют получать события в реальном времени. Вы можете подписаться на различные типы событий: новые сообщения, изменения статуса бота, завершение диалогов и другие. Webhook-и отправляются методом POST на указанный вами URL с подписью для проверки подлинности.

Аутентификация

Для доступа к API необходимо пройти аутентификацию с использованием API-ключа. Каждый проект в личном кабинете имеет уникальный API-ключ, который можно создать и отозвать в любое время. Ключ передаётся в заголовке каждого запроса в формате: Authorization: Bearer YOUR_API_KEY. Без корректного ключа все запросы будут отклонены с кодом 401 Unauthorized.

API-ключи обладают различными уровнями доступа, которые можно настроить в личном кабинете. Рекомендуется использовать принцип наименьших привилегий: для каждого интегрированного сервиса создавайте отдельный ключ с минимально необходимым набором разрешений. Например, сервису аналитики достаточно доступа только к эндпоинтам чтения статистики, тогда как сервису управления ботами потребуется полный доступ.

Для повышения безопасности мы поддерживаем ротацию ключей без прерывания сервиса. При создании нового ключа старый продолжает действовать в течение настраиваемого периода перехода (по умолчанию 24 часа), что позволяет бесшовно обновить ключ во всех интеграциях. Также доступна двухфакторная аутентификация для доступа к личному кабинету управления API-ключами.

Основные эндпоинты

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

  • POST /bots — Создание нового чат-бота. Принимает конфигурацию бота, включая название, описание, сценарии диалогов и настройки ИИ-движка. Возвращает идентификатор созданного бота.
  • GET /bots — Получение списка всех ботов проекта с пагинацией и фильтрацией по статусу, дате создания и другим параметрам.
  • GET /bots/{id} — Получение детальной информации о конкретном боте, включая его конфигурацию, статистику и текущий статус.
  • PUT /bots/{id} — Обновление конфигурации бота. Поддерживает частичное обновление через JSON Merge Patch.
  • DELETE /bots/{id} — Удаление бота. Операция необратима и удаляет все связанные данные, включая историю диалогов.
  • POST /messages — Отправка сообщения от имени бота. Поддерживает текст, изображения, файлы, кнопки и карусели.
  • GET /analytics/overview — Получение сводной аналитики: количество диалогов, среднее время ответа, конверсия, удовлетворённость пользователей.
  • POST /webhooks — Регистрация webhook-подписки на события платформы. Указываете URL и типы событий, на которые хотите подписаться.

Все эндпоинты поддерживают стандартные HTTP-методы и коды ответов. Успешные запросы возвращают статус 200 (или 201 для создания ресурсов), ошибки валидации — 400, проблемы аутентификации — 401, отсутствие ресурса — 404, превышение лимитов — 429. Детальная информация об ошибках возвращается в теле ответа в формате JSON с полями error, message и details.

Лимиты и тарификация

API платформы имеет гибкую систему лимитов, которая зависит от выбранного тарифного плана. Лимиты устанавливаются на количество запросов в минуту, общий объём данных и количество одновременных подключений. Превышение лимита не ведёт к потере данных — запросы помещаются в очередь и обрабатываются при освобождении ресурсов, однако при систематическом превышении мы рекомендуем перейти на более высокий тариф.

На бесплатном тарифе доступны 100 запросов в минуту и до 1 000 сообщений в месяц. Тариф «Стартовый» увеличивает лимит до 1 000 запросов в минуту и 50 000 сообщений. Тариф «Бизнес» предоставляет 5 000 запросов в минуту и 500 000 сообщений. Для корпоративных клиентов доступен тариф «Предприятие» с индивидуальными лимитами и выделенной инфраструктурой.

Тарификация осуществляется по модели pay-as-you-go: вы оплачиваете только фактически потреблённые ресурсы. Стоимость рассчитывается на основе количества обработанных сообщений, использования ИИ-функций и объёма хранимых данных. Детальная разбивка расходов доступна в личном кабинете в режиме реального времени. Ежемесячно формируется детализированный счёт с полной информацией о потреблении.

Примеры кода

Для быстрого старта мы подготовили примеры кода на популярных языках программирования. Ниже приведён пример создания бота и отправки сообщения с использованием curl и Python.

Пример на curl — создание бота:

curl -X POST https://api.max-ai-bot.ru/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Бот поддержки",
    "description": "Автоматическая поддержка клиентов",
    "language": "ru",
    "scenario": "support_v2",
    "ai_engine": "gpt-4"
  }'

Пример на Python — отправка сообщения:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.max-ai-bot.ru/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Отправка сообщения
response = requests.post(
    f"{BASE_URL}/messages",
    headers=headers,
    json={
        "bot_id": "bot_abc123",
        "user_id": "user_xyz789",
        "text": "Здравствуйте! Чем могу помочь?"
    }
)

print(response.status_code, response.json())

Полные SDK доступны для Python, JavaScript/TypeScript, Go и Java. Каждый SDK включает типизацию, автоматическую обработку ошибок и повторные попытки при временных сбоях. Установить SDK можно через стандартные пакетные менеджеры: pip, npm, go mod и Maven соответственно.