install-messenger

What this skill does

# Install Intercom Messenger

Help the user install the Intercom Messenger on their website or application with JWT-based identity verification. This is the secure default — it prevents user impersonation by cryptographically signing user identity on the server.

Only use the insecure (non-JWT) installation if the user explicitly asks for an "insecure installation". Never default to it.

## Requirements

Gather these from the user before proceeding:

1. **Workspace ID** (also called App ID) — A short alphanumeric string like `abc12345`.
   - Found on the [Intercom Messenger install page](https://app.intercom.com/a/apps/_/settings/channels/messenger/install)
   - Or in the URL bar: `https://app.intercom.com/a/apps/<workspace_id>/...`

2. **Identity Verification Secret** (also called Messenger API Secret) — Found on the [Messenger Security page](https://app.intercom.com/a/apps/_/settings/channels/messenger/security). This is the HMAC secret used to sign JWTs. It must never appear in frontend code.

Ask the user for both values. Do not proceed without the Workspace ID. If they don't have the Identity Verification Secret yet, direct them to the [Messenger Security page](https://app.intercom.com/a/apps/_/settings/channels/messenger/security) to enable it.

In all generated code, replace `YOUR_WORKSPACE_ID` with the user's actual Workspace ID. Do not leave placeholders — substitute the real values they provided.

## Installation Overview

The secure installation has two parts:

1. **Backend**: Create an API endpoint that generates a signed JWT for the current authenticated user
2. **Frontend**: Boot the Messenger with the JWT from the backend

Always implement both parts. The backend generates the JWT; the frontend passes it to the Messenger.

## Step 1: Backend — JWT Generation Endpoint

Create a server-side endpoint that the frontend calls to get a signed JWT for the currently authenticated user. The JWT must be signed with **HS256** using the Identity Verification Secret.

### Required JWT Claims

| Claim | Required | Description |
|-------|----------|-------------|
| `user_id` | Yes | Stable, unique identifier for the user. Must match across sessions. |
| `email` | Recommended | User's email address |
| `name` | Recommended | User's display name |
| `exp` | Recommended | Expiration timestamp (Unix seconds). Use short-lived tokens — 2 hours is reasonable. |

**Important**: `user_id` is mandatory. If multiple users share the same email and you only pass `email` without `user_id`, Intercom will reject the request with a conflict error.

### Node.js / Express Example

```javascript
const jwt = require('jsonwebtoken');

const INTERCOM_SECRET = process.env.INTERCOM_IDENTITY_SECRET; // Never hardcode this

app.get('/api/intercom-jwt', requireAuth, (req, res) => {
  const token = jwt.sign(
    {
      user_id: req.user.id,
      email: req.user.email,
      name: req.user.name,
      exp: Math.floor(Date.now() / 1000) + (2 * 60 * 60), // 2 hours
    },
    INTERCOM_SECRET,
    { algorithm: 'HS256' }
  );

  res.json({ token });
});
```

For Python (Flask/Django), PHP, and Ruby/Rails examples, see `references/backend-examples.md`. The pattern is identical across languages.

Adapt the example to the user's backend language and framework. The key requirements are:
- The endpoint is authenticated (only the logged-in user can get their own JWT)
- The secret comes from an environment variable, never hardcoded
- The token includes `user_id` and has a short expiration

## Step 2: Frontend — Boot Messenger with JWT

The frontend fetches the JWT from the backend and passes it to the Messenger via `intercom_user_jwt`.

### Basic JavaScript (No Framework)

Add before the closing `</body>` tag:

```html
<script>
  // Fetch JWT from your backend, then boot the Messenger
  fetch('/api/intercom-jwt', { credentials: 'include' })
    .then(res => res.json())
    .then(({ token }) => {
      window.Intercom('boot', {
        app_id: 'YOUR_WORKSPACE_ID',
        intercom_user_jwt: token,
      });
    });
</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;var l=function(){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>
```

### Anonymous Visitors

For unauthenticated pages, boot without a JWT: `Intercom('boot', { app_id: 'YOUR_WORKSPACE_ID' })`. Intercom tracks anonymous visitors as leads.

## Framework-Specific Installation

If the user is using React, Next.js, Vue.js, Angular, Ember, or another SPA framework, refer to `references/framework-guides.md` for JWT-integrated installation code. Ask the user what framework they are using if it is not obvious from their codebase.

After reading the framework guide, adapt the code to the user's specific project structure — find their main layout component, app entry point, or equivalent, and integrate the Messenger there.

## Regional Data Centers

Most Intercom workspaces are in the US region, which is the default — no `api_base` is needed. Only add `api_base` if the user's workspace is hosted in EU or Australia:

| Region | `api_base` | Required? |
|--------|------------|-----------|
| US (default) | *(not needed)* | No |
| EU (Ireland) | `https://api-iam.eu.intercom.io` | Yes |
| Australia | `https://api-iam.au.intercom.io` | Yes |

If the user mentions EU or Australian hosting, GDPR compliance, or data residency requirements, add the appropriate `api_base` to every `Intercom('boot', ...)` call. Otherwise, omit it.

## Security Best Practices

### Logout and Shutdown

When a user logs out, shut down the Messenger to clear session cookies and prevent data leakage:

```javascript
// Call this in your logout handler, BEFORE clearing session data
Intercom('shutdown');
```

After shutdown, re-initialize for the next user or as anonymous:

```javascript
Intercom('boot', {
  app_id: 'YOUR_WORKSPACE_ID',
});
```

Always include the shutdown call. Skipping it leaks conversation data between users on shared devices.

### Token Expiration

Set short JWT expiration times — two hours is a good default. To refresh an expired token, re-fetch the JWT from the backend and call `Intercom('boot', ...)` again with the new token.

## Troubleshooting

### JWT Library Not Installed
Error: `Cannot find module 'jsonwebtoken'` (Node.js), `ModuleNotFoundError: No module named 'jwt'` (Python), or `LoadError: cannot load such file -- jwt` (Ruby)
Solution: Install the JWT library for the user's language — `npm install jsonwebtoken`, `pip install PyJWT`, or `gem install jwt`.

### Wrong Identity Verification Secret
Symptom: Messenger loads but shows "Identity verification failed" or user attributes don't appear.
Cause: The secret used to sign JWTs doesn't match the workspace's Identity Verification Secret.
Solution: Verify the secret on the [Messenger Security page](https://app.intercom.com/a/apps/_/settings/channels/messenger/security). Ensure the environment variable holds the correct value for this workspace.

### Plan Doesn't Support Identity Verification
Symptom: Identity Verification Secret not available in Intercom settings.
Cause: Identity verification is a paid feature not available on all Intercom plans.
Solution: Check the workspace's Intercom plan on the [Messenger Security page](https://app.intercom.com/a/apps/_/settings/channels/messenger/security). If identity verification is unavailable, the user may need to upgrade or use the insecure installation (with explicit acknowledgment of the security trade-off).

### JWT `exp` in the Past
Symptom: