Intercom Integration: Setup, HMAC, Custom Attributes & Events

You have integrated Intercom, set up trigger messages—but users aren't being identified, events vanish into thin air, and HMAC verification throws a 403 error. This is typical for a shallow Intercom integration. As a result, up to 30% of leads never receive personalized messages, and the support team spends hours manually gathering data.

Over five years, we have integrated Intercom on 50+ projects—from SaaS startups to enterprise solutions with thousands of users. Our stack is PHP 8.3 (Laravel), JavaScript, and Docker. We test each stage on staging to avoid production issues. Let's dive into setting up HMAC, passing custom attributes, and tracking events so the messenger works flawlessly.

How to Set Up HMAC Verification

Generating the HMAC Hash

HMAC (Hash-based Message Authentication Code) protects user data from tampering. Intercom uses your secret key to verify the hash. A 403 error occurs if the key doesn't match or user_id is empty. Obtain your secret key in Intercom settings (Settings > Developer Tools > Identity Verification). Generate the hash server-side:

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

Ensure user_id is unique and stable. On one project we saw a 403 error because user_id contained spaces—trim fixed it.

Installing the Script with HMAC

Add the script before </head>. Always pass 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>

Important: api_base must point to https://api-iam.intercom.io, otherwise it won't work.

How to Pass Custom Attributes

Send user data right after initialization to make the Inbox profile complete. Use the window.Intercom('update', ...) method:

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

Typical mistakes: forgetting to pass attributes after profile updates, or not syncing with CRM. Attributes must be refreshed on every change—otherwise Intercom stores outdated data.

How to Track Events

Every important user action should become an Intercom event. This enables automated triggers:

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

Events allow behavioral segmentation. For example, if a customer hasn't used a new feature within seven days, send an automated educational message. Intercom supports up to 100 custom events per project.

REST API: Creating Notes and Tasks

Use the REST API for programmatic inbox interactions. For example, adding a note on order placement:

Http::withToken(env('INTERCOM_ACCESS_TOKEN'))
    ->post('https://api.intercom.io/notes', [
        'user'  => ['user_id' => $userId],
        'body'  => "Placed order #{$orderId} for {$total} RUB"
    ]);

The REST API lets you sync users, add tags, and create tasks.

Why Intercom Is Worth the Investment

Intercom is three times more effective in converting chat to sale thanks to proactive messages and deep product integration. The integration typically pays for itself within two months, reducing support costs by $5,000–$20,000 per year for an average B2B project. At 5,000 users, savings reach $50,000 per year. Comparison:

The difference is substantial—especially for B2B with long sales cycles.

How We Deliver Turnkey Integration

We don't just drop in a script. We design the data flow architecture, set up automated messages and tours, and integrate with CRM via REST API.

Work process:

1. Analysis: audit current stack, identify integration points (registration, payment event, login).
2. Design: attribute schema, HMAC keys, events.
3. Implementation: install script, backend code, staging testing.
4. Testing: verify identification, events, automated messages.
5. Deployment and documentation: hand over access, support instructions.

What's Included

• Messenger setup with HMAC verification.
• Configuration of 5–10 custom attributes (plan, spend, status) and events.
• REST API integration for creating/updating users, adding notes and tags.
• Testing and documentation (all attributes, events, support guide).
• Training the support team on Inbox usage and automated message setup.

Delivery Timeline

Typical Integration Mistakes

• Not passing HMAC hash for logged-in users → 403 error.
• Attributes not updating after profile changes → stale Inbox data.
• Events with identical names overwriting each other → use unique names.
• Not handling user deletion per GDPR → Intercom retains data indefinitely, violating regulations.

Experience: 5+ years, 50+ projects. We guarantee no 403 errors and no lost events. Save up to $50,000 per year on support.

Contact us for a project assessment—we'll prepare your integration in 1–3 days. Order a turnkey Intercom integration from proven engineers.

Email Campaign Integration: Why Does It Often Break?

We’ve observed that a trigger email sent 10 minutes after registration converts 4–5 times better than the same email sent after 24 hours. This isn’t a marketing myth—it’s mechanics: while the user is still warm, while they remember the context. But most integrations with email services are built like this: form submits → synchronous HTTP request to API → if the API is slow, the user waits 3 seconds → the email either goes out or doesn’t, nobody knows. In one project, we saw a 30% drop in conversion simply because the email service responded with 504 and Laravel’s queue driver wasn’t configured. Lost emails often hit customers silently – no log, no alert, just a missing order confirmation.

If you’re facing lost emails or spam folder issues, order an audit of your current integration – we’ll find bottlenecks within 2 days.

Providers and Their APIs

Unisender — a Russian provider popular in the SMB segment. REST API, simple. Adding a contact: importContacts, sending a transactional email: sendEmail. Important: for transactional emails (order confirmations, password resets), Unisender Go is a separate service with a different API and separate pricing. Mixing bulk and transactional mailings in one stream is bad for domain reputation. Unisender Go handles up to 1000 requests per second.

SendPulse — provides email, SMS, web push, Viber, and Telegram bots through a unified API. Convenient for projects requiring an omnichannel approach. Automation 360 is a visual chain builder; you can trigger automation via API events. The PHP SDK (sendpulse/rest-api-php-sdk) is maintained but updated irregularly – better to use Guzzle directly.

Mailchimp — a choice for international audiences and marketing teams accustomed to the Mailchimp ecosystem. Transactional email via Mandrill (a subsidiary service). Marketing API v3 for list, tag, and campaign management. Webhooks for opens, clicks, unsubscribes, bounces.

SMS. For Russia: SMSCenter, MTS Exolve, Devino Telecom, SMS Aero. Their APIs are similar: a send method with phone, message, sender parameters (sender name must be registered separately with the operator). One nuance: the sender name must be registered through the aggregator with a contract – otherwise SMS won’t be sent on MTS/MegaFon/Beeline networks.

How to Build an Integration That Doesn’t Lose Emails?

Separate Transactional and Marketing Streams

Transactional emails (order confirmations, password resets, delivery status) go through a dedicated sender domain or subdomain tx.example.com. Marketing campaigns go through mail.example.com or news.example.com. If a marketing campaign receives many spam complaints, it should not affect the reputation of the transactional stream. According to SendGrid documentation, transactional messages should be sent through a dedicated IP pool to prevent cross-contamination.

Queue and Retry

Any call to the email API goes through a queue (Laravel Queue, Bull, Celery). If Unisender returns a 503, the job retries after 5 minutes, then 15, then 60. After 5 failed attempts, it goes to a dead letter queue with an alert. The user already received their 200 OK and knows nothing about the issue. This approach reduces bounce rate on projects to 0.5%.

Example Laravel job:

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

Templates

We store templates in code (Blade, Twig, React Email), not in the provider’s interface. Reasons: versioning via Git, browser preview without sending, testability. For complex templates with dynamic content — react-email with export to HTML via @react-email/render.

Validation and Consent

Before adding a contact to a list — double opt-in (confirmation email). Store the confirmation timestamp in your own database. Upon unsubscription — synchronously unsubscribe both at the provider and in your database. Ignoring webhook unsubscriptions is a direct path to account suspension at the provider. All processes comply with Федеральный закон № 152-ФЗ «О персональных данных».

Deliverability Monitoring and DKIM Setup

Connect provider webhooks for events: bounce (hard and soft), spam_complaint, unsubscribe. Hard bounce — immediately mark the email as invalid in your database, stop sending. Soft bounce 3 times in a row — same. Metrics: open rate, click rate, bounce rate, unsubscribe rate — review at least once a week. Our certified engineers configure alerts in Grafana/Prometheus.

DKIM configuration steps:

1. Generate a key pair (e.g., openssl genrsa -out private.key 2048).
2. Publish the public key in DNS as a TXT record for the selector (e.g., mail._domainkey.tx.example.com).
3. Provide the selector to the provider (SendGrid, Mailgun, Unisender).
4. Verify with dig TXT mail._domainkey.tx.example.com.

SPF, DKIM, DMARC must be configured separately for each stream. We use subdomains with different DNS records.

Why Is It Important to Separate Streams?

If you send a marketing campaign from the same domain as transactional emails and receive spam complaints, you risk getting the domain blocked — and users will stop receiving even order confirmations. SPF, DKIM, DMARC (Sender Policy Framework, DomainKeys Identified Mail, Domain‑based Message Authentication, Reporting and Conformance) must be configured separately for each stream. In one project, a marketing blast with 12% spam complaints blocked the transactional domain for 48 hours — we had to re‑authenticate with Google and Yandex.

What Does the Integration Scope Include?

• Audit of current communication streams and domain reputation (SPF, DKIM, DMARC)
• Provider and schema selection: transactional vs marketing traffic
• Configuration of SPF, DKIM, DMARC DNS records
• Development of email templates (HTML + dynamic content)
• Backend integration via queues and API
• Webhook setup for deliverability and complaints
• Operations documentation and team training
• Deliverability guarantee and post‑launch support

We deliver production‑ready documentation, access to monitoring dashboards, and a handover session with your engineers. Our certified engineers provide a 30‑day post‑launch health check guarantee.

Timelines and Cost

Cost is calculated individually after audit. We provide turnkey service: from analysis to production monitoring. Contact us for a free engineer consultation — we’ll evaluate your project and give accurate timelines. Over 7 years of experience in email service integration, 50+ projects implemented. Order a free audit of your current integration and receive a report with recommendations and estimated savings.