Как подключить WhatsApp к CRM через API и вебхуки

Общая схема

Обработчик нужен, потому что CRM не знает формата нашего API, а мы — формата вашей CRM. Обычно это несколько десятков строк кода или сценарий из пары блоков в n8n или Make.

Из CRM в WhatsApp

Типичные случаи: заказ подтверждён — клиенту уходит сообщение; сделка перешла на этап «Счёт выставлен» — клиент получает PDF; запись создана — приходит подтверждение.

Как это устроено:

1. В CRM настраиваете событие: робот или исходящий вебхук на этапе воронки. В amoCRM это действие «Webhook» в цифровой воронке, в Bitrix24 — робот «Webhook» в автоматизации или исходящий вебхук на события сделок. Точные названия сверяйте с документацией вашей CRM.
2. CRM отправляет запрос на адрес обработчика. Часто в нём только id сделки — тогда обработчик сам запрашивает у CRM телефон и данные по её API.
3. Обработчик приводит телефон к формату API и вызывает POST /messages/send. Параметры отправки — в документации.

Телефоны в CRM хранятся как попало: «+7 (701) 123-45-67», «8 701 123 4567», «7011234567». API нужен номер цифрами с кодом страны, а «8» в начале для API — не код Казахстана, сообщение уйдёт не туда. Нормализуйте:

function normalizePhone(raw) {
  let d = String(raw || "").replace(/\D/g, "");                  // только цифры
  if (d.length === 11 && d.startsWith("8")) d = "7" + d.slice(1); // 8 701… → 7 701…
  if (d.length === 10) d = "7" + d;                                // 701… → 7701…
  return d.length >= 11 && d.length <= 15 ? d : null;              // иначе — не номер
}

Если не уверены, что у клиента есть WhatsApp, проверьте номер через POST /contacts/check до первой отправки — до 200 проверок в сутки на номер. Меньше ошибок доставки — выше индекс доверия номера.

Из WhatsApp в CRM

Чтобы переписка из WhatsApp попадала в CRM, обработчик принимает вебхуки. Клиент пишет на ваш номер — событие message приходит на обработчик. Дальше:

1. Проверить секрет в адресе (?token=…) — подписи у вебхука нет.
2. Сразу ответить 200: на ответ есть 10 секунд, а запросы к CRM бывают медленными.
3. Взять телефон из payload.from (77011234567@c.us). Группы (@g.us) обычно пропускают.
4. Найти контакт в CRM по телефону. Надёжнее сравнивать по последним 10 цифрам: так совпадут и «+7 701…», и «8 701…».
5. Нашли — добавить примечание в сделку или комментарий в таймлайн. Не нашли — создать лид.

Не создавайте лид на каждое сообщение: клиент пишет «Здравствуйте», «Сколько стоит?», «Есть в наличии?» — это один лид и три примечания.

app.post("/wapi/hook", express.json(), async (req, res) => {
  if (req.query.token !== process.env.WAPI_HOOK_TOKEN) return res.sendStatus(403);
  res.sendStatus(200);                               // ответили сразу, дальше — CRM
  const e = req.body;
  if (!["message", "message.out"].includes(e.event)) return;
  const chat = e.payload.from;                        // чат всегда в from — и у message, и у message.out
  if (!chat || !chat.endsWith("@c.us")) return;      // только личные чаты
  const phone = chat.split("@")[0];
  const author = e.event === "message" ? "Клиент" : "Менеджер (с телефона)";
  const text = e.payload.hasMedia ? `${e.payload.body || ""} [вложение: GET /messages/${e.wapi.message_id} → media.url]` : e.payload.body;
  try {
    const contact = await crm.findContactByPhone(phone.slice(-10)); // ваш запрос к API CRM
    if (contact) await crm.addNote(contact, `${author}: ${text}`);
    else if (e.event === "message") await crm.createLead({ phone, text });
  } catch (err) {
    console.error("crm:", err.message);              // повтора не будет — логируйте
  }
});

crm.findContactByPhone, crm.addNote и crm.createLead — ваши функции поверх API CRM. В amoCRM это REST API v4 (/api/v4/leads, примечания /api/v4/leads/{id}/notes), в Bitrix24 — методы crm.lead.add и crm.timeline.comment.add через входящий вебхук. Детали полей сверяйте с документацией CRM.

Вебхуки не отправляются повторно. Если обработчик был недоступен, догрузите пропущенное из журнала: GET /messages?since=… — подробнее в гайде про историю сообщений.

Авторство: кто написал

Номер остаётся на телефоне, поэтому в одном чате пишут и CRM, и менеджер, и клиент. Чтобы в карточке было понятно, кто что сказал:

Сообщения, отправленные через API, отдельным вебхуком не приходят — вы и так знаете о них из ответа на запрос. Поэтому примечание «Отправлено клиенту: …» обработчик пишет в CRM сразу после POST /messages/send. Значения поля — в разделе source.

Ключ номера для подрядчика

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

Если номеров несколько — например, «Продажи» и «Сервис», — у каждого свой вебхук, а в событии есть wapi.number_id: обработчик поймёт, в какую воронку писать.

Где держать обработчик

• Свой сервер или облачная функция. Полный контроль и любая логика. Нужен публичный адрес по https, перенаправления мы не выполняем.
• n8n без кода. Узел Webhook принимает событие, HTTP Request отправляет запрос в CRM или в wapi.kz.
• Make без кода. Модули Webhooks → Custom webhook и HTTP → Make a request.
• Google Таблицы как мини-CRM. Веб-приложение Apps Script отвечает перенаправлением, поэтому вебхук лучше принимать через n8n или Make и писать в таблицу оттуда.
• 1С. Входящие — через HTTP-сервисы опубликованной базы или промежуточный скрипт, отправка — встроенными HTTPСоединение и HTTPЗапрос.

Что честно не получится

• Переписка не появится в окне чатов CRM как встроенный канал. Окна чатов в CRM работают через отдельные приложения-коннекторы, у нас их нет. Сообщения попадут в карточку примечаниями или комментариями.
• Операторского чата у нас нет. Менеджеры отвечают с телефона или из WhatsApp Web. Можно сделать в CRM кнопку или робота, который отправит ответ через API.
• Готовых модулей в маркетплейсах CRM нет. Только API и вебхуки.
• Файлы не приходят в самом вебхуке. В событии — признак hasMedia: true, а файл сохраняется у нас и через несколько секунд доступен по ссылке media.url в GET /messages/{id}. Чтобы он попал в карточку CRM, заберите его по этой ссылке и загрузите в CRM.
• Отправки в группы через API нет — только личные чаты.

Настроим за вас

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