v6.0.0

v6.0.0

The Intercom team is excited to announce a new and improved TypeScript SDK. Check out the API reference here.

Installation

Install the latest version by running the following command:

npm

npm install intercom-client

pnpm

pnpm install intercom-client

yarn

yarn add intercom-client

bun

bun install intercom-client

New Features

1. Strongly typed

All types and endpoints are strongly typed and up to date with Intercom’s latest API.

In version 5.0.0, some of the SDK types included any and unknown properties, which put more onus on the caller to determine what type was expected.

But with the new SDK, you’ll always know exactly what type you’re working with. For example, consider the RequestOptions type:

Before

interface RequestOptions {
    url: string;
    data?: any;
    params?: any;
}

After

interface RequestOptions {
    /** The maximum time to wait for a response in seconds. */
    timeoutInSeconds?: number;
    /** The number of times to retry the request. Defaults to 2. */
    maxRetries?: number;
    /** A hook to abort the request. */
    abortSignal?: AbortSignal;
    /** Override the Intercom-Version header */
    version?:
        | "1.0"
        | "1.1"
        | "1.2"
        | "1.3"
        | "1.4"
        | "2.0"
        | "2.1"
        | "2.2"
        | "2.3"
        | "2.4"
        | "2.5"
        | "2.6"
        | "2.7"
        | "2.8"
        | "2.9"
        | "2.10"
        | "2.11"
        | "Unstable";
}

2. Rich documentation

The new SDK includes in-lined documentation on both endpoints and object properties. This helps the user recognize exactly what parameters need to be specified and allows them to iterate even faster.

For example, consider the following endpoint documentation:

/**
 * You can update the details of a single article by making a PUT request to `https://api.intercom.io/articles/<id>`.
 *
 * @param {Intercom.UpdateArticleRequest} request
 * @param {Articles.RequestOptions} requestOptions - Request-specific configuration.
 *
 * @throws {@link Intercom.UnauthorizedError}
 * @throws {@link Intercom.NotFoundError}
 *
 * @example
 *     await client.articles.update({
 *         article_id: "123",
 *         title: "Christmas is here!",
 *         body: "<p>New gifts in store for the jolly season</p>"
 *     })
 */
public async update(
    request: Intercom.UpdateArticleRequest,
    requestOptions?: Articles.RequestOptions
): Promise<Intercom.Article> {
  ...
}

3. Improved exception handling

The SDK now defines structured errors that users can use to influence their program’s control flow. For example, consider the following:

import { Intercom } from "intercom-client";
try {
    await client.articles.update(...);
} catch (err) {
    if (err instanceof Intercom.NotFoundError) {
        // Do something with the 404 ...
    }
}

With this, users can write their programs to take specific actions whenever an endpoint returns any of the well-known Intercom errors (the Intercom.NotFoundError in this case).

4. Auto-pagination

Intercom’s paginated endpoints now support auto-pagination with an async iterator.

Callers don’t need to manually fetch the next page at all - they can simply iterate over the entire list, and the client will automatically fetch the next page behind the scenes.

Before

const response = client.companies.list({});
for (const company of response.data) {
    // Do something with the company …
}

if (response.pages.next != null) {
    // Fetch the next page, and keep iterating …
}

After

const companies = client.companies.list();
for await (const company of companies) {
    // Do something with the company …
}

5. Version selection

The Intercom client now includes version selection support.

The SDK is configured to use the latest stable version by default (i.e. 2.11), but users can override this value to influence the behavior of the server. Configuring a version is as simple as the following:

const client = new IntercomClient({ token, version: "2.11" });

Migration Guide

These improvements include a few breaking changes (primarily related to request parameters), which are categorized by the following:

1. Client constructor

The client constructor is simplified and doesn’t require a nested type to specify the API token.

Before

const client = new Client({
    tokenAuth: { token },
});

After

const client = new IntercomClient({ token });

2. Parameters names

You’ll notice a few parameter names have changed. Primarily, id parameters are often prefixed with their resource type, for example: contact_id.

Before

const response = client.contacts.listAttachedCompanies({
    id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
});

After

const response = client.contacts.listAttachedCompanies({
    contact_id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
});

3. Request properties naming convention (camelCase -> snake_case).

Request properties now use the snake_case naming convention, whereas response properties preserve the camelCase naming convention.

Before

const response = client.contacts.listAttachedCompanies({
  id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b"
  perPage: 1,
})

After

const response = client.contacts.listAttachedCompanies({
    contact_id: "c89b0cd0-ab8a-43f0-8f03-4972427c446b",
    per_page: 1,
});

4. Request parameters with body property

The client.conversations.reply and client.conversations.manage functions now accept a request object where most parameters are in the body property.

const replyResponse = await client.conversations.reply({
    conversation_id: conversationId,
    body: {
        message_type: "comment",
        type: "admin",
        body: "test",
        admin_id: adminId,
    }
});

const openResponse = await client.conversations.manage({
    conversation_id: conversationId,
    body: {
        message_type: "open",
        admin_id: adminId,
    }
});

5. Assigning a conversation

Previously, you could manually and auto-assign a conversation using a single function client.conversations.assign() by passing different parameters to it.

Before

// manually assign conversation
const manualAssignResponse = await client.conversations.assign({
    id,
    assigneeId: anotherAdminId,
    adminId,
    type: AssignToConversationUserType.ADMIN,
});

// run assignment rules
const autoAssignResponse = await client.conversations.assign({
    id,
    withRunningAssignmentRules: true,
});

In the new SDK, you can manually assign and auto-assign using the client.conversations.manage() and client.conversations.runAssignmentRules() function.

After

// manually assign conversation
const response = await client.conversations.manage({
    conversation_id,
    body: {
        message_type: "assignment",
        type: "admin",
        admin_id: adminId,
        assignee_id: secondAdminId,
    }
});

// run assignment rules
const response = await client.conversations.runAssignmentRules({
    conversation_id,
});