Intercom SDK Patterns

Overview

Production-ready patterns for the intercom-client TypeScript SDK covering

client initialization, cursor-based pagination, error handling, retry with

backoff, compound search, and multi-tenant client factories. Use this skill to

Read existing Intercom code, then Write or Edit it to match these patterns —

type-safe singletons, memory-efficient pagination, and resilient error handling.

The SKILL.md body carries the essential skeletons (client wrapper, pagination,

error-handling shape). Deep implementations and worked examples live in

references/ so you can drill in only when you need them:

• Full implementation patterns — error handling,

retry/backoff, multi-tenant factory, search-operator table.

• Worked examples — pagination, compound search,

combined retry + safe-call.

Prerequisites

• intercom-client package installed (npm install intercom-client).
• TypeScript 5.0+ project with strict mode enabled.
• Familiarity with async/await and async generators.
• An Intercom access token available at runtime (see Authentication below).

Authentication

The SDK authenticates with a workspace access token passed to the

IntercomClient constructor. Store it in the INTERCOMACCESSTOKEN environment

variable — never hardcode it. Generate the token from Intercom's Developer Hub

(Settings → Authentication). For multi-workspace apps, each workspace has its own

token; see the multi-tenant factory in

references/implementation.md.

Instructions

Step 1: Type-Safe Client Wrapper

Create one lazily-initialized singleton client plus thin, typed helpers. This

keeps a single connection pool and gives every call-site full SDK types.

// src/intercom/client.ts
import { IntercomClient } from "intercom-client";
import { Intercom } from "intercom-client";

let instance: IntercomClient | null = null;

export function getClient(): IntercomClient {
  if (!instance) {
    instance = new IntercomClient({
      token: process.env.INTERCOM_ACCESS_TOKEN!,
    });
  }
  return instance;
}

// Type-safe contact creation helper
export async function createContact(
  params: Intercom.CreateContactRequest
): Promise<Intercom.Contact> {
  return getClient().contacts.create(params);
}

Step 2: Cursor-Based Pagination

Intercom lists are cursor-paginated — starting_after points to the next page.

Prefer the SDK's built-in async iteration, which manages the cursor for you:

const response = await client.articles.list();
for await (const article of response) {
  console.log(article.title);
}

When explicit control is needed, an alternative option is a custom generator

that yields each item and advances startingAfter until the cursor is

exhausted. Choose auto-iteration for simplicity, or the manual generator when a

custom perPage, early exit, or per-page side effects are required. Both

variants: references/examples.md.

Step 3: Error Handling and Retry

Wrap every call so a thrown IntercomError becomes a normalized

{ data, error } result, then layer retry/backoff on transient failures (429,

5xx). Skeleton:

import { IntercomError } from "intercom-client";

try {
  const data = await client.contacts.find({ contactId: "abc123" });
  // use data
} catch (err) {
  if (err instanceof IntercomError) {
    // inspect err.statusCode (401/404/409/422/429), err.body?.errors
  }
  throw err; // re-throw non-Intercom errors
}

Full safeIntercomCall wrapper, withRetry exponential-backoff helper (with

Retry-After support), and compound search live in

references/implementation.md.

Output

Applying this skill produces TypeScript source that follows these patterns:

• A singleton client module (e.g. src/intercom/client.ts) exporting getClient

and typed helpers.

• Pagination code that streams items via async iteration instead of buffering

full result sets.

• API calls wrapped in safeIntercomCall returning { data, error }, with

withRetry applied to rate-limited and server-error responses.

• No hardcoded tokens — all auth reads INTERCOMACCESSTOKEN (or a per-workspace

token via the factory).

Error Handling

Status codes to handle explicitly: 401 (bad/expired token), 404 (missing

resource), 409 (conflict/duplicate), 422 (validation — check

err.body?.errors), 429 (rate limited — back off). Full switch-based handler:

references/implementation.md.

Examples

• Pagination — manual generator plus SDK auto-iteration:

references/examples.md.

• Compound search — AND/OR conditions with sort and pagination:

references/examples.md.

• Resilient call — withRetry composed with safeIntercomCall:

references/examples.md.

Minimal end-to-end shape:

import { getClient } from "./intercom/client";

const client = getClient();
const contact = await client.contacts.create({
  role: "user",
  email: "new@acme.com",
});
console.log(contact.id);

Resources

• intercom-client npm
• Intercom API Reference
• Search Contacts

Next Steps

Apply these patterns alongside intercom-core-workflow-a for contact management

workflows. For the full implementation catalog and worked examples, open

references/implementation.md and

references/examples.md.