# Intercom Installation: Messenger, Identity and Launch Checks

An Intercom install is complete when the right person can start a conversation, the support team receives useful context, and the next person using that device cannot inherit the previous session. Start with the installation route, then secure identity and validate the customer journey before enabling broader messaging or Fin workflows.

Canonical URL: https://www.martechdevs.com/blog/how-to-install-intercom

By [Jafrin Akter Alo](https://www.martechdevs.com/authors/jafrin-akter-alo)

Data Engineer and Co-founder at [Martechdevs](https://www.martechdevs.com) and [Growth and Analytics Partners](https://www.growthandanalytics.com)

[LinkedIn](https://linkedin.com/in/jafrinalo)

Last updated: 2026-11-15

Next step: [Plan the Intercom implementation](https://www.martechdevs.com/intercom-implementation). Define identity, customer context and launch acceptance.

## Installation routes

Choose the route that can follow your application's actual login and logout lifecycle.

| Environment | Installation route | Identity owner | Acceptance evidence |
| --- | --- | --- | --- |
| Public website | Web snippet or an approved integration | Website team | Anonymous conversation without fabricated user details |
| Logged-in web application | JavaScript installation or supported framework integration | Application backend and frontend | Correct authenticated profile and clean account switching |
| Single-page application | Explicit Messenger lifecycle integration | Application team | Route changes without repeated initialization |
| iOS application | Native SDK, usually Swift Package Manager | Mobile and backend teams | Secure login, logout and device checks |
| Android application | Native SDK through Gradle | Mobile and backend teams | Secure login, logout and notification checks |

The installation should have one accountable owner across the application, support workspace and backend. A tag can make the launcher appear while leaving those responsibilities unresolved. For an implementation spanning customer identity, support routing and Fin, [Intercom and Fin implementation](https://www.martechdevs.com/intercom-implementation) can bring the acceptance criteria into one delivery plan.

Intercom lists JavaScript, single-page application and third-party routes, including Google Tag Manager and Segment. Web Messenger and user traffic must be enabled in the workspace before the relevant requests can succeed. For anonymous visitors, omit authenticated user details rather than inventing an email or persistent customer ID. [Intercom web installation](https://developers.intercom.com/installing-intercom/web/installation).

## Installation scope

Write a short installation contract before copying code. Identify the production workspace, testing environment, hosting region, public domains, authenticated application and supported mobile platforms. Record who can change the Messenger configuration and who can deploy application code.

Separate the first release from later automation. A sensible initial scope is a working conversation, correct identity, essential account context, a known support destination and a reliable exit from the session. Product tours, proactive messages and automated actions can each have their own acceptance criteria once that foundation is stable.

Decide whether visitors should see the Messenger before login. A public help route and an authenticated account route can serve different purposes. The latter may expose customer-specific history or account information, so its readiness cannot be inferred from the public launcher appearing correctly.

Keep procurement separate from installation acceptance. Use [Intercom pricing](https://www.martechdevs.com/blog/intercom-pricing) and the [software pricing comparison tool](https://www.martechdevs.com/tools/software-pricing) to document the intended package and usage assumptions. A signed contract, a successful script download and a successful customer conversation are three different pieces of evidence.

## Web setup sequence

1. Confirm the intended workspace and its web installation settings. Copy identifiers and the region-appropriate configuration from that workspace, then enable the required Messenger traffic.
2. Choose one installation owner. Search the application, tag manager and integration settings for an existing loader before adding another one.
3. Install the supported loader for the selected route. For a conventional website, place the snippet on the pages in scope. For an application, connect initialization to its authentication lifecycle.
4. Add the server endpoint that issues the authenticated user's Messenger token. Keep it separate from public configuration and ordinary page content.
5. Connect logout, account switching and session expiry to the Messenger cleanup path.
6. Run the acceptance cases below before exposing the installation to the intended audience.

Google Tag Manager can be a practical deployment route for a marketing site. For authenticated applications, review whether the chosen integration can receive the current server-issued token and reliably handle session changes. Segment can also be appropriate when it already owns customer identification, but adding another identity source without a mapping decision creates ambiguity. The implementation choice should follow those requirements.

Do not boot the Messenger from every component render. In a single-page application, designate one component or service to own its lifetime. Pass approved updates when state changes, and avoid turning every visual interaction into a profile update. Keep a small log of lifecycle calls in the test environment so duplicate initialization is visible during review.

## Authenticated identity

Generate the JWT on your server with the Messenger secret; never put that secret or its signing logic in browser code. Use the authenticated session to select a stable `user_id`, include a suitable expiry, and send the token as `intercom_user_jwt`. Protected customer fields belong inside the signed payload. A supplied but invalid JWT is rejected even before enforcement is enabled. Company data must be nested inside a `company` object to create the association. [Intercom JWT authentication](https://www.intercom.com/help/en/articles/10589769-authenticating-users-in-the-messenger-with-json-web-tokens-jwts).

The application should obtain identity from its trusted session, rather than accepting a requested customer ID from a browser parameter. A token endpoint that signs any submitted ID defeats the purpose of signing. Check authorization before selecting customer and company attributes, particularly when one person belongs to multiple accounts.

The following schematic shows the frontend boundary after the official library has loaded. The values are supplied by your application; this is not a token generator or a complete session manager.

```javascript
function bootCustomer(intercom, workspace, token) {
  if (!token) throw new Error('Authenticated token required');
  intercom('boot', {
    app_id: workspace.appId,
    api_base: workspace.apiBase,
    intercom_user_jwt: token
  });
}

function endCustomerSession(intercom, clearWorkspaceCookies) {
  intercom('shutdown');
  clearWorkspaceCookies();
}
```

`clearWorkspaceCookies` represents the application's reviewed cleanup routine for its Intercom cookies across the relevant domain and path scopes. Limit cleanup to the intended Intercom cookies. Cookie removal must match the original name, path and domain. JavaScript cannot remove HttpOnly cookies or cookies outside its permitted domain scope; include the relevant paths in the cleanup routine and verify the result. [MDN cookie scope and removal](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies). The small function only makes the required ordering explicit; it cannot prove that the browser has removed every cookie or that Intercom accepted a token.

Intercom distinguishes accepting valid tokens from enforcing Messenger Security. Enable enforcement after validating the supported clients, and protect signed attributes against insecure Messenger updates. Existing HMAC installations can continue during migration, but use the current JWT migration route for the new implementation. Test and production workspaces use different secrets. [Messenger Security migration](https://www.intercom.com/help/en/articles/10807823-migrating-from-identity-verification-to-messenger-security-with-jwts).

For account switching, treat the old identity's termination as a prerequisite for the next boot. Include automatic session expiry in that path, not only an explicit logout button. In the test plan, use two separate customer accounts and inspect which profile receives each conversation.

## Customer context

Start with the fields an agent needs to answer a real support question. A small, maintained contract is easier to trust than a large collection of fields with uncertain meanings. Record the business definition, source, owner and update trigger for each field.

| Proposed field | Business meaning | Preferred authority | Acceptance case |
| --- | --- | --- | --- |
| Stable customer ID | The authenticated person | Application identity system | Same person after email change |
| Company association | The account relevant to this session | Authorized account membership | Account switch without stale company context |
| Plan | Current service entitlement | Billing or subscription system | Upgrade and downgrade reflected correctly |
| Usage milestone | A defined product state | Product backend | Completion changes the expected field |
| Preferred language | Support language preference | Customer preference record | Agent sees the intended value |

Intercom distinguishes custom attributes, which describe customer facts, from events, which represent recurring actions. Choose between them deliberately: a current subscription plan is a state, while repeated successful exports are occurrences. [Custom data attributes](https://www.intercom.com/help/en/articles/179-create-and-track-custom-data-attributes-cdas).

Keep timestamps and types explicit. For example, Intercom's `created_at` field uses Unix seconds; `session_duration` uses an integer number of milliseconds. Those values are not interchangeable. A visitor without identifying details becomes a lead after sending a message, which is different from booting a known user. [JavaScript attributes and objects](https://developers.intercom.com/installing-intercom/web/attributes-objects).

Do not send account secrets, payment credentials or unnecessary message contents as convenience attributes. Choose the minimum context that supports the intended interaction. If agents need to look up sensitive account data, design an authorized retrieval process instead of copying everything into a profile.

For a wider field contract and support handoff, use the [customer context guide](https://www.martechdevs.com/blog/support-customer-context). Document how an agent distinguishes missing context from a valid zero, an empty value or an outdated account selection.

## Mobile installation

Treat each mobile platform as its own release. A successful web installation does not establish that a mobile SDK is initialized, securely identified or able to receive a push notification. Match the app's credentials and data hosting region to the intended workspace. Intercom's mobile setup separates installation, security and optional push configuration. [Mobile installation overview](https://www.intercom.com/help/en/articles/567786-install-and-use-intercom-in-your-mobile-app).

### iOS setup

For a new iOS integration, add Intercom through Swift Package Manager and initialize it using the appropriate application lifecycle entry point. Review the required camera usage description and any additional permissions your chosen features need. Intercom currently marks CocoaPods support as deprecated and recommends Swift Package Manager or manual framework installation. [iOS installation](https://developers.intercom.com/installing-intercom/ios/installation).

Set the server-issued JWT before registering the user. Intercom documents `setUserJwt` from iOS SDK 18.7.0 onward. If mobile versions are already distributed, enforcing security can stop older versions from communicating, so the rollout needs an explicit compatibility decision. [iOS Messenger security](https://developers.intercom.com/installing-intercom/ios/secure-your-messenger).

### Android setup

Choose the Android dependency with or without push support, pin the selected SDK version, and initialize Intercom in the application's `onCreate()` method. The installation guide identifies that location as necessary for correct SDK behavior. [Android installation](https://developers.intercom.com/installing-intercom/android/installation).

Set the JWT before user registration. Android's `setUserJwt` requires SDK 15.16.0 or later; the newer token-provider refresh API has its own version requirement. If using that provider, return the token for the currently authenticated user because the provider remains registered after logout. Validate expiry and account changes against the exact SDK version being shipped. [Android Messenger security](https://developers.intercom.com/installing-intercom/android/secure-your-messenger).

Push delivery deserves a separate device case. For Android, configure Firebase credentials and route Intercom notifications separately from the application's own messages where both share Firebase Messaging. Test permission refusal, permitted delivery and opening the intended conversation. [Android push configuration](https://developers.intercom.com/installing-intercom/android/fcm-push-notifications).

## Acceptance workflow

![Authenticated audiences receive server identity and tokens; anonymous audiences receive visitor configuration. Conversation and session-isolation checks branch to scope and lifecycle repair on failure. Accepted identity proceeds to support readiness, with routing repair repeating handoff validation before release.](https://www.martechdevs.com/assets/blog/how-to-install-intercom.svg)

Diagram connections:

- Installation scope to Authenticated audience. 
- Authenticated audience to Server identity and token: Yes. 
- Authenticated audience to Anonymous visitor configuration: No. 
- Server identity and token to Conversation and context checks. 
- Anonymous visitor configuration to Conversation and context checks. 
- Conversation and context checks to Accepted identity and session isolation. 
- Accepted identity and session isolation to Configuration and lifecycle repair: No. 
- Configuration and lifecycle repair to Installation scope. 
- Accepted identity and session isolation to Routing and support readiness: Yes. 
- Routing and support readiness to Accepted handoff. 
- Accepted handoff to Routing and content repair: No. 
- Routing and content repair to Routing and support readiness. 
- Accepted handoff to Reviewed release: Yes

The identity repair returns to scope because the cause may be the wrong workspace, audience or installation owner. Changing only the visible launcher would leave those choices untested. Routing repairs return to support readiness because a correct profile can still reach the wrong team or an unusable help answer.

| Test case | Expected result | Evidence | Failure owner |
| --- | --- | --- | --- |
| New anonymous visitor | Appropriate public conversation | Visitor journey and resulting lead | Website team |
| Authenticated customer | Correct profile and approved context | Profile ID and conversation record | Application team |
| Invalid or expired token | Rejected request with diagnosable error | Installation log and request time | Backend team |
| Customer A logout, customer B login | No inherited customer A session | Same-device account switch record | Application team |
| Plan or company change | Intended current context | Before and after field values | Data owner |
| Human support handoff | Expected destination and useful context | Conversation assignment and agent review | Support owner |

Call `shutdown` for normal logout. The methods reference also describes cookie deletion when shutdown cannot run, such as when the library has not loaded. Separately, Intercom's current JavaScript methods guidance says `shutdown` alone does not remove every Intercom cookie. On shared devices, the anonymous identifier can persist, so the logout flow should also clear the relevant `intercom-` cookies. The same reference limits `update` calls to 20 per 30 minutes before throttling. [JavaScript methods](https://developers.intercom.com/installing-intercom/web/methods).

Use the [martech integration engineering skill](https://www.martechdevs.com/skills/martech-integration-engineering) to turn these cases into a repeatable release handoff. Record the application version, workspace, test identities, observed result and owner of any remaining defect. A screenshot of the launcher alone is insufficient evidence for identity acceptance.

## Launch checklist

- [ ] Confirm the workspace, hosting region and production domains.
- [ ] Assign one installation owner and remove duplicate loader paths.
- [ ] Validate server-authorized identity and protected context fields.
- [ ] Confirm the intended enforcement setting for each supported client.
- [ ] Check logout, session expiry and same-device account switching.
- [ ] Validate mobile credentials and notification behavior separately.
- [ ] Confirm the support destination and escalation owner.
- [ ] Review the help content and permitted actions before enabling Fin for that audience.
- [ ] Record unresolved defects, release boundaries and a rollback owner.

A phased release can start with a bounded audience and a staffed support destination. Keep a way to disable the affected entry point while retaining a usable support alternative. Recheck the original failing case after every repair, then repeat related identity cases if the repair changes login, cookies or company selection.

For an installation already in production, use [Intercom implementation mistakes](https://www.martechdevs.com/blog/intercom-implementation-mistakes) to investigate broader routing and workflow problems. This launch checklist should become part of the application's release process whenever authentication or customer context changes.

## Frequently asked questions

### Can Intercom be installed before users create an account?

Yes, the web Messenger can serve anonymous visitors before account creation. Keep authenticated customer fields out of that configuration and define the intended public support experience. When a visitor later signs in, validate the transition to the correct customer record and ensure the application supplies its trusted identity rather than copying details from an unverified form.

### Is a visible Messenger enough to approve an Intercom installation?

No, a visible Messenger establishes only one part of the installation. Approval should also cover the resulting contact, conversation destination, relevant customer context and session isolation. Have a support teammate review a controlled conversation, then repeat the journey with a second account on the same device to check the identity boundary.

### Does the Messenger secret belong in a frontend environment variable?

No, the signing secret belongs on the server. A value included in a frontend bundle remains available to the browser regardless of its variable name. The frontend should receive the user's signed token through the application's authenticated flow, while server authorization determines which identity and customer fields that token contains.

### Should web and mobile installations share one acceptance result?

No, each platform needs its own acceptance evidence. Web session cleanup, native SDK initialization and push handling follow different paths, even when they connect to the same workspace. Keep a shared identity contract, then record separate results for the supported web, iOS and Android versions and their relevant login and logout journeys.

### Can Fin configuration wait until Messenger installation is accepted?

Yes, Fin configuration can follow the initial installation acceptance. First establish reliable identity, useful context and a working human support destination. Then review the knowledge sources, permitted actions and escalation conditions for the intended audience. This sequence gives the team a clear baseline when evaluating whether an automated interaction behaves as intended.

## Sources

1. [Intercom web installation](https://developers.intercom.com/installing-intercom/web/installation)

2. [Intercom JWT authentication](https://www.intercom.com/help/en/articles/10589769-authenticating-users-in-the-messenger-with-json-web-tokens-jwts)

3. [Messenger Security migration](https://www.intercom.com/help/en/articles/10807823-migrating-from-identity-verification-to-messenger-security-with-jwts)

4. [Custom data attributes](https://www.intercom.com/help/en/articles/179-create-and-track-custom-data-attributes-cdas)

5. [JavaScript attributes and objects](https://developers.intercom.com/installing-intercom/web/attributes-objects)

6. [Mobile installation overview](https://www.intercom.com/help/en/articles/567786-install-and-use-intercom-in-your-mobile-app)

7. [iOS installation](https://developers.intercom.com/installing-intercom/ios/installation)

8. [iOS Messenger security](https://developers.intercom.com/installing-intercom/ios/secure-your-messenger)

9. [Android installation](https://developers.intercom.com/installing-intercom/android/installation)

10. [Android Messenger security](https://developers.intercom.com/installing-intercom/android/secure-your-messenger)

11. [Android push configuration](https://developers.intercom.com/installing-intercom/android/fcm-push-notifications)

12. [JavaScript methods](https://developers.intercom.com/installing-intercom/web/methods)

13. [MDN cookie scope and removal](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies)
