How do we set up Intercom Messenger identity verification (JWT) so we can handle account-specific requests securely?

Handling account‑specific requests in Intercom Messenger—things like billing questions, plan changes, or internal account IDs—absolutely requires identity verification. Without it, you’re effectively treating every browser as anonymous, which means you can’t safely expose sensitive data or let Fin or your agents trust what they see in the Inbox.

This guide walks through how to set up Intercom Messenger identity verification using JSON Web Tokens (JWT) so you can confidently tie each Messenger session to a specific, authenticated user in your own system.

Note: This article focuses on web Messenger and JWT identity verification. You’ll need an Intercom trial or subscription and permissions that allow you to manage security settings.

---

Quick Answer: Intercom Messenger identity verification uses a signed JWT to prove that the user in your app is the same user you’re loading into Intercom. Your backend signs the token with your Intercom Identity Verification secret, you pass it to the Messenger boot code as user_hash, and Intercom uses that signature to securely link the session to the correct user—so Fin and your agents can safely handle account‑specific requests.

The Quick Overview

• What It Is: Identity verification is a security mechanism that cryptographically links a logged‑in user in your app to their Intercom profile using JWT and a shared secret.
• Who It Is For: Teams that use Intercom Messenger with logged‑in customers and need to surface account data, resolve sensitive queries, or let Fin and agents rely on trusted identity.
• Core Problem Solved: Without identity verification, anyone who can guess an identifier could impersonate another user. JWT-based verification prevents that, so you can safely handle account‑specific requests in Messenger.

---

How It Works

At a high level, Intercom identity verification is a three‑part system:

1. You generate a secret in Intercom that only your backend knows.
2. When a user logs into your app, your backend creates a JWT that encodes their Intercom user_id and signs it with that secret.
3. Your frontend boots the Intercom Messenger, passing both the user_id and the signed user_hash (JWT). Intercom validates the signature on every page load and only trusts the identity if the hash is valid.

Because the JWT is signed server‑side and never exposed in your code repository, Intercom can be sure that the browser session actually belongs to the user you claim it does.

Here’s the process broken down into practical phases.

1. Enable the Messenger and get your workspace details

Before touching JWTs, make sure Messenger is correctly installed and accepting traffic.

1. In Intercom, go to:
   Settings > Channels > Messenger > Install and choose Install for web.
2. Pick your installation method:
   • JavaScript code snippet
   • Framework/plugin (e.g., WordPress, SPA loader, GTM, etc.)
3. Confirm that Messenger appears on your site for test users.
   • If it doesn’t, review installation, check for ad blockers, private browsing, or public suffix domains that can block cookies and visibility.

You’ll also need:

• Your Workspace ID (used in the JS snippet).
• Permission to manage security settings (often “Can manage general and security settings”).

2. Configure identity verification and your secret

Next, you enable identity verification and obtain the secret key Intercom will use to verify your JWTs.

1. In Intercom, go to the Identity Verification / Security settings page (exact navigation may vary by plan; look under Settings > Security or Installation > Identity Verification).
2. Turn on Identity verification for users (and leads, if relevant).
3. Generate or copy your Identity Verification secret.
   • Store this secret securely in your backend (e.g., environment variables or secret manager).
   • Never expose it in frontend code, public repos, or client‑side logs.

Important: This secret is the root of trust between your app and Intercom. Rotate it periodically as part of your standard key‑management process and whenever you suspect it may have been exposed.

3. Generate the JWT on your backend

With the secret in place, your backend will generate a JWT whenever a user is authenticated. The JWT will encode who the user is and will be signed with the Intercom secret.

At a minimum, you’ll typically include:

• sub (subject) or user_id – the unique user identifier you use in Intercom.
• Optional claims like iat (issued at) and exp (expiration) to control token lifetime.

Below are conceptual examples; adapt to your language and framework.

Example structure (language‑agnostic)

// JWT payload example
{
  "sub": "123456",           // Your internal user ID mapped to Intercom user_id
  "iat": 1712592000,         // Issued at (Unix timestamp)
  "exp": 1712595600          // Optional: expiry (1 hour later)
}

Sign this payload with your Intercom Identity Verification secret using an HMAC algorithm (commonly HS256).

Example in Node.js

const jwt = require('jsonwebtoken');

function generateIntercomUserHash(userId) {
  const secret = process.env.INTERCOM_IDENTITY_SECRET;

  const payload = {
    sub: userId,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 60 * 60 // 1 hour
  };

  return jwt.sign(payload, secret, { algorithm: 'HS256' });
}

Example in Ruby

require 'jwt'

def generate_intercom_user_hash(user_id)
  secret = ENV.fetch('INTERCOM_IDENTITY_SECRET')

  payload = {
    sub: user_id,
    iat: Time.now.to_i,
    exp: (Time.now + 3600).to_i
  }

  JWT.encode(payload, secret, 'HS256')
end

Note: Your backend should only generate this JWT for authenticated users. Tie it to your login/session logic, not to anonymous page views.

4. Boot Messenger with the user and user_hash

Once the backend can generate the JWT, you pass it to your frontend (e.g., via server‑rendered templates, an authenticated JSON endpoint, or a signed cookie) and then boot the Messenger.

A typical web installation snippet for an authenticated user looks like this:

<script>
  window.intercomSettings = {
    app_id: "YOUR_WORKSPACE_ID",
    user_id: "123456",               // same ID used in the JWT
    name: "Jane Doe",                // optional
    email: "jane@example.com",       // optional but very useful
    user_hash: "JWT_FROM_BACKEND"    // <-- the signed JWT
  };
</script>
<script>
  (function(){
    var w = window; var ic = w.Intercom;
    if(typeof ic === "function"){
      ic('reattach_activator');
      ic('update', w.intercomSettings);
    } else {
      var d = document;
      var i = function(){ i.c(arguments); };
      i.q = []; i.c = function(args){ i.q.push(args); };
      w.Intercom = i;
      function l(){
        var s = d.createElement('script');
        s.type = 'text/javascript'; s.async = true;
        s.src = 'https://widget.intercom.io/widget/YOUR_WORKSPACE_ID';
        var x = d.getElementsByTagName('script')[0];
        x.parentNode.insertBefore(s, x);
      }
      if (document.readyState === 'complete') {
        l();
      } else if (w.attachEvent) {
        w.attachEvent('onload', l);
      } else {
        w.addEventListener('load', l, false);
      }
    }
  })();
</script>

On a SPA or if you delay Messenger until after cookie consent, you’ll typically:

1. Define window.intercomSettings early with disabled: true:

   window.intercomSettings = {
     app_id: 'YOUR_WORKSPACE_ID',
     disabled: true
   };
   

2. Once the user is authenticated and consent is granted, call:

   Intercom('boot', {
     app_id: 'YOUR_WORKSPACE_ID',
     user_id: '123456',
     user_hash: 'JWT_FROM_BACKEND',
     disabled: false
   });
   

Important: The user_id in intercomSettings must match the ID encoded in the JWT. If they differ, Intercom will reject the identity verification.

5. Verify it’s working and test failure modes

Once you deploy this flow to a staging environment, validate that identity verification is behaving correctly:

• Confirmed user linkage:

  • Log in as a test user.
  • Open Messenger and start a conversation.
  • In Intercom Inbox, open the conversation and confirm:
    • The user record matches your app’s user.
    • The same user appears consistently across sessions/devices (where your app session persists).

• Tampering protection:

  • Manually change the user_id in intercomSettings in the browser DevTools without updating the JWT.
  • Refresh the page; Intercom should not treat the browser as the spoofed user.
  • If the JWT is invalid, the user won’t be linked to the tampered ID.

• Expiry behavior:

  • If you’re using exp, confirm how the experience looks when the token expires:
    • Typically you refresh the token when you refresh the user’s session.
    • Avoid very long‑lived tokens for sensitive environments.

---

Features & Benefits Breakdown

Core Feature	What It Does	Primary Benefit
JWT-based identity verification	Uses a signed JWT (user_hash) to prove the user’s identity to Intercom.	Prevents impersonation and makes account‑specific conversations safe to handle in Messenger.
Secure Messenger boot flow	Boots Messenger only after your app authenticates the user and issues a JWT.	Ensures Fin and agents see the right user context—so they can resolve sensitive issues confidently.
Consistent user profiles	Ties conversations across sessions/devices to the same Intercom user record.	Gives agents a shared view of every customer, improving resolution speed and reporting accuracy.

---

Ideal Use Cases

• Best for authenticated web apps: Because you already have a login system and user IDs, you can easily generate JWTs on login and safely expose subscription data, billing info, or account settings in Messenger.
• Best for Fin handling account‑specific requests: Because Fin can rely on verified identity (and your policies), you can let it resolve more complex, account‑linked queries while still enforcing escalation rules for high‑risk actions.

---

Limitations & Considerations

• Backend requirement: You must generate JWTs server‑side using your Intercom secret.
  • Workaround: If you currently have a frontend‑only stack, introduce a minimal backend service (or serverless function) purely for JWT issuance tied to your auth.
• User-only trust model: Identity verification is tied to your user_id, not arbitrary client‑side attributes.
  • Workaround: Map all necessary account context to that user in Intercom or through Data connectors and Fin Tasks/Procedures instead of relying on unverified client‑side parameters.

---

Pricing & Plans

Identity verification is part of securing the Intercom Messenger for logged‑in users. You’ll need:

• An active Intercom trial or subscription.
• Access to Messenger (part of the Customer Service Suite).
• The ability to manage workspace settings (often available to admins and security owners).

Exact pricing depends on your Intercom plan and scale:

• Growth/SMB Plans: Best for teams that want to roll out secure Messenger and Fin quickly and see impact in days, not weeks.
• Advanced/Enterprise Plans: Best for teams needing SAML SSO, granular permissions (“Can manage general and security settings”), and stricter governance around identity and security controls.

For detailed pricing, visit Intercom or contact Sales for a tailored quote.

---

Frequently Asked Questions

Do we need identity verification if we only answer generic questions?

Short Answer: If you never touch account data, it’s optional—but in practice, most teams should enable it.

Details: Without identity verification, Intercom treats users as unverified. That might be acceptable if you strictly answer generic FAQs. But as soon as agents or Fin need to see or act on anything tied to a specific account (billing, usage, internal IDs), you need a cryptographic guarantee of who’s on the other side. Enabling JWT-based verification early gives you room to expand into account‑aware automation and richer support without re‑architecting later.

---

How does identity verification affect Fin AI Agent and our security posture?

Short Answer: It lets Fin safely use account context and enforce policies, instead of treating every request as anonymous.

Details: With identity verification in place:

• Fin can resolve more complex queries—like “What plan am I on?” or “Why was my last invoice higher?”—because it can trust the user identity and pull correct context.
• You can combine verified identity with Fin Tasks/Procedures to gate sensitive actions (e.g., plan changes, refunds) behind identity checks and escalation rules.
• Agents in the Helpdesk see consistent customer profiles and conversation history, reducing risky copy‑paste or manual lookups.
  In short, identity verification turns Messenger from a generic Q&A surface into a secure, account‑aware channel you can confidently automate.

---

Summary

Setting up Intercom Messenger identity verification with JWT is the foundation for handling account‑specific requests securely. You:

1. Enable Messenger and identity verification in Intercom.
2. Store the Intercom identity secret safely in your backend.
3. Generate a signed JWT on login that encodes your Intercom user_id.
4. Boot Messenger with both user_id and user_hash.

Once that’s in place, every Messenger session is cryptographically tied to the right user, so Fin and your agents can resolve sensitive queries faster—with a shared, trusted view of every customer and clear governance over who can see what.

---

Next Step

Get Started