Intercom Contacts & Contact Management

Intercom Contacts & Contact Management

Overview

Primary workflow for managing Intercom contacts. Covers creating users and leads, searching with filters, updating custom attributes, merging leads into users, and listing segments. This SKILL.md gives you the high-level workflow and the first example; drill into references/implementation.md for the full step-by-step code and references/examples.md for end-to-end flows.

Prerequisites

• Completed intercom-install-auth setup
• Understanding of Intercom contact model (users vs leads)
• Valid API credentials with contacts read/write scope

Instructions

The contact workflow is six operations against the intercom-client SDK. Instantiate the client once, then call the operation you need:

import { IntercomClient } from "intercom-client";

const client = new IntercomClient({
  token: process.env.INTERCOM_ACCESS_TOKEN!,
});

// Create an identified user (has external_id)
const user = await client.contacts.create({
  role: "user",
  externalId: "customer-9001",
  email: "[email protected]",
  name: "Alice Johnson",
  customAttributes: { plan: "enterprise" },
});

The six operations, in the order you typically reach for them:

1. Create contacts — contacts.create with role: "user" (identified, needs externalId) or role: "lead" (anonymous).
2. Search contacts — contacts.search with a single filter or a compound AND/OR query, plus pagination and sort.
3. Update a contact — contacts.update by contactId to change name or custom attributes.
4. Merge a lead into a user — contacts.merge({ from: leadId, into: userId }); the lead's conversations, events, and tags transfer to the user.
5. List segments — contacts.listSegments({ contactId }) to see which segments a contact belongs to.