Перейти к содержанию

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

Страница для администратора Битрикс24 и тех, кто ведёт сервер. Она отвечает на вопросы: какой вебхук создать и с какими правами, что именно платформа берёт с портала, чего она не делает никогда и что будет, если портал перестанет отвечать.

Основное подключение работает только на чтение: платформа ничего не создаёт, не меняет и не удаляет в Битрикс24. Единственное исключение, комментарии с итогами проверки в сделках, выключено по умолчанию и работает только на боевом сервере.

Какие вебхуки можно подключить

Вебхук Переменная окружения Обязателен Что даёт
Входящий (REST) BITRIX24_WEBHOOK_URL да Всё чтение: звонки, записи, сотрудники, сделки. Без него Битрикс24 не подключён
Исходящий «звонок завершён» BITRIX24_EVENT_TOKEN нет Платформа узнаёт о звонке сразу после его окончания
Отдельный вебхук для записи BITRIX24_WRITE_WEBHOOK_URL, PUBLIC_BASE_URL нет Комментарии с итогами проверки в карточках сделок

Адрес вебхука содержит секрет. Храните его только в переменных окружения сервера (в Coolify). Платформа не показывает адрес в интерфейсе и не пишет его в сообщения об ошибках; API сообщает только имя портала.

Входящий вебхук: права и проверка

Создайте входящий вебхук от имени сотрудника, который видит звонки и сделки всех отделов продаж: вебхук действует с правами того, кто его создал. Полный адрес запишите в BITRIX24_WEBHOOK_URL и перезапустите сервис tgt-api.

Платформа вызывает только методы чтения. Их список закреплён в коде клиента Битрикс24, методов записи в нём нет. Вебхуку нужны четыре права:

Право вебхука Методы Для чего
CRM (crm) crm.category.list, crm.status.list, crm.deal.list, crm.stagehistory.list, crm.activity.list воронки, стадии, сделки, история стадий, дела
Телефония (telephony) voximplant.statistic.get статистика звонков и ссылки на записи
Пользователи (user) user.get, user.fields сотрудники и поле «Служба»
Диск (disk) disk.file.get ссылка на файл записи, если портал отдаёт запись файлом

Метод profile возвращает имя владельца вебхука и служит проверкой соединения.

Как проверить подключение:

  1. Откройте «Настройки → Автоматика». Шаг «Битрикс24 подключён» в списке «Что осталось настроить» отмечается, когда задан адрес вебхука.
  2. Нажмите «Дополнительно». Если портал не отвечает, над карточкой «Новые звонки» стоит предупреждение «Битрикс24 не подключён» с текстом ответа портала.
  3. Тот же ответ отдаёт API: GET /v1/integrations/bitrix24 возвращает поля configured, connected, portalHost, userName и message (доступно владельцу и ключу API).

Что платформа читает

Метод Что берётся Для чего
voximplant.statistic.get идентификатор звонка, сотрудник, дата, направление, длительность, ссылка на запись или файл записи, к чему звонок привязан в CRM, код неудачи, номер линии компании, номер клиента загрузка записей; звонки менеджеров в копии CRM
disk.file.get ссылка на скачивание файла записи скачать запись, когда в статистике указан только файл
user.get, user.fields идентификатор, имя, должность, подразделения, признак «работает», значение поля «Служба»; user.fields нужен, чтобы найти это поле по названию состав отделов и менеджеров продаж, службы
crm.category.list, crm.status.list воронки сделок и их стадии: названия, порядок, тип стадии (в работе, успех, провал) отчёты по воронкам и стадиям
crm.deal.list идентификатор, воронка, стадия, ответственный, даты создания, изменения и закрытия, сумма и валюта, признак повторного клиента, источник, идентификаторы лида, компании и контакта, время последнего действия продажи, отказы, сделки под вопросом
crm.stagehistory.list переходы сделок между стадиями где теряются сделки
crm.activity.list владелец дела таймлайна, к которому привязан звонок: тип и идентификатор связь звонка со сделкой

Что важно знать о выборке:

  • Сделки читаются из воронок, номера которых заданы у отделов («Настройки → Люди → Отделы → Воронки сделок»). Открытые сделки читаются целиком, остальные за глубину истории: 3 месяца по умолчанию, от 1 до 12 («Настройки → Автоматика → Дополнительно → Данные из CRM → Глубина истории»). Если номера воронок не совпадают с вашим порталом, сделок в платформе не будет.
  • Звонки читаются только у менеджеров продаж из состава, который владелец подтвердил в «Настройки → Люди → Отделы → Менеджеры продаж». Пока состава нет, платформа ничего не загружает и отказывает в любой загрузке звонков.
  • Валюта. Берётся валюта каждой сделки. Платформа не пересчитывает суммы из одной валюты в другую и не читает ни базовую валюту портала, ни курсы.
  • Поле «Служба». Платформа ищет среди пользовательских полей сотрудников поле с названием «Служба» (регистр не важен) и читает его значение как текст. Если поля нет, службы у сотрудников пустые. Если список полей прочитать не удалось, службы остаются прежними, а в карточке «Данные из CRM» стоит пометка об этом.

Как часто и с какой нагрузкой

Что Когда
Проверка новых звонков в автоматическом режиме каждые 30 минут; в интерфейсе можно выбрать 15, 30, 60 или 120 минут
Чтение копии CRM раз в сутки при включённом переключателе «Ночное обновление данных CRM»; кнопка «Обновить сейчас» работает и без него
Загрузка истории по кнопке «Загрузить историю», с оценкой числа звонков и подтверждением
Событие «звонок завершён» сразу, если подключён исходящий вебхук

Портал отвечает не чаще двух запросов в секунду. Платформа делает паузы между страницами: 1 секунда при чтении CRM (CRM_SYNC_PAUSE_SECONDS) и 2 секунды при выгрузке звонков (BITRIX24_EXPORT_PAUSE_SECONDS). Чтение CRM стоит, пока идёт выгрузка звонков, потому что оба используют один вебхук. Ответы 429 и 503 повторяются до трёх раз с паузой 0,5, 1 и 2 секунды; запрос ждёт ответа не дольше 15 секунд. Эти две переменные не входят в docker-compose.yml: чтобы изменить их, добавьте их в environment сервиса tgt-api. Короче пауз делать не стоит: портал начнёт отказывать.

Исходящий вебхук «звонок завершён»

Он нужен, только если хотите получать звонок сразу. Автоматический режим и без него проверяет новые звонки по расписанию.

  1. В Битрикс24 создайте исходящий вебхук на событие ONVOXIMPLANTCALLEND с адресом обработчика https://<адрес-API>/v1/integrations/bitrix24/events.
  2. Скопируйте токен приложения этого вебхука в BITRIX24_EVENT_TOKEN и перезапустите tgt-api.
  3. Убедитесь, что включён переключатель «Автозабор записей» («Настройки → Система»).

Что происходит с событием:

  • Без BITRIX24_EVENT_TOKEN или с неверным токеном платформа отвечает 403. Если в запросе нет названия события или идентификатора звонка, ответ 400; события других типов получают {"accepted": false}.
  • Звонок ставится в очередь «Звонки Битрикс24». Платформа находит его в статистике, скачивает запись и заполняет номер, менеджера, направление и время начала. Если статистика или запись ещё недоступны, платформа повторяет попытку: всего шесть попыток с паузами 30 секунд, 1, 2, 4 и 8 минут.
  • Звонок менеджера, которого нет в составе отделов, и любой звонок при пустом составе только записываются в журнал сервера и не скачиваются.

Внимание

События принимаются, только пока включён переключатель «Автозабор записей»; пока он выключен, платформа отвечает {"accepted": false} и звонок не загружает. Переключатель показывается в «Настройки → Система», лишь когда задан источник записей (INGESTION_SOURCE) или он уже включён. Без источника исходящий вебхук включить нельзя; для новых звонков используйте автоматический режим, ему исходящий вебхук не нужен.

Запись итогов в сделки

Это единственное место, где платформа что-то пишет в Битрикс24: комментарий в таймлайн сделки (crm.timeline.comment.add). Комментарий видят сотрудники, а платформа не умеет его править или удалять. Поэтому запись защищена тремя условиями сразу.

Условие Что проверяется Что вы увидите, если оно не выполнено
Среда NODE_ENV=production; вне боевого сервера принимается только адрес на этой же машине (localhost, 127.0.0.1, .localhost, .test) «Это не боевой сервер, поэтому запись в настоящий портал заблокирована»
Отдельный вебхук BITRIX24_WRITE_WEBHOOK_URL не совпадает с вебхуком чтения; права нужны только на запись комментариев в сделки «Не задан отдельный вебхук для записи» или «Вебхук для записи совпадает с вебхуком для чтения»
Переключатель «Писать итоги звонков в сделки Битрикса» в «Настройки → Автоматика → Дополнительно → Запись итогов звонков в сделки»; только владелец, с подтверждением ничего не пишется

Автоматический режим этот переключатель никогда не включает. Что и когда пишется:

  • Только для звонков, проверенных после включения переключателя; старые звонки не трогаются. Выключили и включили снова: отсчёт начинается с нового момента.
  • Только в сделку, к которой звонок привязан точной связью (класс EXACT, см. ниже), и только для проверок по этапам разговора; проверки входящих звонков по чек-листу в сделки не пишутся. Проверки, которые были пропущены (слишком короткий звонок, не разговор), и проверки с пометкой о подозрении на подмену результата не пишутся.
  • Один раз на пару «звонок и сделка»: новая проверка или перепроверка после смены правил комментарий не дублирует.
  • Не более пяти комментариев за проход обслуживания (раз в 15 секунд). Сбой повторяется с растущей паузой (минута, две, четыре, восемь); после пяти неудач комментарий оставляется без записи и больше не пишется. Счётчики «Записано», «Ждут очереди», «Повторим позже» и «Оставили без записи» видны в той же карточке.

Текст собирает платформа из сохранённого результата проверки, а не из расшифровки. В нём заголовок с датой звонка и пометкой о том, насколько оценке можно верить («предварительная оценка» по словарям или «черновая оценка» модели, не сверенной с людьми), краткое содержание, сильная сторона, главная ошибка, этапы разговора, возражения и недовольство клиента, причина отказа, балл (если отдел показывает баллы) и ссылка на запись (если задан PUBLIC_BASE_URL).

Что хранится в копии CRM

Хранится Не хранится
сотрудники: имя, должность, подразделения, служба, признак «работает» имя клиента, телефон клиента
воронки и стадии с названиями названия сделок, комментарии, любой свободный текст клиента
сделки: идентификаторы, воронка, стадия, даты, сумма, валюта, идентификаторы лида, компании и контакта карточки контактов и компаний
переходы между стадиями
звонки менеджеров: идентификатор, сотрудник, дата, направление, длительность, признак записи, привязка к CRM, линия компании, страна клиента, код неудачи номер клиента (из него берётся только страна)
дела звонков и связи звонков со сделками

Телефон клиента и имя менеджера хранятся не в копии CRM, а в библиотеке звонков, для тех звонков, чьи записи платформа загрузила. Подробнее: Персональные данные и хранение.

Как звонок связывается со сделкой

Звонок в Битрикс24 обычно привязан к контакту, лиду или компании, а не напрямую к сделке. Поэтому платформа находит сделку через дело звонка в таймлайне и запоминает, насколько надёжна связь.

Класс Когда ставится Надёжность
EXACT дело звонка принадлежит сделке точная связь
OPEN звонок привязан к контакту или компании, у которых в момент звонка была открытая сделка вероятная связь
NEAR звонок привязан к лиду, и платформа берёт сделки, выросшие из него; либо звонок клиента без открытой сделки и сделка создана в течение семи дней после звонка предположение

Если подходит одна сделка, связь основная. Если подходят несколько, платформа сохраняет все, но ни одну не считает основной, и отчёты такие звонки в сделки не засчитывают, чтобы не исказить конверсию. Недавние звонки, у которых связи нет, проверяются повторно в течение 14 дней: дело или сделка могут появиться в портале позже звонка. Звонок без дела в таймлайне остаётся без сделки.

Если Битрикс24 недоступен

Уже сохранённое продолжает работать: библиотека звонков, расшифровки, проверки и отчёты на последних прочитанных данных (в отчётах указано, на какой момент данные Битрикса).

Что делает платформа Что происходит при недоступном портале Что делать
Проверка новых звонков попытка не удаётся, у владельца в углу страницы появляется плашка «Не удалась проверка новых звонков», следующая попытка через выбранный интервал проверить портал и вебхук; проверка возобновится сама
Чтение копии CRM каждый шаг пробуется до трёх раз с растущей паузой, затем чтение получает статус «Ошибка» дождаться портала и нажать «Обновить сейчас»; при включённом ночном обновлении платформа запускает чтение снова сама
Загрузка записи по событию шесть попыток; затем задание остаётся в ошибках очереди «Звонки Битрикс24» на странице очереди нажать «Повторить»
Загрузка истории страница пробуется три раза, затем загрузка получает статус «Ошибка»; уже поставленные записи остаются запустить загрузку снова, уже загруженное пропускается
Запись итогов в сделки пять попыток с растущей паузой, затем «Оставили без записи» ничего: платформа повторяет сама, оставленный комментарий повторно не пишется

Чтение CRM не скачивает записи: они приходят только через проверку новых звонков, загрузку истории или событие вебхука.

См. также