Интеграция Intercom: установка, идентификация, события

Вы выполнили интеграцию Intercom, запустили триггерные сообщения — но пользователи не идентифицируются, события уходят в пустоту, а HMAC-верификация даёт ошибку 403. Это типичная ситуация при поверхностной интеграции Intercom. В результате до 30% лидов не получают персонализированного сообщения, а отдел поддержки тратит часы на ручной сбор данных.

За 5 лет мы интегрировали 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-проекта. При росте базы до 5,000 пользователей экономия достигает $50,000 в год. Сравнение:

Разница существенная — особенно для B2B с длинным циклом сделки.

Как мы выполняем интеграцию под ключ

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

Процесс работы:

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

Что входит в работу

• Установка Messenger с HMAC-верификацией.
• Настройка 5–10 кастомных атрибутов (тариф, расходы, статус) и событий.
• Интеграция REST API для создания/обновления пользователей, добавления заметок и тегов.
• Тестирование и документация (описание всех атрибутов, событий, инструкция для поддержки).
• Обучение команды поддержки работе с Inbox, настройка автоматических сообщений.

Сроки выполнения

Типичные ошибки при интеграции

• Не передаётся HMAC-хэш для авторизованных пользователей → ошибка 403.
• Атрибуты не обновляются после изменения профиля → устаревшие данные в Inbox.
• События с одинаковыми именами перезаписывают друг друга → используйте уникальные имена.
• Не настроено удаление пользователей по GDPR → Intercom хранит данные вечно, что нарушает регуляции.

Опыт: 5+ лет, 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+ проектов. Закажите бесплатный аудит текущей интеграции — получите отчёт с рекомендациями.