Intercom Multi-Environment Setup

Overview

Configure separate Intercom workspaces for development, staging, and production with environment-specific access tokens, webhook URLs, and safety guards. This skill establishes a single config loader, an environment-aware client factory, per-platform secret storage, and production guards so the same codebase behaves correctly in every environment.

The full step-by-step code lives in references/implementation.md; this file carries the workflow and the Step 1 skeleton so you can follow it end to end, then drill into the reference for depth.

Prerequisites

• Separate Intercom workspaces (or at minimum, separate apps in Developer Hub)
• Secret management solution (Vault, AWS Secrets Manager, GCP Secret Manager)
• CI/CD pipeline with environment variable support

Environment Strategy

Instructions

Work through six steps. Read the Step 1 skeleton below to see the shape of the config, then open references/implementation.md for the complete code of every step.

1. Environment Configuration — a single loadConfig() reads NODE_ENV and merges shared secrets with per-environment defaults (debug, cache TTL, rate-limit concurrency). Skeleton below.
2. Environment-Aware Client Factory — a lazily-initialised getClient() that throws a clear, environment-named error when the token is missing.
3. Secret Management by Platform — store tokens in git-ignored .env.<environment> files locally and in GitHub Actions, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault in CI/prod.
4. Production Safety Guards — an EnvironmentGuard with requireProduction() / preventProduction() so destructive jobs can never fire in the wrong workspace.
5. Webhook URL per Environment — map NODE_ENV to the correct public webhook URL so no code changes between deploys.
6. Environment Validation on Startup — probe the workspace on boot; fail fast in production, warn (but continue) elsewhere.

Step 1 skeleton — the config loader every other step depends on:

// src/config/intercom.ts
function loadConfig(): IntercomEnvironmentConfig {
  const env = (process.env.NODE_ENV || "development") as IntercomEnvironmentConfig["environment"];
  const shared = {
    accessToken: process.env.INTERCOM_ACCESS_TOKEN!,
    webhookSecret: process.env.INTERCOM_WEBHOOK_SECRET!,
    environment: env,
    baseUrl: "https://api.intercom.io",
  };
  const envDefaults = {
    development: { debug: true, cache: { enabled: false, ttlSeconds: 0 }, rateLimit: { maxConcurrency: 2 } },
    staging: { debug: false, cache: { enabled: true, ttlSeconds: 60 }, rateLimit: { maxConcurrency: 5 } },
    production: { debug: false, cache: { enabled: true, ttlSeconds: 300 }, rateLimit: { maxConcurrency: 10 } },
  };
  return { ...shared, ...envDefaults[env] } as IntercomEnvironmentConfig;
}
export const intercomConfig = loadConfig();

See references/implementation.md for the full IntercomEnvironmentConfig interface, the client factory, all four secret-store commands, the guard class, the webhook map, the startup validator, and the GitHub Actions environment matrix.

Output

Applying this skill produces:

• src/config/intercom.ts — the environment-aware config loader (intercomConfig).
• src/intercom/client.ts — the memoised getClient() factory.
• Per-environment secret sets: git-ignored .env.<environment> files locally plus tokens in your CI/prod secret store (INTERCOM_DEV_TOKEN, INTERCOM_STAGING_TOKEN, INTERCOM_PROD_TOKEN).
• An EnvironmentGuard wired into destructive and production-only operations.
• A startup log line confirming the connected workspace, e.g. [Intercom] Connected to staging workspace.

At runtime, validateIntercomSetup() prints [Intercom] Validating <environment> setup... followed by the connected admin, and throws (production) or warns (dev/staging) if the token cannot reach the workspace.

Error Handling

Examples

Three worked, end-to-end scenarios are in references/examples.md:

• Bootstrap a new staging workspace — create the secret set, mirror it into CI, and confirm the workspace via startup validation.
• Guard a destructive cleanup job — use preventProduction() so a nightly test-contact purge can never run against production.
• Route webhooks per environment in CI — a GitHub Actions matrix that sets NODE_ENV so each deploy selects the correct token and webhook URL.

Quick taste — guarding a destructive job so it can never touch production:

const guard = new EnvironmentGuard(intercomConfig.environment);

async function nightlyCleanup() {
  guard.preventProduction("nightlyCleanup"); // throws if NODE_ENV=production
  await deleteAllTestContacts();
}

Resources

• Full implementation walkthrough
• Worked examples
• Intercom Developer Hub
• Authentication
• 12-Factor App Config
• For observability setup, see the intercom-observability skill.