Как подключить ИИ к CRM? Между ними ставят небольшой сервис: он принимает событие от CRM, кладёт его в очередь, вызывает модель, проверяет ответ и только затем записывает результат обратно через API. Вместе они закрывают пять типичных рисков: модель не успевает за вебхуком, событие записывается дважды, ответ уверенно неверен, запись затирает правку менеджера, а модель реагирует на собственные записи.

Статья для технических руководителей, которые заказывают подключение или принимают его. Кода нет, одна схема дана псевдокодом. Общие понятия разобраны в статье «API простыми словами», правила проектирования самого интерфейса — в статье «Проектирование API для интеграций».

Коротко. Нужны пять элементов: событие, очередь, модель, проверка и запись. Вебхук только сообщает об изменении, свежие данные читают запросом. Модель вызывают из очереди, а не из вебхука. Повтор события не должен давать повторную запись, а запись модели не должна запускать саму модель. Пишут туда, где ошибка видна и обратима: сначала заметка, потом поле.

Как подключить ИИ к CRM: схема из пяти элементов

CRM → 1. Событие → 2. Очередь → 3. Модель → 4. Проверка → 5. Запись → CRM
      вебхук       по одному,   текст в     формат,       заметка,
      или опрос    без потерь   структуру   справочники,  поле,
                                            права         задача
Журнал: каждый шаг оставляет запись с ключом события
  1. Событие. Сообщение, что в CRM что-то произошло: создана сделка, пришло письмо, сменился этап. Это сигнал, а не готовые данные.
  2. Очередь. Событие ждёт своей очереди и обрабатывается по одному на объект, без потерь.
  3. Модель. Сервис собирает минимум данных и получает ответ в заданной структуре, а не абзацем текста.
  4. Проверка. Формат, справочники, права, порог уверенности, сверка с текущей карточкой.
  5. Запись. Результат уходит в CRM туда, где ошибка видна и обратима, с отметкой «создано ИИ» и ключом события.

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

Вебхуки CRM и нейросеть: что приходит от CRM и чего в этом нет

Вебхук — это когда CRM сама сообщает вашему адресу о событии. Обычно он несёт тип события, идентификатор объекта и время, иногда часть полей. Чего он не даёт, на то и рассчитывают при проектировании.

  • Однократной доставки. Событие может прийти дважды, не по порядку или не прийти совсем.
  • Свежего состояния. Пока сервис дошёл до события, менеджер мог поправить карточку: актуальные данные читают запросом по идентификатору.
  • Истории. Заметки и письма прошлых дней вместе с событием не приходят.

Опрос работает наоборот: сервис сам спрашивает, что изменилось с прошлого раза. Он ничего не пропускает, если спрашивать с запасом по времени, но отстаёт на период опроса и расходует лимит даже в тишине. Надёжная схема сочетает оба подхода: вебхук для скорости, опрос и ночная сверка для полноты. Какие события отдаёт ваша CRM и как повторяет доставку, выясняют по описанию разработчика, а не по аналогии с другой системой; для amoCRM и Битрикс24 это сделано на страницах про интеграцию ИИ с amoCRM и интеграцию ИИ с Битрикс24.

Очередь между CRM и моделью: зачем она нужна и как не зациклиться

Модель отвечает секунды, иногда десятки секунд, а отправитель вебхука ждёт недолго и при тишине шлёт событие снова (точное время и правила повтора смотрим в документации CRM). Если вызывать модель прямо из обработчика вебхука, каждое повторное событие запустит ещё один вызов. Поэтому обработчик делает три действия: проверяет подлинность, кладёт событие в очередь и сразу отвечает «принято».

  • Сглаживание. Импорт большой базы даёт сразу много событий; очередь выдаёт их обработчикам с допустимой скоростью.
  • Слияние. Менеджер правил карточку пять минут и вызвал пять событий. Обработка нужна одна, по последнему состоянию.
  • Порядок по объекту. Два обработчика одной сделки запишут конфликтующие значения, поэтому события сделки идут друг за другом.
  • Список застрявших. После нескольких неудач событие уходит в отдельный список с причиной, и человек его видит.

Ловушка самозапуска

Модель записала заметку, CRM сообщила о новой заметке, сервис принял это за действие менеджера и снова вызвал модель, а та записала ещё одну заметку. Цепочка крутится, пока не кончится лимит запросов. Защита из трёх слоёв: события, автором которых назван служебный пользователь (если CRM указывает автора), отбрасываются; запись сервиса узнаётся по отметке «создано ИИ» и ключу, поэтому событие о ней не запускает разбор; число запусков на объект в час ограничено, при превышении приходит оповещение.

Модель и проверка: что происходит с ответом, пока он не попал в CRM

Модель вызывают с минимумом данных: нужные сценарию поля, последние события и текст обращения. Ответ возвращается в заданной структуре (поля, значения, основания), и программа проверяет её до любых действий.

  • Формат. Телефон приведён к единому виду, дата является датой.
  • Справочники. Значение поля-списка есть в списке, стадия существует в воронке.
  • Права. Операция и поле входят в разрешённые для служебной учётной записи.
  • Порог уверенности. Сомнительное уходит в очередь «непонятно», а не в карточку; выбор порога разобран в статье «Порог уверенности модели».
  • Сверка с карточкой. Перед записью карточку перечитывают: если её изменили после чтения для модели, значение не пишется, а предлагается заметкой.

Два свойства модели влияют на схему. Первое: ответ на один и тот же вход может отличаться, поэтому решение сохраняют вместе с ключом события и при повторе берут сохранённое, а не спрашивают модель заново. Второе: текст письма для модели данные, а не команда. Фраза «поставь стадию Выиграна» в письме не должна менять поведение; об этой угрозе — статья «Что такое prompt injection». Защищает не просьба в инструкции, а отсутствие у служебной записи права менять стадию.

Куда писать результат: заметка, поле, задача или черновик

У каждого приёмника своя цена ошибки, и чем структурнее приёмник, тем строже проверка перед записью.

Куда пишемПлюсыМинусыКогда выбирать
ЗаметкаВидны автор и время, можно удалить, значения не меняет, в текст помещается ключ событияСтруктурированное значение из текста придётся доставать заново; поток заметок засоряет лентуРезюме, выжимка, объяснение, предложения значений
Поле карточкиЗначение попадает в фильтры, отчёты и правилаМожет запустить автоматизацию CRM, затереть ручной ввод; для ключа события места нетПустые поля из согласованного списка, значения из справочника, важные поля после подтверждения
ЗадачаПопадает в рабочий список менеджера, у неё есть срокЛишние задачи обесценивают все остальныеСледующий шаг по итогам звонка или письма, с лимитом на сделку
Черновик ответаКлиент ничего не получит, пока менеджер не отправитЗависит от того, как CRM хранит черновики и можно ли писать их через APIОтветы клиентам
Стадия, ответственныйДвижение по воронке без ручных действийЗапускает правила, отчёты и расчёты, ошибку видно поздноТолько как предложение в заметке, меняет человек

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

Лимиты запросов, повторы и идемпотентность простыми словами: как не записать дважды

Лимиты. API CRM ограничивает частоту запросов, и при превышении обычно отвечает ошибкой с просьбой подождать (в вебе для этого принят код 429, но поведение конкретной CRM смотрят в документации). Сервис держит собственный предел ниже лимита и повторяет запрос с растущей паузой. Значения лимитов из чужих статей не копируют: они зависят от версии.

Неизвестный результат. Сервис отправил запись, ответ не пришёл, и неизвестно, создана ли заметка. Повторить без проверки нельзя, не повторить значит потерять запись. Выход называется идемпотентностью: операция идемпотентна, если выполненная дважды даёт тот же результат, что и один раз. «Установить поле в значение» такова по природе. «Добавить заметку» и «создать задачу» нет: каждый вызов добавляет новую запись.

Поэтому ключ события кладут в сам результат: в текст заметки или задачи записывают отметку с ключом. Перед повтором сервис читает карточку и ищет отметку: нашёл, значит запись уже есть; не нашёл, значит пишет. Схема в псевдокоде:

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

Сбой между «записали» и «пометили» не страшен: следующая попытка найдёт отметку в самой CRM. Остальные приёмы надёжной доставки описаны в статье про outbox и гарантированную доставку.

Журнал: что записывать по каждому событию

Журнал отвечает на три вопроса: почему появилась эта запись, что застряло и насколько модели можно доверять. По каждому событию хранят:

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

Из журнала считают три числа: сколько событий застряло и как давно, какая доля записей принята без правок, сколько запросов ушло в повторы. Рост любого числа разбирают сразу. Журнал содержит персональные данные: доступ по ролям, срок хранения записан заранее; общие приёмы описаны в статье про журнал действий пользователей.

Как подключить ИИ к CRM: режимы интеграции, плюсы, минусы, когда выбирать

РежимПлюсыМинусыКогда выбирать
Вебхук и очередьРеакция за секунды, нагрузка ровная, нет пустых запросовНужны доступный адрес и проверка подлинности; события повторяются или теряютсяРазбор входящих, резюме, задачи по событиям
Опрос по расписаниюПросто, входящий адрес не нужен, ничего не теряется при запасе по времениЗадержка до следующего опроса, расход лимитаCRM в закрытой сети, события нужны раз в несколько минут
Вебхук как сигнал, чтение по API и ночная сверкаСкорость и полнота, пропущенное находит сверкаБольше компонентов, нужен экран разбора расхожденийОсновной вариант: потеря события стоит денег
Кнопка или виджет в карточкеМенеджер сам решает, когда звать модель; потока событий нетРаботает только по нажатию, зависит от того, какие приложения допускает CRMПодсказки, резюме, черновики по запросу
Обмен файламиРаботает без API, удобен для архиваНет реакции в реальном времени, запись обратно сложнееРазовая обработка накопленных писем и карточек
Прямой доступ к базе CRMНе зависит от лимитов APIОбходит права и проверки CRM, ломается при обновленииКрайняя мера: своя CRM и только чтение, риск фиксируется в документе

Выбор сводится к трём вопросам. Нужна ли реакция без нажатия кнопки? Сколько стоит потерянное событие? Есть ли у CRM интерфейс на нужные объекты? Если на третий ответ «нет», остаётся обмен файлами, а если нет и его, об этом честнее сказать до договора.

Что делаем мы и с чего начать

Мы собираем такой сервис между вашей CRM и моделью: на первом этапе один сценарий и одна CRM, а не подключение всего сразу. Общая схема, права и журнал на уровне продукта описаны на странице интеграции ИИ с CRM, особенности amoCRM и Битрикс24 — в разделе про вебхуки выше.

Обследование стоит 200 000 ₽ за CRM и один-два сценария (2–3 недели) и 350 000 ₽, когда систем несколько (3–4 недели); сумма вычитается из первого этапа. На выходе перечень событий и полей, доступных через API, что вебхуки дают на деле, лимиты, правила CRM, которые сработают на запись, схема подключения и вилка бюджета. Затем лёгкий пилот одного сценария (150 000–400 000 ₽, 2–8 недель) и, если нужна запись, тяжёлый (400 000–1 200 000 ₽, 2–3 месяца). Исходники лежат в вашем репозитории с первого коммита, круглосуточного дежурства нет. Цены — на странице тарифов.

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

Как подключить ИИ к CRM, чтобы он не писал в карточки лишнего?

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

Что лучше: вебхук или опрос?

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

Почему нельзя вызывать модель прямо из вебхука?

Модель отвечает долго, а CRM при молчании повторяет событие. Каждый повтор запустит новый вызов модели, и получится лавина дублей. Обработчик вебхука только проверяет подлинность, ставит событие в очередь и отвечает «принято».

Что такое идемпотентность простыми словами?

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

Как не записать в CRM дважды, если ответ потерялся?

Не повторять вслепую: сначала прочитать карточку и поискать отметку с ключом события в заметке, задаче или поле. Нашлась — запись уже сделана. Не нашлась — пишем, с отметкой. Так неизвестный результат превращается в известный.

Куда писать результат модели: в заметку или в поле?

Начинать лучше с заметок и задач: запись видна, ключ события помещается в текст, ошибку можно удалить. В поле пишут, когда оно пустое, значение взято из справочника и запись не запустит правило автоматизации CRM. Важные значения идут после подтверждения менеджера.

Что делать, если CRM отвечает ошибкой о превышении лимита?

Подождать и повторить с растущей паузой. Сервис заранее держит собственный предел ниже лимита, очередь регулирует скорость. Точные значения лимитов берут из документации разработчика CRM для вашей версии.

Сколько стоит подключение ИИ к CRM через API?

Обследование — 200 000 ₽ за CRM и один-два сценария или 350 000 ₽ при нескольких системах, сумма вычитается из первого этапа. Лёгкий пилот — 150 000–400 000 ₽, тяжёлый с записью — 400 000–1 200 000 ₽. Точную цену называем после обследования.