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

Это руководство для CTO, архитекторов решений и администраторов CRM, которым нужно, чтобы CRM и омниканальный инбокс показывали единую картину клиента. Здесь объясняется, какие события синхронизировать, как построить приёмник вебхуков, устойчивый к повторам и дубликатам, как сопоставлять контакты в WhatsApp, Instagram и электронной почте и какие правила приватности влияют на архитектуру.

Какими данными должны обмениваться CRM и омниканальный инбокс?

Инбокс должен сообщать CRM, кто обратился, по какому каналу, по какому вопросу и с каким результатом. CRM должна сообщать инбоксу, кто этот клиент, кто за него отвечает и какой контекст нужен операторам.

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

На какие события вебхуков стоит подписаться?

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

• Диалог создан — первое сообщение клиента в любом канале.
• Сообщение получено — входящее сообщение клиента с каналом и идентификатором отправителя.
• Сообщение отправлено — исходящее сообщение оператора или шаблон.
• Статус сообщения — отправлено, доставлено, прочитано или не доставлено, если канал сообщает об этом.
• Диалог назначен — изменился ответственный или очередь.
• Диалог закрыт или открыт повторно — смена статуса.
• Контакт обновлён — в инбоксе изменились идентификаторы или атрибуты.

В случае WhatsApp вебхуки самой Meta передают платформе входящие сообщения и обновления статусов исходящих сообщений, а ваш провайдер инбокса затем отдаёт вашим системам собственные события.

Как построить надёжный приёмник вебхуков?

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

Пошаговая схема приёмника

1. Откройте один HTTPS endpoint для каждого окружения, например /webhooks/inbox.
2. Проверьте подлинность. Проверьте подпись (обычно это HMAC от исходного тела запроса с общим секретом, как определено в RFC 2104) или токен, который описывает отправитель. Вычисляйте её по исходным байтам до разбора JSON.
3. Проверьте актуальность. Если передаётся временная метка, отклоняйте события за пределами короткого допуска, чтобы ограничить повторное воспроизведение.
4. Дедуплицируйте. Вставляйте ID события в таблицу с ограничением уникальности. Если вставка не удалась, потому что ID уже существует, верните успешный ответ и остановитесь.
5. Поставьте в очередь. Поместите событие в очередь и сразу верните ответ 2xx.
6. Обрабатывайте асинхронно. Воркер читает очередь, сопоставляет контакт и записывает данные в CRM через upsert.
7. Повторяйте с задержкой. Если CRM недоступна, повторяйте попытки из своей очереди с экспоненциальной задержкой (backoff) и не рассчитывайте на повторные отправки со стороны отправителя.
8. Используйте очередь недоставленных событий. После нескольких неудач переместите событие в dead-letter queue и оповестите сотрудника.
9. Сверяйте данные. Запускайте периодическую задачу, которая сравнивает недавние диалоги инбокса с записями CRM и восполняет пропуски через API инбокса.

Почему важны идемпотентность и порядок событий

Отправители вебхуков обычно повторяют запрос, если не получили своевременный успешный ответ, поэтому доставка работает по принципу at-least-once. Одно и то же событие может прийти дважды, а событие «закрыто» может прийти раньше последнего события «сообщение получено». Чтобы справиться с этим:

• используйте ID события как ключ дедупликации;
• используйте upsert по ID диалога или сообщения в CRM;
• сравнивайте временные метки или порядковые номера событий и игнорируйте более старое состояние.

Когда сценарий CRM вызывает API инбокса, чтобы отправить сообщение, передавайте ключ идемпотентности, если API его поддерживает. Распространённый подход описан в черновике IETF для HTTP-заголовка Idempotency-Key.

Как сопоставлять контакты между каналами?

Сопоставляйте по нормализованным идентификаторам, отдавайте предпочтение детерминированным совпадениям, а неоднозначные случаи передавайте человеку.

Правила принятия решений:

1. Одно точное совпадение: связать.
2. Совпадений нет: создать лид или «несопоставленный контакт» с указанием исходного канала.
3. Несколько совпадений: пометить для оператора, не объединять автоматически.
4. Клиент подтвердил другой идентификатор в диалоге: связать его и добавить пометку с основанием.

Как обеспечить приватность данных при интеграции с CRM?

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

• Минимизация данных. Храните в CRM ссылки на диалоги, результаты и краткое содержание, а полные переписки оставляйте в инбоксе, если у вас нет определённой цели.
• Правовое основание и согласие. Фиксируйте согласие на получение маркетинговых сообщений (opt-in) по каждому каналу: обращение в поддержку не является согласием на маркетинговые шаблоны.
• Срок хранения. Согласуйте сроки хранения в инбоксе, CRM, очередях и логах: логи payload вебхуков часто забывают.
• Контроль доступа. Ограничьте круг лиц, которые видят текст сообщений и вложения в CRM.
• Запросы на удаление и доступ. Сделайте так, чтобы запрос в одной системе распространялся на другую.
• Трансграничная передача. Проверьте, где каждая система хранит данные. GDPR распространяется на персональные данные людей в ЕС, а в ОАЭ и Саудовской Аравии действуют собственные законы о защите персональных данных. Актуальные требования уточняйте у соответствующего регулятора и юристов вашей компании.

Как выглядит референсная архитектура?

В текстовом виде поток таков: каналы → инбокс → приёмник → очередь → воркер → CRM, а сценарии CRM возвращаются в API инбокса.

Пример из практики: группа клиник в Джидде

«Wahat Clinics» — вымышленная медицинская группа в Саудовской Аравии. Она использует CRM для записи пациентов на приём и инбокс для WhatsApp и электронной почты.

• Пациент пишет в WhatsApp. Инбокс отправляет событие «диалог создан», приёмник проверяет его, сохраняет и ставит в очередь.
• Воркер нормализует номер до формата E.164, находит одну карточку пациента и записывает активность со ссылкой на диалог, а не с текстом сообщения.
• CRM показывает, что предпочитаемый язык пациента — арабский, и передаёт это в инбокс, который направляет диалог в арабскую очередь.
• Когда запись на приём оформлена в CRM, сценарий вызывает API инбокса и отправляет подтверждение одобренным служебным шаблоном (utility). ID записи передаётся как ключ идемпотентности, чтобы повторная попытка не отправила два подтверждения.
• Событие инбокса «сообщение доставлено» обновляет запись о приёме.

Какие ошибки встречаются чаще всего?

• Запись в CRM внутри запроса вебхука, из-за чего возникают тайм-ауты, повторные отправки и дубликаты.
• Отсутствие дедупликации, из-за чего создаются дубликаты активностей и контактов.
• Сопоставление по ненормализованным номерам телефонов, из-за чего форматы +971 и с ведущим 0 никогда не совпадают.
• Автоматическое объединение по имени или частичным совпадениям.
• Копирование всего содержимого сообщений в CRM без цели и правила хранения.
• Отсутствие сверки, из-за чего один пропущенный событие превращается в постоянное расхождение данных.
• Секреты в исходном коде и отсутствие плана их ротации.

Чем помогает OmniChannels.ai

OmniChannels.ai, платформа на базе BroadNet Technologies, объединяет диалоги из WhatsApp, Instagram, Messenger, Telegram и электронной почты в одном общем инбоксе (едином окне для всех каналов) Omni Inbox с назначением операторов и тегами. Кроме того, платформа поддерживает подключение WhatsApp через Meta Embedded Signup и одобренные шаблоны с переменными, медиа и кнопками. Для интеграции с CRM REST API публично документирован со спецификацией OpenAPI 3.1, а вебхуки передают статусы доставки (SENT, DELIVERED, READ, FAILED и другие) в едином нормализованном формате. Отчёты о доставке с фильтрами и экспортом в CSV помогают при сверке. Начните со страницы для разработчиков.