Intercom sdk patterns

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 INTERCOM_ACCESS_TOKEN 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 INTERCOM_ACCESS_TOKEN (or a per-workspace token via the factory).

Error Handling

Pattern	Use Case	Benefit
safeIntercomCall wrapper	All API calls	Prevents uncaught exceptions
withRetry	Transient failures (429, 5xx)	Automatic recovery
Cursor pagination generator	Large data sets	Memory-efficient streaming
Client factory	Multi-tenant apps	Workspace isolation

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: "[email protected]",
});
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.