Intercom Upgrade & Migration

Overview

Upgrade the intercom-client npm package and handle Intercom API version

changes without breaking production traffic. The v6 TypeScript rewrite changed

the API surface — most notably unifying users/leads into a single contacts

API — so this skill drives a branch-based, type-checked upgrade that surfaces

every breaking change through the compiler and test suite before merge.

Deep material lives in references/ so this file stays scannable:

• Full v5 → v6 migration guide — every changed

operation with before/after code, API-version pinning, the upgrade procedure,

type-import changes, and the method cheat sheet.

• Worked examples — three end-to-end runs from version

detection through a committed upgrade branch.

Prerequisites

• A project with intercom-client already installed (npm list intercom-client

shows the current version).

• Git available for branch-based upgrades and reviewable diffs.
• A working test suite, ideally including an integration suite that can run

against a dev Intercom workspace.

• TypeScript (tsc) configured if migrating to v6+, since the compiler is the

primary breaking-change detector.

Authentication

Intercom API calls authenticate with a workspace access token passed as a Bearer

token. Read it from the INTERCOMACCESSTOKEN environment variable — never

hardcode it. Version-detection curls and the integration test step both consume

this variable:

export INTERCOM_ACCESS_TOKEN="<workspace-access-token>"   # from Intercom > Developer Hub

Use a separate dev-workspace token ($DEV_TOKEN) for the integration test step

so the upgrade is validated without touching production data.

Instructions

Follow the workflow at a high level here; drill into

the migration guide for the exact code diffs.

Step 1: Check current versions

Read (with the Read tool or npm list) the installed version, the latest

published version, and the live API version to size the upgrade:

npm list intercom-client                  # installed SDK version
npm view intercom-client version          # latest available
curl -s -D - -o /dev/null \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  https://api.intercom.io/me 2>/dev/null | grep -i intercom-version

If the installed major is < 6 and the target is ≥ 6, expect the TypeScript-rewrite

breaking changes.

Step 2: Migrate the code (v5 → v6)

For a major crossing, apply the breaking-change diffs with the Edit/Write

tools: swap new Intercom.Client() for new IntercomClient(), move

users/leads calls to the unified contacts API, rename positional params

(id → contactId/conversationId), and update error handling to the

IntercomError instance check. The full before/after set and a one-line-per-method

cheat sheet are in the migration guide.

Step 3: Pin the API version if needed

The SDK sends a compatible Intercom-Version header automatically. Pin it

explicitly only when using raw fetch requests or when a response shape must be

frozen — see the API-version-pinning section of the migration guide.

Step 4: Run the type-checked upgrade on a branch

Do the whole upgrade on a dedicated branch so TypeScript and the tests gate it:

git checkout -b upgrade/intercom-client-v6
npm install intercom-client@latest
npx tsc --noEmit 2>&1 | grep "intercom"    # surfaces every breaking change
npm test

Fix each error the compiler reports, re-run until clean, then validate against a

dev workspace and commit. The complete procedure is in the migration guide.

Output

Running this skill produces:

• A dedicated upgrade branch (e.g. upgrade/intercom-client-v6) with

intercom-client bumped in package.json / lockfile.

• Source edits that migrate every v5 call site to the v6 API surface.
• A clean npx tsc --noEmit run (no remaining intercom-client type errors) and

a green npm test / integration run against a dev workspace.

• A commit ready for PR, e.g. chore: upgrade intercom-client to v6.

Error Handling

Examples

Quick skeleton — detect, then migrate one call:

npm list intercom-client        # e.g. 5.4.0
npm view intercom-client version # e.g. 6.4.0 → major upgrade

// v5  → migrate to →  v6
// await client.users.create({ email });
await client.contacts.create({ role: "user", email });

Three full end-to-end runs — version detection, a single-call migration, and a

complete branch upgrade — are in references/examples.md.

Resources

• intercom-node GitHub
• SDK v6 Release Notes
• API Versioning
• intercom-client npm

Next Steps

After the upgrade branch is green, wire the version bump into CI so future

regressions are caught automatically — see the intercom-ci-integration skill

for the pipeline configuration.