Быстрый старт¶

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

Все API-запросы требуют токен компании в заголовке:

Authorization: Bearer <company_api_token>

Токен выдается при создании компании в админ-панели.

Swagger UI¶

Интерактивная документация API доступна по адресу:

Swagger UI: https://app2.botfarm.me/api/docs/
OpenAPI Schema: https://app2.botfarm.me/api/schema/

Первый запрос: отправка сообщения¶

curl -X POST https://app2.botfarm.me/api/v1/sendMessage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Привет от BotFarm!",
    "user_ids": [1]
  }'

Навигация пользователя на страницу¶

curl -X POST https://app2.botfarm.me/api/v1/navigate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/welcome",
    "user_ids": [1]
  }'

BotFarm2 загрузит страницу /welcome с вашего бекенда, распарсит HTML и отправит сообщения пользователю.

Формат HTML-страницы¶

Ваш бекенд должен возвращать HTML с определенной разметкой. Минимальный пример:

<div class="bf-message">
    <span class="bf-text">Добро пожаловать!</span>
    <div class="bf-inline">
        <a href="/catalog">Каталог</a>
        <a href="/profile">Профиль</a>
    </div>
</div>

Это создаст сообщение с текстом и двумя кнопками. При нажатии на кнопку BotFarm2 перейдет на указанный URL и отправит новое сообщение.

Подробнее о разметке: HTML спецификация

Заголовки запроса к вашему бекенду¶

При загрузке страницы BotFarm2 передает информацию о пользователе в HTTP-заголовках:

Заголовок	Описание
`Botfarm-ID`	ID пользователя в BotFarm (BFUser.id)
`Botfarm-User-ID`	То же самое (алиас)
`Botfarm-First-Name`	Имя (URL-encoded)
`Botfarm-Last-Name`	Фамилия (URL-encoded)
`Botfarm-Username`	Username пользователя
`Botfarm-Type`	Платформа: `tg`, `vk`, `max`, `ig`
`Botfarm-Page`	Текущая страница пагинации кнопок
`Botfarm-Tg-Ext-ID`	Telegram ID (если есть)
`Botfarm-VK-Ext-ID`	VK ID (если есть)
`Botfarm-Max-Ext-ID`	Max ID (если есть)

Обработка действий пользователя¶

Когда пользователь отправляет текст, геолокацию или контакт, BotFarm2 отправляет POST-запрос на текущую страницу пользователя:

{
  "text": "Сообщение от пользователя",
  "location": null,
  "contact": null
}

Подробнее: Вебхуки

Cookies и сессии¶

BotFarm2 автоматически сохраняет и передает cookies для каждого пользователя. Это позволяет использовать стандартные Django-сессии или любой другой механизм аутентификации на вашем бекенде.