Intercom Node.js & TypeScript Library

List endpoints return a paginated response. You can iterate through all items using an async iterator, or manually navigate pages using hasNextPage() and getNextPage().

import { IntercomClient } from "intercom-client";

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

// Option 1: Using an async iterator (recommended)
const pageableResponse = await client.articles.list();
for await (const item of pageableResponse) {
    console.log(item);
}

// Option 2: Manual page-by-page iteration
let page = await client.articles.list();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// Access the underlying response object
const response = page.response;

The unstable.customObjectInstances namespace provides methods to manage custom object instances.

Available Operations:

• getCustomObjectInstancesByExternalId: Fetch an instance using its external_id.
• getCustomObjectInstancesById: Fetch an instance using its Intercom-defined id.
• createCustomObjectInstances: Create or update a custom object instance.
• deleteCustomObjectInstancesById: Delete an instance using its Intercom-defined id.
• deleteCustomObjectInstancesByExternalId: Delete an instance using its external_id.

Install the intercom-client package using npm:

npm i -s intercom-client

To use the SDK, instantiate IntercomClient by providing your Intercom API token in the configuration object.

import { IntercomClient } from "intercom-client";

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

// Example API call
await client.aiContent.createContentImportSource({
    url: "https://www.example.com"
});

The CustomChannelEventsClient allows you to bring Fin and Intercom capabilities to your own platform via API. By treating your integration like an Intercom channel, you can exchange events seamlessly, enabling users to interact with Fin directly within your own application's UI.

Note: This feature is currently under managed availability. You must reach out to your Intercom accounts team to discuss access and support.

import { CustomChannelEventsClient } from 'intercom-client';

const client = new CustomChannelEventsClient({
  // ... client options
});

// Use client.customChannelEvents to access event notification methods
await client.customChannelEvents.notifyNewConversation({
    event_id: "event_id",
    external_conversation_id: "external_conversation_id",
    contact: {
        type: "user",
        external_id: "external_id"
    }
});

The IpAllowlistClient allows you to configure which IP addresses are permitted to access the Intercom API and web application for your workspace. This is used to restrict access to specific corporate networks or VPNs.

Important Requirements:

• This endpoint requires the manage_ip_allowlist OAuth scope.
• Lockout Protection: The API will reject updates that would lock out the caller's IP address. Always ensure your current IP address is included in the allowlist when enabling this feature.

Common Errors:

• Intercom.UnauthorizedError: Thrown if authentication fails (401).
• Intercom.UnprocessableEntityError: Thrown if the update request is invalid (422), such as when an update would cause a lockout.

The SDK supports logging via the logging configuration object in the IntercomClient constructor. By default, logging is silent (silent: true) and uses logging.LogLevel.Info with a logging.ConsoleLogger.

To use a custom logger, implement the logging.ILogger interface.

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

const client = new IntercomClient({
    logging: {
        level: logging.LogLevel.Debug,
        logger: new logging.ConsoleLogger(),
        silent: false,
    }
});

// Example: Custom logger using Winston
const logger: logging.ILogger = {
    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
    info: (msg, ...args) => winstonLogger.info(msg, ...args),
    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
    error: (msg, ...args) => winstonLogger.error(msg, ...args),
};