Intercom Upgrade & Migration Skill

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 INTERCOM_ACCESS_TOKEN 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

| Issue | Detection | Solution | |-------|-----------|----------| | Cannot find module 'intercom-client' | Import fails | npm install intercom-client | | Property 'users' does not exist | TypeScript error | Migrate users/leads to contacts | | Property 'id' does not exist | Changed param names | Use contactId, conversationId | | Response shape changed | Runtime errors | Check API version headers, pin Intercom-Version | | 401 Unauthorized | curl/test fails | Verify INTERCOM_ACCESS_TOKEN is set and valid |

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

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.

Agent Skills: Intercom Upgrade & Migration

Install this agent skill to your local

Skill Files