Как быстро собрать чат-бота в Bitrix24: стартер-кит с AI-агентами, Nuxt и тремя бэкендами — VogueTech

Что произошло

GitHub-проект b24-ai-starter превратился в полноценный конструктор для приложений и чат-ботов в Bitrix24. Это не просто шаблон кода, а целая среда, где за рутину отвечает связка Docker, Cloudpub и AI-агенты, а разработчик сразу работает с боевым стеком.

Факты и «цифры» проекта:

3 варианта бэкенда на выбор: PHP (Symfony 7), Python (Django), Node.js (Express).
Frontend на Nuxt 3 с Bitrix24 UI Kit и JS SDK.
Поддержка PostgreSQL 17 и MySQL 8.4.
Встроенный RabbitMQ для очередей и фоновых задач.
Готовая JWT-аутентификация и безопасные API endpoints.
Поддержка версий проекта через versions/ и скрипты create-version.sh / delete-version.sh.
Skills и инструкции для двух AI-сред: Cursor Agent (.cursor/skills/) и Claude Code (.claude/skills/).
Отдельный оркестратор security-проверок с Semgrep, Gitleaks, Trivy и аудитом зависимостей.

Разработчик получает структуру, которая годится и для локального приложения в своём портале Bitrix24, и как основа тиражного решения для маркетплейса Bitrix24.

Зачем это нужно

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

b24-ai-starter решает эту задачу сразу в нескольких плоскостях:

Стратегия для разработчика. Проект снимает необходимость каждый раз собирать окружение с нуля. Docker, Cloudpub, Nuxt 3, три стека бэкенда, RabbitMQ, PostgreSQL/MySQL — всё уже собрано в одном репозитории. Можно сосредоточиться на логике чат-бота, роботов, встройки или CRM-сценариев, а не на настройке nginx и Docker Compose.
Стратегия для команд и студий. Встроенная версионность (versions/) позволяет поддерживать несколько веток продукта: например, V1 для текущих клиентов и V2 с экспериментальными функциями. Скрипты создают и удаляют версии, а make dev-init умеет запускать нужную.
Стратегия для AI-разработки. Проект изначально заточен под работу с AI-агентами: есть модульные инструкции в instructions/ и skills для Cursor и Claude Code. Это позволяет поручать ассистентам типовые задачи: навигацию по проекту, добавление endpoints, работу с очередями, фронтенд-правки. Человек остаётся архитектором и ревьюером, а не «ручной IDE».
Почему сейчас. Bitrix24 активно продвигает маркетплейс и кастомные приложения. Чем быстрее команда может собрать прототип чат-бота или CRM-расширения, тем проще протестировать гипотезу и вывести продукт в продажи. Стартер-кит сокращает время до первого рабочего прототипа до нескольких часов.

Для каждой стороны выгода своя:

Разработчик тратит меньше времени на инфраструктуру.
Студия получает стандартизированный шаблон под все проекты Bitrix24.
Клиент быстрее получает рабочее решение, а не вечную «подготовку окружения».

Что меняет для рынка

Для разработчиков под Bitrix24

b24-ai-starter превращает разработку под Bitrix24 в более предсказуемый и стандартизированный процесс.

Что именно меняется:

Вход в экосистему. Новичок в Bitrix24, но знакомый с PHP, Python или Node.js, может взять стартер-кит и сразу увидеть, как выглядит полноценное приложение: как устроена установка, авторизация, работа с Bitrix24 API и frontend внутри портала.
Снижение инфраструктурного шума. Cloudpub даёт публичный HTTPS-домен, Docker поднимает весь стек, make dev-init автоматизирует инициализацию. Не нужно вручную настраивать туннели и веб-сервер.
Фокус на бизнес-логике. JWT, хранение установок, базовая безопасность, очереди, фронтенд-скелет — всё уже реализовано. Разработчик добавляет свои endpoints и UI, а не изобретает авторизацию и структуру проекта.
Переиспользуемость. Версионность через versions/ делает возможным параллельное развитие нескольких версий продукта, что важно для агентств и для тиражных решений.

Для интеграторов и студий

Появляется общий «скелет» проектов: фронтенд на Nuxt 3, один из трёх бэкендов, единая структура каталогов и единый подход к очередям, логам, security-проверкам.
Легче масштабировать команду: новый разработчик изучает instructions/knowledge.md и стек своего языка, а не разбирается в хаотичном монолите.
Встроенные security-проверки (Semgrep, Gitleaks, Trivy, audits) помогают держать минимальный уровень безопасности без отдельной DevSecOps-команды.

Для клиентов Bitrix24

Сокращение времени разработки кастомных приложений и чат-ботов.
Более предсказуемое качество: проекты собираются по одному шаблону, а не каждый раз «с нуля».
Легче сопровождать решения: структура кода и API единообразна.

Для AI-инструментов

Проект показывает, как можно использовать GPT-5 или Claude 4 не только для генерации кода, но и как постоянных «агентов-разработчиков» с чёткими инструкциями и skills.
Встроенные prompts и knowledge-база превращают репозиторий в среду, где ассистент понимает контекст и не ломает архитектуру при каждом изменении.

Что это значит для вас

Если вы:

Разработчик или тимлид, который делает приложения и чат-боты для Bitrix24.
Фаундер или руководитель интегратора, которому нужно стандартизировать проекты.
Продукт-менеджер, который хочет проверить гипотезу чат-бота или CRM-расширения на Bitrix24.

b24-ai-starter даёт вам:

Быстрый старт с готовым фронтендом и бэкендом.
Понятную схему авторизации через JWT и Bitrix24 OAuth.
Реалистичный пример того, как строить API, очереди, UI и безопасность.
Возможность подключить GPT-5 или Claude 4 в роли «сослуживца-разработчика» с заранее прописанными инструкциями.

Минусы и ограничения:

Проект рассчитан на разработчиков, которые уже уверенно работают с Docker и хотя бы одним из стеков: PHP, Python или Node.js.
Для production всё равно придётся настраивать свои секреты, домены, мониторинг и деплой — стартер-кит не заменяет DevOps, он даёт базу.
Если вы хотите что-то совсем минималистичное без Docker и без Nuxt, этот шаблон может показаться тяжеловесным.

Если вы уже пишете под Bitrix24 и устали каждый раз собирать окружение, этот репозиторий экономит недели. Если вы только заходите в экосистему, он даёт рабочий пример, как «делать правильно».

Как устроен проект

Проект b24-ai-starter организован вокруг нескольких ключевых блоков: фронтенд, бэкенды, инфраструктура, инструкции для AI и версионность.

Структура репозитория

b24-ai-starter/
├── frontend/ # Nuxt 3 фронтенд с Bitrix24 UI Kit
├── backends/ # Три варианта бэкенда на выбор
│   ├── php/   # Symfony + PHP SDK
│   ├── python/ # Django + b24pysdk
│   └── node/  # Express + Node.js
├── infrastructure/
│   └── database/ # PostgreSQL/MySQL init-скрипты
├── instructions/ # 📚 Модульные инструкции для AI-агентов
│   ├── knowledge.md # Центральный узел знаний
│   ├── php/ # PHP-специфичные инструкции
│   ├── python/ # Python-специфичные инструкции
│   ├── node/ # Node.js-специфичные инструкции
│   ├── frontend/ # Frontend-специфичные инструкции
│   ├── versioning/ # Инструкции для версионности проекта
│   ├── queues/ # Инструкции для сервиса очередей RabbitMQ
│   └── bitrix24/ # Платформенные инструкции
├── .cursor/
│   └── skills/ # Skills для Cursor Agent
├── .claude/
│   └── skills/ # Skills для Claude Code
├── logs/ # Логи вне контейнеров
├── versions/ # Версии проекта
├── README.md # 🤖 Главный промпт для AI
└── docker-compose.yml # Docker конфигурация

Разработчик может добавить свой бэкенд, просто создав папку в backends/ с нужной структурой и интеграцией в Docker Compose.

Инструкции и knowledge для AI-агентов

Центральная точка входа — instructions/knowledge.md. Это навигатор по проекту для AI-агентов и людей.

Модульная архитектура:

instructions/
├── knowledge.md             # Центральный узел — начните отсюда
├── php/knowledge.md         # Общие знания по PHP-части
├── python/knowledge.md      # Общие знания по Python-части
├── node/knowledge.md        # Общие знания по Node.js
├── queues/                  # Очереди и фоновые задачи
├── frontend/knowledge.md    # Общие знания по frontend
├── bitrix24/                # Платформенные инструкции
├── versioning/              # Инструкции для создания версий
└── [язык]/[специфика].md    # Детальные инструкции

Как с этим работать:

Открыть knowledge.md для общего обзора.
Выбрать стек: PHP, Python или Node.js.
Пройти в [язык]/knowledge.md.
При необходимости — изучить более узкие инструкции: очереди, фронтенд, версионность, Bitrix24.

Skills для Cursor и Claude Code

Проект содержит готовые skills для двух сред:

.cursor/skills/ — сценарии и инструкции для Cursor Agent.
.claude/skills/ — зеркальные сценарии для Claude Code.

Skills покрывают:

Навигацию по проекту.
Работа с окружением и Docker.
Разработку по каждому стеку (frontend / php / python / node).

Цель — чтобы AI-агент выполнял типовые задачи предсказуемо: добавление endpoints, правки в Nuxt, настройка очередей, обновление версий.

Версионность проекта

Версии проекта хранятся в versions/. Скрипты автоматизируют создание и удаление версий.

Ключевые элементы:

Промпт для агентов: instructions/versioning/create-version-prompt.md — сценарий «создать V2», чеклист проверки и способы переключения.
Создание версии:

./scripts/create-version.sh v2

Скрипт копирует текущий фронтенд, бэкенд и инфраструктуру, и прописывает APP_VERSION=v2 в .env.

Через make:

make create-version VERSION=v2
make delete-version VERSION=v2

Без VERSION включается интерактивный режим.

Удаление версии:

./scripts/delete-version.sh v2

Удаляет versions/v2 и при необходимости убирает APP_VERSION из .env.

Запуск нужной копии:

make dev-init

make dev-init предложит выбрать одну из директорий versions/*. Можно указать явно:

DEV_INIT_VERSION=v2 make dev-init
./scripts/dev-init.sh --version v2

Работа с git: по умолчанию versions/ участвует в истории. Если версия нужна только локально, добавьте каталог в .gitignore до коммита.

Технологический стек

Frontend:

Nuxt 3 (Vue 3, TypeScript).
Bitrix24 UI Kit (@bitrix24/b24ui-nuxt).
Bitrix24 JS SDK (@bitrix24/b24jssdk-nuxt).
Pinia для управления состоянием.
i18n для многоязычности.
TailwindCSS.

Backend (на выбор):

PHP: Symfony 7, Doctrine ORM, PHP SDK для Bitrix24.
Python: Django, Python SDK для Bitrix24 (b24pysdk).
Node.js: Express, PostgreSQL/MySQL, JWT, JS SDK для Bitrix24.

Infrastructure:

Docker и Docker Compose.
PostgreSQL 17 / MySQL 8.4.
Cloudpub (ngrok-like) для туннелирования.
Nginx для production.

Особенности:

На Windows при проблемах с api-php иногда нужно пересохранить backends/php/docker/php-fpm/docker-entrypoint.sh.
Для Python-бэкенда Django-админка доступна по адресу:

https://<VIRTUAL_HOST>/api/admin

Логин: <DJANGO_SUPERUSER_USERNAME>, пароль: <DJANGO_SUPERUSER_PASSWORD>.

Установка

Ниже — полный сценарий запуска, без сокращений. Он рассчитан на разработчика, который хочет быстро получить рабочее окружение и подключить приложение к порталу Bitrix24.

Автоматическая инициализация (рекомендуется)

Запустите интерактивный мастер настройки:

make dev-init

Мастер:

запросит API-ключ Cloudpub;
предложит выбрать бэкенд (PHP / Python / Node.js);
удалит неиспользуемые папки бэкендов;
настроит переменные окружения;
получит публичный домен от Cloudpub;
запустит Docker-контейнеры.

После этого можно открыть технический домен в браузере. Приложение сообщит об ошибке и попросит открыть URL внутри Bitrix24. Это нормальное поведение: окружение работает, но приложение ещё не получило токены авторизации от Bitrix24.

Подключение к порталу Bitrix24

Зная технический домен, добавьте его в настройки локального приложения в вашем портале Bitrix24 или в карточку приложения в кабинете разработчика:

https://vendors.bitrix24.ru

Основные URL:

Основной URL приложения: [технический-домен]/
URL установки приложения: [технический-домен]/install

Разрешения (scopes), которые нужно запросить:

crm
user_brief
pull
placement
userfieldconfig

После добавления приложения Bitrix24 выдаст CLIENT_ID и CLIENT_SECRET. Вставьте их в .env и перезапустите Docker-контейнеры.

Примеры команд перезапуска:

make down
make dev-php      # если выбран PHP-бэкенд
# или
make dev-python   # если выбран Python-бэкенд
# или
make dev-node     # если выбран Node.js-бэкенд

После этого переустановите приложение в портале Bitrix24. Теперь можно начинать разработку.

Ручная настройка (вместо автоматической)

Если вы не хотите использовать make dev-init, можно настроить всё вручную.

Скопируйте и настройте переменные окружения:

cp .env.example .env

Запустите стек в режиме разработки с выбранным бэкендом:

# Разработка с PHP бэкендом
make dev-php

# Разработка с Python бэкендом
make dev-python

# Разработка с Node.js бэкендом
make dev-node

Остановить все сервисы:

make down

Production-сборка:

# Продакшн с PHP
make prod-php

# Продакшн с Python
make prod-python

# Продакшн с Node.js
make prod-node

Частичные профили Docker Compose:

# Только PostgreSQL + фронтенд (для тестирования)
COMPOSE_PROFILES=db-postgres,frontend docker compose up --build

# Полный стек
COMPOSE_PROFILES=php,worker docker-compose up -d

Переменные окружения для production

Для боевого режима обязательно задайте свои значения:

JWT_SECRET — секрет для шифрования JWT-токенов между frontend и backend.
DB_TYPE — тип СУБД (postgresql или mysql).
DB_USER — имя пользователя базы данных.
DB_PASSWORD — пароль пользователя базы данных.
DB_NAME — имя базы данных.
DB_PORT — порт СУБД (5432 для PostgreSQL, 3306 для MySQL).
DATABASE_URL — DSN для PHP/Doctrine (автоматически настраивается через make dev-init).
BUILD_TARGET — установите в production для prod-сборки фронтенда.
DJANGO_SUPERUSER_USERNAME — логин суперпользователя Django (для Python-бэкенда).
DJANGO_SUPERUSER_EMAIL — email суперпользователя Django.
DJANGO_SUPERUSER_PASSWORD — пароль суперпользователя Django.

Как запустить

Ниже — практические примеры команд, которые пригодятся каждый день.

Основной цикл разработки

Инициализация (один раз на проект или на новую версию):

make dev-init

Запуск нужного бэкенда (если не использовали мастер):

make dev-php
# или
make dev-python
# или
make dev-node

Остановка сервисов:

make down

Запуск только БД и фронтенда (например, для UI-разработки):

COMPOSE_PROFILES=db-postgres,frontend docker compose up --build

Полный стек с PHP и воркерами:

COMPOSE_PROFILES=php,worker docker-compose up -d

Работа с RabbitMQ

make dev-init может автоматически развернуть контейнер RabbitMQ и сгенерировать учётные данные, которые сохраняются в .env.

Профиль queue:

AMQP: порт 5672.
Панель управления: порт 15672.

Команды:

# Запуск брокера
make queue-up

# Остановка брокера
make queue-down

Подробности по каждому стеку:

Сервис и переменные окружения — instructions/queues/server.md.
PHP + Messenger — instructions/queues/php.md.
Python + Celery — instructions/queues/python.md.
Node.js + amqplib — instructions/queues/node.md.

Security-проверки

Оркестратор security-тестов:

make security-tests

Команда запускает scripts/security-tests.sh в Docker-окружении. Скрипт выполняет аудит зависимостей, статический анализ и общие проверки:

Semgrep (OWASP Top 10).
Gitleaks.
Trivy.
Дополнительно: phpstan / bandit / eslint (в полном профиле).

Профили:

quick (по умолчанию) — dependency audit + Semgrep.
full — быстрый профиль + phpstan/bandit/eslint, Gitleaks и Trivy.
custom — интерактивный выбор шагов.

Особенности:

В интерактивном режиме шаги с уязвимостями помечаются как «предупреждение», пайплайн продолжает работу.
В режиме --ci те же шаги считаются ошибкой.
Отчёты сохраняются в reports/security/<timestamp>/....

Пример запуска с параметрами:

make security-tests SECURITY_TESTS_ARGS="--profile full --allow-fail"

Быстрый аудит зависимостей:

make security-scan

Команда запускает scripts/security-scan.sh.

Скрипт делает:

composer audit --locked --format=json внутри контейнера php-cli, если есть backends/php.
pnpm audit --prod --json в контейнере frontend.

JSON-отчёты сохраняются в:

reports/security/php-composer.json.
reports/security/frontend-pnpm.json.

По умолчанию скрипт завершает работу с ненулевым кодом, если найдены уязвимости. Мягкий режим:

SECURITY_SCAN_ALLOW_FAILURES=1 make security-scan
# или
./scripts/security-scan.sh --allow-fail

Команда ничего не запускает автоматически, её удобно использовать в локальных чеклистах перед релизом или в CI.

Как устроена аутентификация и API

b24-ai-starter сразу даёт готовую схему аутентификации и защищённых endpoints.

JWT-токены

Все API endpoints, кроме /api/install и /api/getToken, требуют JWT-токен в заголовке:

Authorization: Bearer ${tokenJWT}

Процесс аутентификации

Установка приложения (/api/install)

Вызывается из фронтенда при установке приложения.
JWT не требуется.
Получает данные из Bitrix24: DOMAIN, AUTH_ID, REFRESH_TOKEN, member_id, user_id и другие.
Сохраняет данные установки в БД.

Параметры (POST):

DOMAIN: string — домен портала Bitrix24.
PROTOCOL: number — протокол (0 — HTTP, 1 — HTTPS).
LANG: string — язык интерфейса.
APP_SID: string — идентификатор сессии приложения.
AUTH_ID: string — токен авторизации.
AUTH_EXPIRES: number — время истечения токена.
REFRESH_ID: string — токен обновления.
member_id: string — ID участника.
user_id: number — ID пользователя.
PLACEMENT: string — размещение приложения.
PLACEMENT_OPTIONS: object — опции размещения.

Ответ:

{
  "message": "Installation successful"
}

Пример тестирования:

curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":"1","PLACEMENT":"DEFAULT","PLACEMENT_OPTIONS":"{\"any\":\"6\/\"}"}'

Получение токена (/api/getToken)

Вызывается фронтендом для получения JWT-токена.
JWT не требуется.
На вход передаются данные авторизации Bitrix24.
Время жизни токена: 1 час.

Параметры (POST):

DOMAIN: string.
PROTOCOL: number.
LANG: string.
APP_SID: string.
AUTH_ID: string.
AUTH_EXPIRES: number.
REFRESH_ID: string.
member_id: string.
user_id: number.

Ответ:

{
  "token": "AIHBdxxxLLL"
}

Пример тестирования:

curl -X POST http://localhost:8000/api/getToken \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":1}'

Защищённые endpoints

Проверяют JWT-токен через middleware / декораторы.
Извлекают bitrix24_account из токена.
Предоставляют доступ к Bitrix24 API через соответствующий SDK.

Общий формат запроса с JWT:

const { data, error } = await $fetch('/api/protected-route', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${someJWT}`
  }
})

Сервер возвращает JSON. При ошибке статус-код 401, 404 или 500 и тело вида:

{
  "error": "Internal server error"
}

Стандартные API endpoints

/api/health — статус бэкенда.

Метод: GET.
Параметры: нет.
Ответ:

{
  "status": "healthy",
  "backend": "php",
  "timestamp": 1760611967
}

Пример:

curl http://localhost:8000/api/health

/api/enum — перечисление опций.

Метод: GET.
Параметры: нет.
Ответ:

[
  "option 1",
  "option 2",
  "option 3"
]

Пример:

curl http://localhost:8000/api/enum

/api/list — список элементов.

Метод: GET.
Параметры: нет.
Ответ:

[
  "element 1",
  "element 2",
  "element 3"
]

Пример:

curl http://localhost:8000/api/list

Примеры добавления нового endpoint

PHP (Symfony):

#[Route('/api/my-endpoint', name: 'api_my_endpoint', methods: ['GET'])]
public function myEndpoint(Request $request): JsonResponse
{
    // JWT payload доступен через:
    $jwtPayload = $request->attributes->get('jwt_payload');
    
    // Bitrix24 аккаунт через:
    // $bitrix24Account = ...
    
    return new JsonResponse(['data' => 'value'], 200);
}

Python (Django):

@xframe_options_exempt
@require_GET
@log_errors("my_endpoint")
@auth_required
def my_endpoint(request: AuthorizedRequest):
    # Bitrix24 клиент доступен через:
    client = request.bitrix24_account.client
    
    # Вызов Bitrix24 API:
    response = client._bitrix_token.call_method(
        api_method='method.name',
        params={'param': 'value'}
    )
    
    return JsonResponse({'data': 'value'})

Node.js (Express):

app.get('/api/my-endpoint', verifyToken, async (req, res) => {
  // JWT payload доступен через:
  const jwtPayload = req.jwtPayload;
  
  // Bitrix24 API вызовы...
  
  res.json({ data: 'value' });
});

Frontend: Nuxt 3, Bitrix24 UI Kit и JS SDK

Основные директории

app/pages/ — страницы приложения:
- index.client.vue — главная страница.
- install.client.vue — страница установки.
- *.client.vue — клиентские страницы (SSR отключён).
app/stores/ — Pinia stores:
- api.ts — API-методы и управление JWT.
- user.ts — данные пользователя.
- appSettings.ts — настройки приложения.
- userSettings.ts — пользовательские настройки.
app/composables/:
- useAppInit.ts — инициализация приложения, загрузка данных через batch.
- useBackend.ts — работа с бэкендом.
app/middleware/:
- 01.app.page.or.slider.global.ts — глобальный middleware для инициализации B24Frame и обработки placement.
app/layouts/:
- default.vue — основной layout.
- placement.vue — layout для placement.
- slider.vue — layout для слайдеров.
- uf-placement.vue — layout для пользовательских полей.

Работа с Bitrix24 JS SDK

Получение B24Frame:

const { $initializeB24Frame } = useNuxtApp()
const $b24: B24Frame = await $initializeB24Frame()

Batch-запросы:

const response = await $b24.callBatch({
  appInfo: { method: 'app.info' },
  profile: { method: 'profile' }
})
const data = response.getData()

Одиночные вызовы:

const result = await $b24.callMethod('method.name', { param: 'value' })

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

const authData = $b24.auth.getAuthData()

Открытие слайдеров:

await $b24.slider.openPath('/path/to/page')

Работа с API store

const apiStore = useApiStore()

// Инициализация (после инициализации B24Frame)
await apiStore.init($b24)

// Запросы с автоматической передачей JWT
const data = await apiStore.getList()
const enumData = await apiStore.getEnum()

Добавление нового метода в store (app/stores/api.ts):

const myMethod = async (): Promise<MyType> => {
  return await $api('/api/my-endpoint', {
    headers: {
      Authorization: `Bearer ${tokenJWT.value}`
    }
  })
}

Bitrix24 UI Kit

Компоненты подключаются через @bitrix24/b24ui-nuxt и доступны в шаблонах Nuxt.

Пример:

<template>
  <B24Card>
    <template #header>
      <h1>Заголовок</h1>
    </template>
    
    <B24Button
      label="Кнопка"
      color="air-primary"
      @click="handleClick"
    />
    
    <B24Input
      v-model="inputValue"
      placeholder="Введите текст"
    />
    
    <B24Badge
      label="Статус"
      color="air-primary-success"
    />
    
    <B24Avatar
      :src="photoUrl"
      size="md"
    />
  </B24Card>
</template>

Встройки, события и роботы Bitrix24

Если вы создаёте чат-бота или приложение, которое реагирует на события CRM, бизнес-процессы или встройки, важно учитывать несколько моментов.

Встройки (Widgets)

Используются для размещения интерфейса внутри разных областей Bitrix24.
Документация: API Reference: Widgets и инструкция «Разработка приложения с встройками».

События (Events)

Регистрируются через event.bind в процессе установки.
Обрабатываются через публичный endpoint /api/app-events.
JWT не используется.
Поддерживаются форматы application/x-www-form-urlencoded и JSON.

Роботы (Robots)

Регистрируются через bizproc.robot.add.
Обрабатываются через публичный endpoint /api/robot-handler.
JWT не используется.
Поддерживаются разные форматы данных от Bitrix24.

Ключевые моменты реализации:

Публичные endpoints для событий и роботов не используют JWT, но должны быть корректно защищены на уровне домена и валидации входящих данных.
Нужно корректно построить структуру OAuth и OAuthPlacementData для SDK.
Регистрацию встройки, событий и роботов стоит добавить в install.client.vue, чтобы они создавались при установке приложения.

Что хорошо, а что нет

Плюсы:

Реальный боевой стек: Nuxt 3, Symfony 7 / Django / Express, PostgreSQL/MySQL, RabbitMQ.
Готовая авторизация через JWT и Bitrix24 OAuth.
Чёткая структура проекта и модульные инструкции для людей и AI-агентов.
Встроенные security-проверки и сценарии для CI.
Версионность проекта из коробки.

Минусы:

Порог входа для тех, кто не знаком с Docker и DevOps-подходом.
Для очень простых задач (например, один маленький webhook) шаблон может быть избыточным.
Требуется аккуратная настройка переменных окружения для production.

Если вы строите серьёзного чат-бота, сложное приложение или планируете выход в маркетплейс Bitrix24, b24-ai-starter даёт рациональный старт и экономит много времени. Если задача — одноразовый скрипт, проще обойтись чем-то более лёгким.

Итог для читателя VogueTech

b24-ai-starter — это пример того, как можно использовать GPT-5 и Claude 4 не только для генерации кода по запросу, а как часть инженерного процесса. Репозиторий задаёт правила игры, а AI-агенты работают внутри этих правил.

Для рынка Bitrix24 это означает, что разработка чат-ботов и приложений постепенно переезжает из мира «кустарных» решений в мир стандартизированных конструкторов. Для вас это шанс тратить меньше времени на инфраструктуру и больше — на сценарии, которые действительно приносят деньги: автоматизация продаж, поддержка, интеграция с внешними сервисами и интеллектуальные боты внутри CRM.

Что произошло

Зачем это нужно

Что меняет для рынка

Для разработчиков под Bitrix24

Для интеграторов и студий

Для клиентов Bitrix24

Для AI-инструментов

Что это значит для вас

Как устроен проект

Структура репозитория

Инструкции и knowledge для AI-агентов

Skills для Cursor и Claude Code

Версионность проекта

Технологический стек

Установка

Автоматическая инициализация (рекомендуется)

Подключение к порталу Bitrix24

Ручная настройка (вместо автоматической)

Переменные окружения для production

Как запустить

Основной цикл разработки

Работа с RabbitMQ

Security-проверки

Как устроена аутентификация и API

JWT-токены

Процесс аутентификации

Стандартные API endpoints

Примеры добавления нового endpoint

Frontend: Nuxt 3, Bitrix24 UI Kit и JS SDK

Основные директории

Работа с Bitrix24 JS SDK

Работа с API store

Bitrix24 UI Kit

Встройки, события и роботы Bitrix24

Встройки (Widgets)

События (Events)

Роботы (Robots)

Что хорошо, а что нет

Итог для читателя VogueTech

Читайте также