Інтеграція 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, налаштування автоматичних повідомлень.

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

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

Досвід: понад 50 проектів. Гарантуємо відсутність помилок 403 та втрат подій. Економія до $50,000 на рік на підтримці.

Зв'яжіться з нами для оцінки вашого проекту — ми підготуємо інтеграцію за 1–3 дні. Замовте інтеграцію Intercom під ключ у перевірених інженерів.

Інтеграція email розсилок: чому вона часто ламається?

Ми стикалися з тим, що тригерний лист через 10 хвилин після реєстрації конвертує в 4–5 разів краще, ніж той самий лист через 24 години. Це не маркетинговий міф — це механіка: поки користувач теплий, поки пам'ятає контекст. Але більшість інтеграцій з розсильниками зроблені так: форма сабмітиться → синхронний HTTP-запит до API → якщо API гальмує, користувач чекає 3 секунди → лист йде або не йде, ніхто не знає.

Якщо ви зіткнулися з втраченими листами або потраплянням у спам, замовте аудит існуючої інтеграції — ми знайдемо вузькі місця за 2 дні.

Провайдери та їх API

Unisender — російський провайдер, популярний у сегменті SMB. REST API, простий. Додавання контакту: importContacts, відправка транзакційного листа: sendEmail. Важливо: для транзакційних листів (підтвердження замовлення, скидання пароля) Unisender Go — окремий сервіс з іншим API та окремою ціною. Змішувати масові розсилки та транзакційні в одному потоці — погана ідея для репутації домену.

SendPulse — надає email, SMS, web push, Viber, Telegram-боти через єдиний API. Для проєктів, де потрібен омніканал, це зручно. Automation 360 — візуальний конструктор ланцюжків, можна запустити автоматизацію через API event. SDK для PHP (sendpulse/rest-api-php-sdk) підтримується, але оновлюється нерегулярно — краще використовувати напряму через Guzzle.

Mailchimp — вибір для міжнародної аудиторії та маркетингових команд, звиклих до екосистеми Mailchimp. Transactional email — через Mandrill (дочірній сервіс). Marketing API v3 для управління списками, тегами, кампаніями. Webhook для подій: відкриття, клік, відписка, bounce.

SMS. Для Росії: СМСЦ, МТС Exolve, Devino Telecom, SMS Aero. API у всіх схожий: метод send, параметри phone, message, sender (ім'я відправника — потрібно реєструвати окремо у оператора). Один нюанс: ім'я відправника має бути зареєстровано через агрегатора з договором — без цього SMS не відправляться на мережі МТС/МегаФон/Білайн.

Як побудувати інтеграцію, щоб не втрачати листи?

Розділяємо транзакційні та маркетингові потоки

Транзакційні листи (підтвердження замовлення, скидання пароля, статус доставки) — через окремий домен-відправник або субдомен tx.example.com. Маркетингові розсилки — через mail.example.com або news.example.com. Якщо маркетингова розсилка отримає багато скарг на спам, це не повинно зачепити репутацію транзакційного потоку. Згідно з документацією SendGrid, транзакційні повідомлення слід відправляти через виділений IP-пул для запобігання перехресному впливу.

Черга та retry

Будь-який виклик до email API — через чергу (Laravel Queue, Bull, Celery). Якщо Unisender повернув 503 — задача йде в retry через 5 хвилин, потім 15, потім 60. Після 5 невдалих спроб — у dead letter queue з алертом. Користувач при цьому вже отримав свій 200 OK і не знає про проблему. Завдяки цьому підходу bounce rate на проєктах знижується до 0.5%.

Приклад job для Laravel:

public function handle(): void
{
    try {
        $response = Http::post(config('services.unisender.email_url'), $this->params);
        if ($response->failed()) {
            $this->release(300); // retry через 5 хв
        }
    } catch (\Throwable $e) {
        $this->release(300);
    }
}

Шаблони

Зберігаємо шаблони в коді (Blade, Twig, React Email), не в інтерфейсі провайдера. Причини: версіонування через Git, preview у браузері без відправки, можливість тестування. Для складних шаблонів з динамічним контентом — react-email з експортом в HTML через @react-email/render.

Валідація та згоди

Перед додаванням контакту до списку — double opt-in (лист з підтвердженням). Зберігати факт підтвердження з timestamp у своїй БД. При відписці — синхронно відписуємо і у провайдера, і в своїй базі. Ігнорувати webhook відписки — прямий шлях до блокування акаунта у провайдера. Всі процеси відповідають ФЗ-152 про персональні дані.

Моніторинг доставності

Підключаємо webhook від провайдера на події bounce (жорсткий і м'який), spam_complaint, unsubscribe. Жорсткий bounce — негайно позначаємо email як невалідний у своїй БД, більше не відправляємо. М'який bounce 3 рази поспіль — те саме. Метрики: open rate, click rate, bounce rate, unsubscribe rate — дивимося не рідше разу на тиждень. Наші сертифіковані інженери налаштовують алерти в Grafana/Prometheus.

Чому важливо розділяти потоки?

Якщо відправити маркетингову розсилку з того ж домену, що й транзакційні листи, отримавши скарги на спам, ви ризикуєте заблокувати домен — і користувачі перестануть отримувати навіть підтвердження замовлень. SPF, DKIM, DMARC (Wikipedia SPF, Wikipedia DKIM) повинні бути налаштовані окремо для кожного потоку. Ми використовуємо субдомени з різними DNS-записами.

Обсяг робіт з інтеграції

• Аудит поточних потоків комунікації та репутації домену (SPF, DKIM, DMARC)
• Вибір провайдера та схеми: транзакційний vs маркетинговий трафік
• Налаштування DNS-записів SPF, DKIM, DMARC (Wikipedia DMARC)
• Розробка шаблонів листів (HTML + динамічний контент)
• Інтеграція з бекендом через черги та API
• Налаштування webhook для доставності та скарг
• Документація з експлуатації та навчання команди
• Гарантія доставності та підтримка після запуску

Терміни та вартість

Вартість розраховується індивідуально після аудиту. Ми працюємо під ключ: від аналізу до моніторингу в продакшені. Отримайте консультацію інженера — оцінимо проєкт безкоштовно та скажемо точні терміни. Досвід більше 7 років в інтеграції поштових сервісів, реалізовано 50+ проєктів. Замовте безкоштовний аудит поточної інтеграції — отримайте звіт з рекомендаціями.