Интеграция нейросети в Bitrix24 через вебхуки и API

В Битрикс24 каждый день приходят лиды с сайта, из форм и мессенджеров, и менеджер тратит время, чтобы прочитать заявку и понять, насколько она срочная. Интеграция Битрикс24 с нейросетью снимает эту рутину: при появлении лида ваш сервер отправляет его описание модели, а ответ — приоритет и совет менеджеру — появляется комментарием в карточке. Ниже — схема на вебхуках, обработчик на PHP, вариант на Python и расчёт стоимости.

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

В Битрикс24 два вида вебхуков, и понадобятся оба:

• Входящий вебхук — секретный адрес, через который ваш код вызывает методы REST API портала (прочитать лид, добавить комментарий).
• Исходящий вебхук — Битрикс24 сам отправляет POST-запрос на ваш адрес, когда происходит событие, например создание лида.

Цепочка выглядит так:

1. Создан лид → исходящий вебхук присылает на ваш обработчик событие ONCRMLEADADD с ID лида.
2. Обработчик через входящий вебхук получает данные лида методом crm.item.get.
3. Обработчик отправляет описание заявки модели через Zukko.
4. Ответ модели записывается в таймлайн лида методом crm.timeline.comment.add.

Важная деталь: исходящий вебхук присылает только идентификатор объекта, а не все поля лида. Поэтому шаг 2 обязателен.

Шаг 1: входящий вебхук

Вебхуки создаются в разделе для разработчиков в меню «Приложения» (в англоязычной документации Битрикс24 — Applications → Developer resources → Other). Названия пунктов зависят от версии интерфейса.

1. Выберите «Входящий вебхук».
2. В правах доступа отметьте CRM (scope crm).
3. Сохраните и скопируйте адрес вида https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxx/. Здесь 1 — ID сотрудника, от имени которого выполняются запросы, а xxxxxxxx — секретный код.

Этот адрес даёт доступ к CRM с правами сотрудника — храните его как пароль, только в переменных окружения сервера.

Шаг 2: исходящий вебхук

1. В том же разделе выберите «Исходящий вебхук».
2. Укажите URL обработчика, например https://ваш-сервер.ru/b24-handler.php. Адрес должен быть доступен из интернета по HTTPS, localhost и самоподписанные сертификаты не подойдут.
3. Выберите событие создания лида (ONCRMLEADADD).
4. Сохраните токен, который покажет Битрикс24: по нему обработчик проверяет, что запрос пришёл именно с вашего портала.

Шаг 3: обработчик на PHP

Битрикс24 присылает данные как обычную форму (application/x-www-form-urlencoded), поэтому в PHP они уже разобраны в $_REQUEST: event, data[FIELDS][ID], auth[application_token].

<?php
// b24-handler.php — обработчик исходящего вебхука Битрикс24

$expectedToken = (string) getenv('B24_OUTGOING_TOKEN');
$event  = $_REQUEST['event'] ?? '';
$token  = (string) ($_REQUEST['auth']['application_token'] ?? '');
$leadId = (int) ($_REQUEST['data']['FIELDS']['ID'] ?? 0);

if ($expectedToken === '' || !hash_equals($expectedToken, $token)) {
    http_response_code(403);
    exit;
}

// Отвечаем сразу, а модель вызываем уже после ответа (работает в PHP-FPM)

Что здесь важно:

• Проверка токена. hash_equals сравнивает токен из запроса с тем, что выдал Битрикс24. Без этой проверки любой, кто узнает адрес обработчика, сможет запускать его и тратить ваш баланс.
• Быстрый ответ. Битрикс24 не должен ждать, пока ответит модель. fastcgi_finish_request() отдаёт ответ сразу и продолжает работу в фоне. Если PHP работает не через FPM, вынесите обработку в очередь или cron.
• Методы REST. crm.item.get с entityTypeId = 1 — универсальный метод чтения элемента CRM (старый crm.lead.get в документации помечен как устаревший). crm.timeline.comment.add принимает параметры в ключе fields строчными буквами.
• Персональные данные. В модель уходят только название, источник и комментарий. Телефон и email для оценки приоритета не нужны.

Переменные окружения: ZUKKO_API_KEY, B24_WEBHOOK_URL (адрес входящего вебхука) и B24_OUTGOING_TOKEN (токен исходящего).

Шаг 4: проверка

Отправьте обработчику тестовое событие с ID существующего лида:

curl -X POST https://ваш-сервер.ru/b24-handler.php \
  -d 'event=ONCRMLEADADD' \
  -d 'data[FIELDS][ID]=123' \
  -d 'auth[application_token]=ваш_токен'

Через несколько секунд в таймлайне лида 123 должен появиться комментарий. Если его нет, смотрите error_log: там будут коды ответа Zukko (401 — неверный ключ, 402 — закончился баланс, 429 — слишком часто) или ошибки REST Битрикс24.

Вариант на Python

Тот же обработчик на Flask. Ответ Битрикс24 отдаём сразу, а работу с моделью запускаем в отдельном потоке:

import hmac
import os
import threading

import requests
from flask import Flask, request

app = Flask(__name__)
B24_URL = os.environ["B24_WEBHOOK_URL"].rstrip("/")
B24_TOKEN = os.environ["B24_OUTGOING_TOKEN"]


def b24(method: str, params: dict) -> dict:
    return requests.post(f"{B24_URL}/{method}.json", json=params, timeout=15).json()

Поток подходит для небольшого потока лидов. При сотнях событий в час используйте очередь задач (Celery, RQ и т.п.), чтобы не потерять задания при перезапуске сервера.

Сколько стоит

Пример: 200 лидов в день, на каждый около 300 входных и 150 выходных токенов. За день это 200 × 300 = 60 000 входных и 200 × 150 = 30 000 выходных токенов, всего 0,09M.

Реальное число токенов видно в поле usage ответа и в истории расходов в кабинете. Насколько хорошо модель оценивает именно ваши заявки, проверьте на выборке: возьмите 30–50 прошлых лидов с известным исходом и сравните оценки двух-трёх моделей. Параметры запроса — в документации Chat Completions↗.

Частые вопросы

Комментарий не появляется — что проверить?

1. Доходит ли запрос до обработчика: посмотрите логи веб-сервера. Адрес должен открываться из интернета по HTTPS.
2. Совпадает ли токен auth[application_token] с токеном исходящего вебхука.
3. Есть ли у входящего вебхука право CRM и доступ сотрудника к лиду.
4. Что вернул Zukko: код и текст ошибки пишутся в error_log.

Как обрабатывать не только новые лиды?

Добавьте в исходящий вебхук другие события, например изменение лида (ONCRMLEADUPDATE) или создание сделки, и разветвите обработку по полю event. Для сделок используйте entityTypeId = 2 и ENTITY_TYPE = deal. Следите, чтобы ваш же комментарий не запускал обработку заново.

Можно ли обойтись без своего сервера?

Нужен любой публичный HTTPS-адрес, который примет вебхук и сделает два HTTP-запроса: это может быть хостинг с PHP, облачная функция или сервис автоматизации с поддержкой вебхуков. Сам код при этом небольшой — как в примерах выше.

Где взять ключ и как ограничить расходы?

Создайте отдельный ключ для Битрикс24 в кабинете Zukko↗, задайте ему дневной лимит и разрешите только нужную модель. Если что-то пойдёт не так, например обработчик зациклится, лимит остановит расходы. Подробнее — в разделе о лимитах ключей↗.