intercom-core-workflow-a

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 managing tags and segments.

Prerequisites

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

Instructions

Step 1: Create Contacts

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: "alice@acme.com",
  name: "Alice Johnson",
  phone: "+1-555-0100",
  customAttributes: {
    plan: "enterprise",
    company_size: 500,
    signed_up_at: Math.floor(Date.now() / 1000),
  },
});
// Response: { type: "contact", id: "6657add46abd...", role: "user", ... }

// Create an anonymous lead (no external_id required)
const lead = await client.contacts.create({
  role: "lead",
  email: "visitor@example.com",
  name: "Website Visitor",
  customAttributes: {
    landing_page: "/pricing",
    utm_source: "google",
  },
});

Step 2: Search Contacts

POST to https://api.intercom.io/contacts/search with query filters.

// Simple search by email
const byEmail = await client.contacts.search({
  query: {
    field: "email",
    operator: "=",
    value: "alice@acme.com",
  },
});

// Compound search: users on enterprise plan who signed up recently
const filtered = await client.contacts.search({
  query: {
    operator: "AND",
    value: [
      { field: "role", operator: "=", value: "user" },
      { field: "custom_attributes.plan", operator: "=", value: "enterprise" },
      { field: "signed_up_at", operator: ">", value: Math.floor(Date.now() / 1000) - 86400 * 30 },
    ],
  },
  pagination: { per_page: 50 },
  sort: { field: "created_at", order: "descending" },
});

console.log(`Found ${filtered.totalCount} contacts`);
for (const contact of filtered.data) {
  console.log(`  ${contact.name} (${contact.email}) - plan: ${contact.customAttributes?.plan}`);
}

Step 3: Update a Contact

const updated = await client.contacts.update({
  contactId: user.id,
  name: "Alice Johnson-Smith",
  customAttributes: {
    plan: "enterprise_plus",
    upgraded_at: Math.floor(Date.now() / 1000),
  },
});

Step 4: Merge a Lead into a User

When an anonymous lead is identified, merge them into a user contact. The lead's conversation history transfers to the user.

// Lead must have role "lead", user must have role "user"
const merged = await client.contacts.merge({
  from: lead.id,  // Lead ID (will be deleted)
  into: user.id,  // User ID (will absorb lead data)
});

console.log(`Merged lead into user: ${merged.id}`);
// The lead's conversations, events, and tags are now on the user

Step 5: List Segments for a Contact

const segments = await client.contacts.listSegments({
  contactId: user.id,
});

for (const segment of segments.data) {
  console.log(`Segment: ${segment.name} (${segment.id})`);
}

Step 6: Paginate All Contacts

async function* allContacts(client: IntercomClient) {
  let startingAfter: string | undefined;

  do {
    const page = await client.contacts.list({
      perPage: 50,
      startingAfter,
    });

    for (const contact of page.data) {
      yield contact;
    }

    startingAfter = page.pages?.next?.startingAfter ?? undefined;
  } while (startingAfter);
}

// Stream all contacts
let count = 0;
for await (const contact of allContacts(client)) {
  count++;
  if (count % 100 === 0) console.log(`Processed ${count} contacts`);
}

Contact Data Model

Field	Type	Description
id	string	Intercom-generated unique ID
external_id	string	Your system's user ID
role	"user" or "lead"	Contact type
email	string	Email address
name	string	Full name
phone	string	Phone number
custom_attributes	object	Custom key-value data
created_at	number	Unix timestamp
last_seen_at	number	Last activity timestamp
signed_up_at	number	Signup timestamp
tags	object	Applied tags list
companies	object	Associated companies
location	object	GeoIP location data

Error Handling

Error	HTTP Code	Cause	Solution
not_found	404	Contact ID doesn't exist	Verify with search first
conflict	409	Duplicate external_id or email	Search before creating
parameter_invalid	422	Bad field value or missing required field	Check field types and names
rate_limit_exceeded	429	Over 10,000 req/min (private apps)	Add backoff, batch operations
merge_not_possible	400	Merging user into lead (reversed)	from must be lead, into must be user

Resources

• Contacts API
• Search Contacts
• Merge Contacts
• Contact Guides

Next Steps

For conversation management, see intercom-core-workflow-b.