Документация для разработчиков
Полное руководство по интеграции с БотПолка. REST API, WebSocket события, вебхуки и SDK. Все, что нужно, чтобы автоматизировать вашу поддержку.
Методы аутентификации
Доступ к API БотПолка защищен через Bearer-токены. Выберите метод, подходящий для вашего сценария использования.
API Keys (Server-to-Server)
Используйте для серверных интеграций, где безопасность ключа гарантирована.
Создайте ключ в разделе 'Настройки' → 'API Access'. Ключи имеют суффиксы pk_live (продакшн) и pk_test (песочница).
OAuth 2.0 (User Context)
Для приложений, действующих от имени оператора поддержки.
Стандартный поток Authorization Code. Токены обновляются автоматически (Refresh Token). Срок жизни Access Token — 1 час.
Работа с сообщениями
Отправка, получение и управление жизненным циклом сообщений во всех подключенных каналах.
POST /v1/messages
Отправка сообщения в чат. Поддерживает Markdown, кнопки и файлы до 10MB.
GET /v1/messages
Получение истории переписки. Пагинация через cursor-based navigation.
POST /v1/webhooks
Настройка подписки на события (new_message, user_typing, status_changed).
Пользователи и Чаты
Управление профилями клиентов (Contact) и сессиями (Chat). БотПолка автоматически агрегирует данные из разных источников в единый профиль.
GET /v1/users/{id}
Получение профиля пользователя. Возвращает email, телефон, теги, историю покупок (если интегрирована CRM) и score лояльности.
POST /v1/chats
Создание новой сессии чата или назначение существующего пользователя на оператора. Поддерживается автоматическая маршрутизация.
1200
Запросов в минуту (Rate Limit)
10MB
Лимит тела запроса
99.99%
SLA доступности API
JWT
Формат токенов
Коды ответов
API использует стандартные HTTP-коды. Ошибки возвращаются в формате JSON с полем error_code для детальной диагностики.
| HTTP Code | Error Code | Описание |
|---|---|---|
| 400 | INVALID_PAYLOAD | Ошибка валидации JSON. Проверьте обязательные поля. |
| 401 | AUTH_FAILED | Неверный или истекший API-ключ. |
| 429 | RATE_LIMIT_EXCEEDED | Превышен лимит запросов. Повторите через 60 секунд. |
| 500 | INTERNAL_ERROR | Ошибка на стороне сервера БотПолка. Обратитесь в поддержку. |
Готовые SDK
Ускорьте разработку с помощью официальных библиотек. Полная типизация, обработка вебхуков и автоматическая ретрай-логика.