Интеграция нейросети в amoCRM для автоответов и анализа лидов

Менеджеры в amoCRM тратят заметную часть дня на то, чтобы прочитать новую заявку, понять её срочность и решить, что делать дальше. Нейросеть может делать первичный разбор за них: amoCRM сообщает вашему серверу о новой сделке, сервер отправляет описание модели через Zukko, а ответ появляется примечанием в карточке. Ниже — настройка вебхука, токен для API, рабочий обработчик на PHP и расчёт стоимости.

Как работает интеграция amoCRM с нейросетью

1. В amoCRM создаётся сделка → вебхук отправляет её данные на ваш адрес.
2. Обработчик собирает из полей сделки текст для анализа.
3. Текст уходит модели через https://api.zukko.pro/v1/chat/completions.
4. Ответ записывается в сделку примечанием через REST API amoCRM (/api/v4/leads/notes).

В amoCRM лиды называются сделками, поэтому в API и вебхуках это сущность leads.

Шаг 1: вебхук в amoCRM

По документации amoCRM (международная версия — Kommo, API у них общий) вебхуки настраиваются так:

1. Откройте Настройки → Интеграции и нажмите Веб-хуки в правом верхнем углу.
2. Укажите URL обработчика, например https://ваш-сервер.ru/amo-handler.php?key=длинная_случайная_строка.
3. Выберите событие «Сделка добавлена» и сохраните.

Две особенности, от которых зависит код:

• Данные приходят не в JSON, а как обычная форма (application/x-www-form-urlencoded): leads[add][0][id], leads[add][0][name], leads[add][0][custom_fields][...]. В PHP они уже разобраны в $_POST.
• amoCRM ждёт ответ около 2 секунд. Если обработчик не успел или вернул ошибку, вебхук считается недоставленным. Поэтому сначала отвечаем 200, а модель вызываем после.

У вебхуков CRM нет подписи, поэтому добавьте в URL секретный параметр key и проверяйте его в обработчике — иначе кто угодно сможет слать запросы на ваш адрес и тратить баланс.

Шаг 2: токен для API amoCRM

Чтобы записывать примечания, обработчику нужен доступ к API аккаунта. Для интеграции, которая работает только в вашем аккаунте, проще всего долгосрочный токен:

1. В разделе Интеграции создайте собственную (внешнюю) интеграцию.
2. На вкладке ключей и доступов сгенерируйте долгосрочный токен, выбрав срок действия.
3. Сохраните его в переменную окружения сервера.

Токен работает с правами администратора, который его создал, поэтому храните его как пароль. Точные названия кнопок зависят от версии интерфейса — сверяйтесь с документацией для разработчиков amoCRM. Если интеграция будет ставиться в чужие аккаунты, нужна полноценная OAuth-авторизация с обновлением токенов.

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

<?php
// amo-handler.php — обработчик вебхука amoCRM «Сделка добавлена»

if (!hash_equals((string) getenv('AMO_HOOK_KEY'), (string) ($_GET['key'] ?? ''))) {
    http_response_code(403);
    exit;
}

// amoCRM ждёт ответ не дольше ~2 секунд: отвечаем сразу (PHP-FPM)
http_response_code(200);
echo 'OK';
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

Переменные окружения: ZUKKO_API_KEY, AMO_SUBDOMAIN, AMO_TOKEN и AMO_HOOK_KEY (та самая секретная строка из URL вебхука). Названия полей в ALLOWED_FIELDS замените на свои: так в модель уходят только нужные для оценки данные, без контактов клиента.

Если PHP работает не через FPM и fastcgi_finish_request недоступна, сохраняйте входящие события в базу или файл, а обрабатывайте их отдельным скриптом по cron.

Задача вместо примечания

Для срочных сделок удобнее сразу ставить задачу ответственному. Это метод POST /api/v4/tasks:

function addTask(int $leadId, string $text): void
{
    $subdomain = getenv('AMO_SUBDOMAIN');
    $ch = curl_init("https://{$subdomain}.amocrm.ru/api/v4/tasks");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode([[
            'entity_id'     => $leadId,
            'entity_type'   => 'leads',
            'text'          => $text,
            'complete_till' => time() + 3600, // срок — через час
        ]], JSON_UNESCAPED_UNICODE),
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('AMO_TOKEN'),
            'Content-Type: application/json',
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
    ]);
    curl_exec($ch);
}

Чтобы понять, когда ставить задачу, попросите модель начинать ответ со слова «ВЫСОКАЯ», «СРЕДНЯЯ» или «НИЗКАЯ» и проверяйте первое слово в коде.

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

Пример: 50 сделок в день, на каждую около 300 входных и 100 выходных токенов. За день это 50 × 400 = 20 000 токенов, то есть 0,02M.

При 500 сделках в день суммы умножаются на 10: на glm-5.3-flash это $0.24 за 30 дней. Реальное число токенов видно в поле usage ответа и в истории расходов в кабинете. Насколько модель полезна именно для ваших заявок, проверьте на выборке: прогоните 30–50 прошлых сделок с известным результатом через две-три модели и сравните. Параметры запроса — в документации Chat Completions↗.

Персональные данные

В запросе к модели оказываются данные клиентов, поэтому:

1. Отправляйте только поля, нужные для оценки (список ALLOWED_FIELDS в коде). Телефон, email и ФИО для оценки срочности не нужны.
2. Не пишите полные данные сделок в логи — достаточно ID и кода ошибки.
3. Проверьте, что обработка данных внешним сервисом не противоречит вашей политике и согласиям клиентов.

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

Вебхук не приходит — что проверить?

1. Вебхук сохранён и для него выбрано нужное событие.
2. Адрес открывается из интернета по HTTPS.
3. Обработчик отвечает 200 быстрее чем за 2 секунды. Для отладки временно запишите входящие данные в файл: file_put_contents('/tmp/amo.log', print_r($_POST, true), FILE_APPEND);

Как проверить, что токен рабочий?

Запросите список сделок:

curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
  "https://ваш_аккаунт.amocrm.ru/api/v4/leads?limit=1"

Ответ с данными означает, что токен действует; 401 — токен неверный или истёк.

Примечания не добавляются — почему?

Посмотрите error_log: amoCRM возвращает код и описание ошибки. Частые причины — неверный поддомен, истёкший токен или ID сделки, к которой у владельца токена нет доступа.

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

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