Для AI-агентов: markdown этой страницы — /docs-content/connect-self-hosted-bitrix24.md индекс документации — /llms.txt

Подключение коробочного Битрикс24

Коробочный Битрикс24 заказчик разворачивает на своём сервере, а не в облаке Битрикс24. Чтобы Вайбкод мог работать с таким Битрикс24 — обращаться к CRM, задачам, ботам, выписывать вебхуки — на его стороне нужен личный ключ разработчика.

Подключение идёт через бот-компаньон: один раз для всего Битрикс24 и по одному подтверждению на каждого пользователя. В кабинете такой Битрикс24 подписан двояко — на карточке стоит отметка «Self-hosted», а в заголовке его настроек «Коробочная версия Битрикс24».

Как это работает

Шаг 1. Администратор Битрикс24 — один раз

Шаг выполняет любой пользователь коробочного Битрикс24 с правами администратора.

  1. Откройте административный раздел Битрикс24
  2. Установите бесплатный модуль «VibeCode Connector», если его ещё нет — он лежит в разделе модулей
  3. Откройте настройки модуля
  4. Нажмите «Подключить к Вайбкоду»
  5. Дождитесь окончания активации — модуль зарегистрирует Битрикс24 на платформе Вайбкод, выпишет ключ разработчика администратора, установит приложение и зарегистрирует бот-компаньон

После этого шага любой пользователь этого Битрикс24 подключает себя сам — обращаться к администратору повторно не нужно.

Шаг 2. Пользователь Вайбкод — одно подтверждение

  1. Откройте Вайбкод, перейдите на экран Выберите портал
  2. Нажмите «Подключить коробочную версию Битрикс24»
  3. Введите адрес своего Битрикс24 — например, mybox.example.com — и нажмите «Подключить»
  4. Мастер проверит, что этот Битрикс24 зарегистрирован и бот-компаньон на нём установлен
  5. Нажмите «Подтвердить в браузере» или «Подтвердить в десктоп-приложении» — откроется чат с «Вайбкод Бот» в мессенджере Битрикс24, и туда придёт запрос на привязку
  6. В запросе видна карточка с вашим именем и почтой из кабинета Вайбкод и две кнопки — «Да, это я» и «Нет, это не я»
  7. Нажмите «Да, это я» — Вайбкод выпишет ваш личный ключ разработчика и откроет дашборд этого Битрикс24

Открывайте чат там, где вы уже вошли в свой Битрикс24 — в приложении на компьютере или в браузере. Кнопки подтверждения активны 10 минут. Если сообщение от бота не пришло, в мастере есть повторная отправка.

Готово. С этого момента ваши скрипты, агенты и приложения Вайбкод могут обращаться к этому Битрикс24 от вашего имени.

Если вы уже подключали этот Битрикс24 раньше, мастер пропускает подтверждение в боте и сразу открывает дашборд.

Состояния мастера подключения

Состояние Что видит пользователь Что происходит
Проверка адреса «Проверяем ваш Битрикс24» Мастер ищет регистрацию по введённому адресу
Ожидание подтверждения «Подтвердите, что это вы», кнопки подтверждения активны 10 минут Запрос отправлен в чат с ботом
Успех «Битрикс24 подключён», отсчёт до перехода на дашборд Пользователь нажал «Да, это я», ключ разработчика выписан
Регистрация не найдена «Вайбкод пока не знает этот Битрикс24» с инструкцией шага 1 Модуль на Битрикс24 ещё не активирован
Бот-компаньон не подключён «Бот-компаньон ещё не подключён» Битрикс24 платформе известен, но бота, с которым можно говорить, на нём нет
Активация продолжается «Подключение активируется» Бот-компаньон устанавливается либо Битрикс24 временно недоступен
Отклонено «Подтверждение отклонено» Пользователь нажал «Нет» в боте
Срок истёк «Срок подтверждения истёк» С момента запроса прошло больше 10 минут
Ключ не выписан «Не удалось выписать ключ» с кодом ошибки Подтверждение прошло, но ключ разработчика выписать не удалось

Что делать в типичных ситуациях

«Вайбкод пока не знает этот Битрикс24»

Этот Битрикс24 ещё не зарегистрирован на платформе. Попросите администратора выполнить шаг 1: установить модуль «VibeCode Connector» и нажать «Подключить к Вайбкоду». После этого вернитесь в мастер и нажмите «Я подключил — повторить».

«Бот-компаньон ещё не подключён»

Проверьте три условия: модуль «VibeCode Connector» установлен и активирован, кнопка «Подключить к Вайбкоду» нажата, и на Битрикс24 разрешён входящий защищённый доступ со стороны платформы Вайбкод — межсетевой экран и трансляция сетевых адресов (NAT) не должны его блокировать.

«Подключение активируется»

Бот-компаньон ещё устанавливается либо Битрикс24 временно недоступен. Повторите попытку через пару минут.

Бот пишет «Запрос на привязку отклонён» — а вы ничего не отклоняли

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

«Срок подтверждения истёк» — прошло больше 10 минут

Код подтверждения действует 10 минут. Запустите подключение заново — мастер выдаст новую ссылку и отправит в бот новый запрос.

Бот пишет «Кнопка устарела» — нажимаю «Да, это я», а ничего не происходит

Так бывает, когда открыто старое сообщение от бота, а мастер за это время создал новый код подтверждения — например, если Вайбкод открыт в нескольких вкладках. Вернитесь в мастер, убедитесь, что он показывает свежий запрос, и нажмите кнопку подтверждения заново.

Сообщение от бота не пришло

В мастере есть кнопка «Отправить ещё раз». Если чат с ботом уже открыт, закройте вкладку мессенджера и нажмите кнопку подтверждения снова. Когда попытки отправки исчерпаны, начните подключение заново.

Кнопка «Подключить коробочную версию Битрикс24» не появляется

Возможность включается постепенно. Если кнопки нет, она выключена на стороне платформы — обратитесь к администратору платформы.

Пока идёт постепенное включение, кнопка видна с пометкой «бета», а в окне подключения показан баннер «Пока функция доступна ограниченному кругу пользователей». После полного включения кнопка выглядит так же, без пометки и баннера.

Бот не появился в моём Битрикс24

Бот-компаньон регистрируется сам, на шаге 1. Если бота нет, один из шагов активации не прошёл: выпуск ключа администратора, установка приложения, регистрация бота. Администратор может нажать «Подключить к Вайбкоду» повторно — повторное нажатие проходит только те шаги, которые не удались.

Безопасность

  • Карточка инициатора в боте — защитный механизм, а не оформление. Бот показывает имя и почту того пользователя Вайбкод, который запросил привязку. Не узнаёте его — нажмите «Нет, это не я», и ключ разработчика не будет выписан.
  • Код подтверждения действует 10 минут и он одноразовый: после подтверждения он аннулируется. Перехват ссылки бесполезен через 10 минут или после первого подтверждения.
  • Ключ разработчика хранится зашифрованным. В ответах API возвращается только подсказка — последние 4 символа. Сам ключ не отдаётся ни одному клиенту.
  • Защита от запросов во внутреннюю сеть (SSRF). Адреса вида localhost, 127.0.0.1 и записанные числами адреса отклоняются уже при вводе. Имя, которое ведёт во внутреннюю сеть, отсекается на следующем шаге — при исходящем вызове, до обращения к порталу.

После подключения

Подключённый коробочный Битрикс24 работает так же, как облачный:

  • Создавайте ключи API в разделе Ключи API — они работают через те же эндпоинты /v1/*
  • Создавайте OAuth-приложения в разделе Ключи авторизации — пользователи получают свой ключ разработчика автоматически, тем же подтверждением в боте
  • Запускайте AI-агентов и AI Router — доступны те же модели
  • Пользуйтесь веб-поиском и аналитикой. Расход списывается из кошелька Битрикс24 так же, как у облачного

Чем коробка отличается от облака:

  • На коробке скоупы ключа проверяет и Битрикс24. Платформа сверяет скоуп до вызова и отвечает 403 SCOPE_DENIED — одинаково для коробочного и облачного Битрикс24. Сверх этого на коробке набор скоупов записывается в сам вебхук при выпуске ключа, поэтому вызов вне скоупа отклонит и Битрикс24, кодом BITRIX_ACCESS_DENIED. Обрабатывайте оба — подробности в Ошибках.
  • Платная лицензия коробки сама по себе доступа к Вайбкод не даёт. Без действующей подписки Маркетплейса коробочный Битрикс24 не отдаёт ключ: установка приложения и выпуск ключа отвечают 403. В подписочном регионе — Россия и Беларусь — приходит код B24_MARKET_SUBSCRIPTION_REQUIRED, понятное сообщение и ссылка на оформление в error.details.upgradeUrl. Имя подписки зависит от региона: в России это «BitrixGPT + Маркетплейс», в Беларуси — «Битрикс24 Маркет Плюс». Коробка, у которой регион лицензии не определился, получает 403 INT_TARIFF_REQUIRED без ссылки: оформить подписку там негде. На .com инфраструктура и выпуск ключей дополнительно требуют тарифа Vibe+ (INT_VIBE_PLUS_REQUIRED). Полный разбор подписочных отказов — в Ошибках.
  • Признак wasEverCommercial не односторонний. В ответе GET /v1/me у коробочного Битрикс24, за которым не нашлось ни подписки, ни платежей, значение однократно меняется с true на false. Коробка, у которой регион лицензии не определён, признак сохраняет. Не полагайтесь на его монотонность.
  • Несколько пользователей одного Битрикс24 — каждый проходит шаг 2 сам и получает свой личный ключ разработчика. Учётные записи независимые: отзыв одного ключа не затрагивает остальные.

Если что-то пошло не так

Откройте раздел Обратная связь в кабинете Вайбкод или напишите в поддержку. В заявке укажите:

  • Адрес Битрикс24 — например, mybox.example.com
  • На каком состоянии мастера остановилось подключение
  • Текст ошибки и её код, если мастер их показал
  • Время попытки

С этими данными мы найдём ваш запрос в журнале аудита.

Что дальше