Webhook из Telegram-бота в CRM: как передавать лиды без потери контекста

Webhook из Telegram-бота в CRM нужен не для галочки в интеграциях, а чтобы не потерять момент, когда человек стал лидом: оставил телефон, нажал кнопку покупки, прошел квалификацию, оплатил или попросил менеджера. Правильный вебхук передает в CRM не только имя и телефон, а событие, Telegram ID, источник, статус, ответы пользователя и ссылку на дальнейшее действие.

Короткий вывод: если CRM нужна только как таблица лидов, хватит одного исходящего HTTP-запроса из сценария. Если CRM должна запускать бота обратно, нужен входящий API-вебхук с ключом события и идентификатором контакта. Если продажи идут прямо в Telegram, часто проще держать CRM-слой внутри Strelo и отправлять наружу только те события, которые действительно нужны внешней системе.

Сначала разделите три разных вебхука

В одном запросе люди часто смешивают три вещи. Первая - служебный webhook Telegram Bot API, по которому Telegram присылает платформе входящие сообщения. Его обычный пользователь конструктора не настраивает вручную: он подключает токен бота, а платформа регистрирует и обслуживает этот вход.

Вторая - исходящий запрос из сценария. Бот дошел до шага, собрал телефон или email и отправил POST в CRM. Именно это чаще всего имеют в виду, когда говорят: "нужно передать лида из Telegram-бота в CRM".

Третья - входящий API-вебхук в сторону платформы. CRM, сайт, платежка или свой backend отправляет в Strelo событие, например order_paid или demo_booked, а опубликованная воронка запускается для найденного контакта.

Если не разделить эти маршруты, проект быстро ломается. Маркетолог ждет, что "вебхук Telegram" создаст сделку в CRM. Разработчик настраивает endpoint Telegram Bot API, хотя бизнесу нужен обычный POST с лидом. Менеджер видит в CRM контакт без Telegram ID и не может вернуть человека в бот. Поэтому начинать нужно не с URL, а с вопроса: какое событие передаем и кто должен отреагировать.

Когда достаточно исходящего запроса в CRM

Исходящий запрос подходит, если сценарий в Telegram уже собрал нужные данные и должен просто сообщить их CRM. Например, пользователь нажал "Хочу консультацию", ответил на три вопроса, оставил телефон и согласился на связь. В этот момент бот отправляет в CRM payload с именем, телефоном, Telegram ID, тегом интереса, источником и временем.

В Strelo для этого используется действие "Внешний запрос (API)". Оно отправляет HTTP-запрос на публичный адрес, поддерживает GET, POST, PUT и DELETE, заголовки, JSON-тело и сохранение ответа в переменную. Это не требует писать отдельный сервер, если CRM уже умеет принимать webhooks или имеет API.

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

Контракт payload: что отправлять в CRM

Хороший payload не должен быть огромным. Но он должен позволить CRM однозначно понять, кто это, что случилось и что делать дальше. Минимальный набор: event, telegram_id, phone или email, name, source, status, answers, occurred_at и stable_id для идемпотентности.

Если у вас есть только username, интеграция будет хрупкой. Username можно сменить, он может отсутствовать, а менеджер не всегда сможет написать человеку напрямую. Telegram ID надежнее для связи внутри бота, phone и email лучше для CRM и внешних продажных процессов, external_id полезен, если контакт уже существует в другой системе.

Отдельно решите, что делать с UTM и источником. Если реклама ведет в Telegram, CRM должна получить не просто "лид из бота", а campaign, content, объявление или хотя бы короткую ссылку. Иначе отдел продаж видит заявки, но маркетинг не понимает, какая реклама дала нормальные лиды.

Как обрабатывать ответ CRM

Не все CRM только принимают данные. Иногда они возвращают статус: сделка создана, дубль найден, нужен другой менеджер, лимит достигнут, ошибка авторизации. Если ответ важен для сценария, сохраните его в переменную и поставьте после HTTP-запроса условие.

Например, CRM вернула статус ok. Бот отвечает: "Заявка принята, менеджер напишет". Если вернулась ошибка, бот может предложить ручной контакт или перевести диалог оператору. Сценарий не должен молча продолжаться так, будто внешняя система всегда доступна.

В Strelo HTTP-запрос не должен останавливать всю воронку навсегда. Поэтому важно заранее продумать fallback: если endpoint не ответил, не обещайте пользователю, что заявка точно создана. Лучше сказать, что данные приняты в чате, поставить тег "проверить вручную" и уведомить оператора.

Входящий API-вебхук: когда CRM запускает бота обратно

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

В Strelo для такого сценария есть пользовательская API-ссылка вида /api/hooks/<token>. Внешняя система отправляет POST с полем event и идентификатором контакта. Идентификатором может быть contact_id, telegram_id, email, username, external_id, phone или другой параметр, который сопоставляется с контактом.

В панели триггера "Внешнее событие (API)" задается ключ события. Если CRM отправила event = order_paid, сработает опубликованная воронка с таким ключом. Все поля payload становятся переменными сценария, поэтому можно сразу использовать сумму, тариф, product_id, имя менеджера или ссылку на доступ.

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

Безопасность вебхуков

Вебхук - это публичный URL. Если на него можно отправить что угодно без проверки, любой человек сможет создать фальшивое событие, запускать воронки, отмечать оплаты или засыпать CRM мусором. Минимальная защита: секрет в заголовке, проверка event, ограничение публичных URL для исходящих запросов, логирование и идемпотентность.

В Strelo пользовательский API-вебхук закрыт секретным token в URL. Если у вебхука задан дополнительный secret, он проверяется через заголовок X-Strelo-Secret или Bearer. Для исходящих HTTP-запросов используется защита от внутренних адресов: нельзя дергать localhost, приватные сети и служебные адреса облака. Это важно, потому что URL задает пользователь, а запрос выполняет сервер.

Секрет не должен жить в тексте сообщения, в названии события или в query-параметре, который копируется в чаты. Держите его в заголовке. Если секрет утек, ротируйте его и не пытайтесь "замаскировать" старый URL.

Идемпотентность: один лид не должен стать пятью

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

Используйте stable_id: order_id, lead_id, payment_id или другой внешний ID события. CRM должна обновлять известную запись, а не создавать новую. Бот тоже должен понимать, что повторный order_paid по тому же заказу не должен повторно выдавать доступ и запускать дожим.

Если CRM не умеет отдавать стабильный ID, создайте свой event_id на стороне сценария. Главное правило: timestamp не подходит как главный ключ. Каждый повтор получит новый timestamp и будет выглядеть как новое событие.

Какие данные не стоит отправлять

Не передавайте в CRM все подряд. Лишние данные повышают риск утечки и усложняют поддержку. Для лида обычно достаточно контакта, источника, статуса, выбранного продукта и ответов на квалификационные вопросы. Паспортные данные, токены, полные переписки и внутренние промпты модели не должны уходить в обычный webhook.

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

Частые ошибки при связке бота и CRM

Самая дорогая ошибка - передавать только phone и забыть Telegram ID. Пока менеджер работает в CRM, все нормально. Как только нужно вернуть клиента в бот, оказывается, что связать сделку с Telegram-контактом невозможно.

Вторая ошибка - делать один event для всего. lead, qualified, manager_needed, order_paid и refund - разные события. Если все назвать update, воронка не сможет понять, что делать.

Третья ошибка - не проверять негативный путь. Все тестируют успешную заявку, но никто не проверяет 401, таймаут, дубль, пустой телефон, выключенный webhook, неверный secret и повторную доставку события.

Как это выглядит в Strelo

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

Если у вас уже есть CRM, Strelo становится Telegram-слоем вокруг нее. Бот собирает данные без кода, отправляет в CRM нормальный payload, получает ответ и продолжает сценарий. CRM может вызвать входящий API-вебхук, чтобы запустить следующую ветку в Telegram.

Практичная hybrid-схема выглядит так: Strelo хранит Telegram-диалог, теги, текущий шаг, ответы пользователя, оплату и быстрые действия менеджера, а внешняя CRM получает итоговые события для отчетности, задач и long-term учета. Так вы не превращаете CRM в архив каждого сообщения, но и не оставляете отдел продаж без контрольной системы. Если позже понадобится заменить CRM, Telegram-воронки и база контактов не разваливаются, потому что главный пользовательский путь остается в Strelo, а внешний контур получает согласованные события.

Чеклист перед запуском

Перед публикацией пройдите путь на тестовом контакте. Создайте заявку в боте, проверьте, что CRM получила event, contact_id или telegram_id, phone, email, source и status. Затем отправьте ответ CRM с ошибкой и убедитесь, что бот не обещает невозможное.

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

Итог

Webhook из Telegram-бота в CRM - это не просто "вставить URL". Это контракт между событием, контактом, статусом и следующим действием. Сначала определите, где рождается событие. Потом выберите маршрут: исходящий HTTP-запрос в CRM, входящий API-вебхук обратно в Strelo или CRM внутри самой Telegram-платформы.

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