Інтеграція Intercom: встановлення, ідентифікація, події

Інтеграція Intercom з коректним налаштуванням HMAC-верифікації, передачею кастомних атрибутів та відстеженням подій — запорука успішної роботи чату підтримки. Ви виконали інтеграцію Intercom, запустили тригерні повідомлення — але користувачі не ідентифікуються, події йдуть у порожнечу, а HMAC-верифікація дає помилку 403. Це типова ситуація при поверхневій інтеграції Intercom. У результаті до 30% лідів не отримують персоналізованого повідомлення, а відділ підтримки витрачає години на ручний збір даних.

Ми інтегрували Intercom на 50+ проектах — від SaaS-стартапів до enterprise-рішень з тисячами користувачів. Наш стек: PHP 8.3 (Laravel), JavaScript, Docker. Кожен етап тестуємо на staging, щоб уникнути помилок у продакшені. Розберемо, як налаштувати HMAC, передавати кастомні атрибути та відстежувати події, щоб месенджер працював без збоїв.

Як налаштувати HMAC-верифікацію?

Генерація HMAC-хешу

HMAC (Hash-based Message Authentication Code) захищає дані користувача від підробки. Intercom використовує ваш секретний ключ для перевірки хешу. Помилка 403 виникає, якщо ключ не збігається або user_id порожній. Отримайте секретний ключ у налаштуваннях Intercom (Settings > Developer Tools > Identity Verification). На сервері згенеруйте хеш:

$userHash = hash_hmac('sha256', (string)$user->id, env('INTERCOM_SECRET_KEY')); 

Перевірте, що user_id унікальний і не змінюється. На одному проекті ми бачили помилку 403 через те, що user_id містив пробіли — після trim проблема зникла.

Встановлення скрипта з HMAC

Додайте скрипт перед </head>. Обов'язково передавайте user_hash:

<script> window.intercomSettings = { api_base: "https://api-iam.intercom.io", app_id: "YOUR_APP_ID", user_id: "<?= $user->id ?>", name: "<?= $user->name ?>", email: "<?= $user->email ?>", created_at: <?= $user->created_at->timestamp ?>, user_hash: "<?= $userHash ?>" }; </script> <script> (function(){var w=window;var ic=w.Intercom;/* snippet */})(); </script> 

Важно: api_base має вказувати на https://api-iam.intercom.io, інакше не спрацює.

Як передавати кастомні атрибути?

Передавайте дані про користувача одразу після ініціалізації, щоб картка в Inbox була повною. Використовуйте метод window.Intercom('update', ...):

window.Intercom('update', { plan: 'pro', monthly_spend: 150, is_paying: true, last_product_used: 'dashboard' }); 

Типові помилки: забувають передати атрибути після оновлення профілю або не синхронізують з CRM. Атрибути мають оновлюватися при кожній зміні — інакше Intercom зберігає застарілі дані.

Як відстежувати події?

Кожна важлива дія користувача має стати подією для Intercom. Так ви зможете будувати автоматичні тригери:

window.Intercom('trackEvent', 'feature-used', { feature: 'export', format: 'csv', record_count: 1250 }); 

Події дозволяють сегментувати користувачів за поведінкою. Наприклад, якщо клієнт не скористався новою функцією протягом 7 днів, надсилайте автоматичне навчальне повідомлення. Intercom дає можливість створювати до 100 кастомних подій на проект.

REST API: створення нотаток і завдань

Для програмної взаємодії з Inbox використовуйте REST API. Наприклад, додавання нотатки при оформленні замовлення:

Http::withToken(env('INTERCOM_ACCESS_TOKEN')) ->post('https://api.intercom.io/notes', [ 'user' => ['user_id' => $userId], 'body' => "Оформив замовлення #{$orderId} на {$total} ₴" ]); 

REST API дозволяє синхронізувати користувачів, додавати теги та створювати завдання.

Чому Intercom вигідніший за дешеві альтернативи?

Intercom у 3 рази ефективніший за конверсією з чату в продаж завдяки проактивним повідомленням і глибокій інтеграції з продуктом. Інтеграція окупається в середньому за 2 місяці, скорочуючи витрати на підтримку на $5,000–$20,000 на рік для середнього B2B-проекту. Для проекту з 1,000 користувачів економія складає $15,000 на рік. При зростанні бази до 5,000 користувачів економія досягає $50,000 на рік. Інтеграція Intercom у 2 рази швидше налаштовується, ніж дешеві альтернативи. Порівняння:

Різниця суттєва — особливо для B2B з довгим циклом угоди.

Як ми виконуємо інтеграцію під ключ?

Ми не просто вставляємо скрипт. Ми проектуємо архітектуру передачі даних, налаштовуємо автоматичні повідомлення та тури, інтегруємо з CRM через REST API.

Процес роботи:

1. Аналітика: аудит поточного стеку, визначення точок інтеграції (реєстрація, подія "оплата", вхід).
2. Проектування: схема передачі атрибутів, HMAC-ключі, події.
3. Реалізація: встановлення скрипта, бекенд-код, тестування на staging.
4. Тестування: перевірка ідентифікації, подій, автоматичних повідомлень.
5. Деплой та документація: передача доступів, інструкція для підтримки.

Що входить у роботу?

• Встановлення Messenger з HMAC-верифікацією.
• Налаштування 5–10 кастомних атрибутів (тариф, витрати, статус) та подій.
• Інтеграція REST API для створення/оновлення користувачів, додавання нотаток і тегів.
• Тестування та документація (опис усіх атрибутів, подій, інструкція для підтримки).
• Навчання команди підтримки роботі з Inbox, налаштування автоматичних повідомлень.

Які терміни виконання?

Які типові помилки при інтеграції?