Intercom Node.js Client

Common errors

• Error: INTERCOM_ACCESS_TOKEN environment variable is not set.

  cause The Intercom client was initialized without an API token, or the environment variable was missing.
  fix Set the `INTERCOM_ACCESS_TOKEN` environment variable with your actual Intercom API token or pass `{ token: 'YOUR_TOKEN' }` directly to the `IntercomClient` constructor. For production, environment variables are recommended.

• Intercom API Error [401]: Unauthorized

  cause The provided Intercom API token is invalid, expired, or lacks the necessary permissions for the requested action.
  fix Verify that your `INTERCOM_ACCESS_TOKEN` is correct and active in your Intercom workspace. Check if the token has the required scopes/permissions for the API endpoint you are calling.

• Intercom API Error [404]: Not Found

  cause The requested resource (e.g., user, conversation, article by ID) does not exist, or the endpoint path is incorrect.
  fix Double-check the IDs or parameters used in your API call. Review the Intercom API documentation to confirm the correct endpoint path and resource existence.

• Intercom API Error [429]: Too Many Requests

  cause You have exceeded Intercom's API rate limits for your workspace.
  fix The library has built-in retries, but for sustained high load, implement client-side rate limiting or back-off strategies in your application. Review Intercom's rate limit documentation.

Warnings

• breaking Version `7.0.0` of `intercom-client` introduced support for Intercom API v2.14. This major version bump likely includes breaking changes to the API surface, endpoint paths, or data structures. Users migrating from `v6.x` or earlier should consult the official Intercom API documentation and the client's reference for specific changes relevant to their utilized endpoints.
  Fix: Review your API calls against the Intercom API v2.14 documentation and update code to match new endpoint signatures, request bodies, and response structures.
• gotcha The library explicitly targets modern Node.js environments (`>=18.0.0`) and is written in TypeScript, preferring ES Module (ESM) import syntax. While CommonJS `require()` might partially function, using `import` statements is the recommended and best-supported approach, especially for type safety and future compatibility.
  Fix: Ensure your project is configured for ESM (`"type": "module"` in `package.json`) and use `import` syntax for all package imports.
• gotcha API errors (non-2xx HTTP responses) are encapsulated within `IntercomError` instances. Direct checks of `response.status` might not be necessary if you catch `IntercomError` to access `statusCode`, `message`, `body`, and `rawResponse` for comprehensive error handling.
  Fix: Wrap API calls in `try...catch` blocks and check if the caught error is an `instanceof IntercomError` to access detailed API error information.
• gotcha Pagination for list endpoints has specific patterns, either using `for await...of` iterators or manual `hasNextPage()` and `getNextPage()` methods on the returned `PageableResponse` object. Attempting to directly destructure a paginated response like a simple array will not work for fetching subsequent pages.
  Fix: Utilize the provided iteration patterns (`for await...of` or `page.hasNextPage()/getNextPage()`) to correctly traverse paginated results, as demonstrated in the library's usage examples.

Install

• npm install intercom-client npm
• yarn add intercom-client yarn
• pnpm add intercom-client pnpm

Imports

• IntercomClient
  wrong:

  const IntercomClient = require('intercom-client').IntercomClient;

  correct:

  import { IntercomClient } from 'intercom-client';

  Use named import for the main client class. CommonJS `require` is not officially supported and may lead to issues.
• Intercom
  wrong:

  import * as Intercom from 'intercom-client';

  correct:

  import { Intercom } from 'intercom-client';

  Import the `Intercom` namespace for accessing all exported request and response TypeScript types, e.g., `Intercom.User` or `Intercom.Article`.
• IntercomError
  wrong:

  import { Error } from 'intercom-client';

  correct:

  import { IntercomError } from 'intercom-client';

  Import `IntercomError` to properly catch and handle API-specific errors, which are instances of this class or its subclasses.

Quickstart

Initializes the Intercom client using an environment variable for the API token and demonstrates how to make an API call (e.g., importing AI content) with robust error handling using `IntercomError`.

import { IntercomClient, IntercomError } from "intercom-client";

// Initialize the Intercom client with an API token from environment variables.
// It's crucial to protect your Intercom API token and avoid hardcoding it.
const INTERCOM_ACCESS_TOKEN = process.env.INTERCOM_ACCESS_TOKEN ?? '';

if (!INTERCOM_ACCESS_TOKEN) {
  console.error("Error: INTERCOM_ACCESS_TOKEN environment variable is not set.");
  process.exit(1);
}

const client = new IntercomClient({ token: INTERCOM_ACCESS_TOKEN });

async function importContent() {
  try {
    // Example: Create a content import source for AI capabilities.
    // Replace with the actual endpoint and parameters you intend to use.
    const result = await client.aiContent.createContentImportSource({
      url: "https://www.example.com/your-business-faq-page",
      // Additional parameters might be required depending on the specific API call.
      // Refer to the Intercom API documentation for required fields.
    });
    console.log("Content import initiated successfully:", result);
  } catch (err) {
    if (err instanceof IntercomError) {
      console.error(`Intercom API Error [${err.statusCode}]: ${err.message}`);
      console.error("Error Body:", err.body);
      console.error("Raw Response:", err.rawResponse);
    } else {
      console.error("An unexpected error occurred:", err);
    }
  }
}

importContent();