@helpnest/intercom

Migrate your Intercom Articles to HelpNest in one command.

What it does

@helpnest/intercom connects to the Intercom Help Center API, pulls your collections and articles, converts the HTML body of each article to Markdown, then creates them in your HelpNest instance via the REST API.

Migration order:

1. All collections are fetched and created in HelpNest first (parent collections before children where possible).
2. Each article is transformed and created inside its mapped collection.

Prerequisites

| Requirement | Where to get it | |---|---| | Intercom Access Token | Intercom → Settings → Developers → Access Token | | HelpNest API Key | HelpNest Dashboard → Settings → API Keys | | Node 18+ | nodejs.org |

Install

Global install (recommended for repeated use):

npm install -g @helpnest/intercom
helpnest-intercom migrate --help

One-off via npx (no install required):

npx @helpnest/intercom migrate --help

Usage

helpnest-intercom migrate [options]

Options

| Flag | Environment variable | Default | Description | |---|---|---|---| | --intercom-token <token> | INTERCOM_ACCESS_TOKEN | — | Intercom Access Token (required) | | --helpnest-url <url> | HELPNEST_URL | http://localhost:3000 | HelpNest base URL | | --helpnest-key <key> | HELPNEST_API_KEY | — | HelpNest API key (required unless --dry-run) | | --dry-run | — | false | Print what would be migrated; no API writes | | --collections-only | — | false | Migrate collections only, skip articles | | --state <state> | — | published | Which Intercom article state to migrate: published, draft, or all |

All options can be supplied via environment variables instead of flags.

Examples

Dry run first (always recommended)

INTERCOM_ACCESS_TOKEN=your_token \
HELPNEST_URL=https://help.yourcompany.com \
HELPNEST_API_KEY=hn_your_api_key \
  npx @helpnest/intercom migrate --dry-run

Full migration (published articles only)

INTERCOM_ACCESS_TOKEN=your_token \
HELPNEST_URL=https://help.yourcompany.com \
HELPNEST_API_KEY=hn_your_api_key \
  npx @helpnest/intercom migrate

Migrate all articles (published + draft)

npx @helpnest/intercom migrate \
  --intercom-token your_token \
  --helpnest-url https://help.yourcompany.com \
  --helpnest-key hn_your_api_key \
  --state all

Migrate collections only

npx @helpnest/intercom migrate \
  --intercom-token your_token \
  --helpnest-url https://help.yourcompany.com \
  --helpnest-key hn_your_api_key \
  --collections-only

What gets migrated

| Item | Migrated | Notes | |---|---|---| | Collections | Yes | Hierarchy preserved where possible | | Articles | Yes | All fields mapped | | HTML body → Markdown | Yes | Converted via node-html-markdown | | Author info | No | HelpNest assigns the API key's user as author | | Inline images | Preserved as-is | Image URLs are kept in Markdown ![]() syntax | | Attachments | No | Intercom file attachments are not included |

After migration

1. Review draft articles in your HelpNest dashboard — any Intercom draft articles migrated with --state draft or --state all will land as drafts and require publishing.

2. Check collection nesting — if your Intercom workspace uses deeply nested sections the parent mapping may need manual adjustment depending on your HelpNest collection depth limits.

3. Images — article images reference Intercom's CDN URLs. Download and re-host them in HelpNest's media library if you need them to be self-contained.

License

MIT