Intercom Hello World Skill

Intercom Hello World

Overview

Minimal working examples covering the Intercom core data model: contacts (users and leads), conversations, messages, and tags.

Prerequisites

Completed intercom-install-auth setup
intercom-client package installed
Valid access token in environment

Instructions

Step 1: Create a Contact

Contacts are the core entity. They have a role of either user (identified) or lead (anonymous).

import { IntercomClient } from "intercom-client";

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

// Create a user contact
const user = await client.contacts.create({
  role: "user",
  externalId: "user-12345",
  email: "jane@example.com",
  name: "Jane Smith",
  customAttributes: {
    plan: "pro",
    signup_date: Math.floor(Date.now() / 1000),
  },
});

console.log(`Created contact: ${user.id} (${user.role})`);

// Response shape:
// {
//   type: "contact",
//   id: "6657add46abd0167d9419c3a",
//   workspace_id: "abc123",
//   external_id: "user-12345",
//   role: "user",
//   email: "jane@example.com",
//   name: "Jane Smith",
//   custom_attributes: { plan: "pro", signup_date: 1711100000 },
//   created_at: 1711100000,
//   updated_at: 1711100000,
//   ...
// }

Step 2: Search for Contacts

// Search contacts by email
const results = await client.contacts.search({
  query: {
    field: "email",
    operator: "=",
    value: "jane@example.com",
  },
});

console.log(`Found ${results.totalCount} contacts`);
for (const contact of results.data) {
  console.log(`  ${contact.name} - ${contact.email} (${contact.role})`);
}

Step 3: Send a Message

Messages are outbound communications from admins to contacts.

// Send an in-app message
const message = await client.messages.create({
  messageType: "inapp",
  body: "Welcome to our platform! Need help getting started?",
  from: {
    type: "admin",
    id: "12345", // Admin ID from client.admins.list()
  },
  to: {
    type: "user",
    id: user.id,
  },
});

console.log(`Sent message: ${message.id}`);

Step 4: Create a Conversation

Conversations are created when a contact replies or an admin initiates.

// Create a conversation (as a contact)
const conversation = await client.conversations.create({
  from: {
    type: "user",
    id: user.id,
  },
  body: "Hi, I have a question about billing.",
});

console.log(`Conversation created: ${conversation.conversationId}`);

Step 5: Tag a Contact

// Create a tag
const tag = await client.tags.create({ name: "vip-customer" });

// Tag a contact
await client.contacts.tag({
  contactId: user.id,
  id: tag.id,
});

console.log(`Tagged contact ${user.id} with "${tag.name}"`);

Core Data Model

| Entity | Description | Key Fields | |--------|-------------|------------| | Contact | Users and leads | id, role, email, external_id, custom_attributes | | Conversation | Threaded exchanges | id, state, contacts, conversation_parts | | Message | Outbound from admin | id, message_type, body, from, to | | Tag | Labels for entities | id, name, applied_to | | Company | Organization grouping | id, company_id, name, plan | | Admin | Workspace team member | id, name, email, type |

Complete Working Script

import { IntercomClient } from "intercom-client";

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

async function main() {
  // 1. Verify connection
  const me = await client.admins.list();
  const admin = me.admins[0];
  console.log(`Authenticated as: ${admin.name}`);

  // 2. Create or find a contact
  const contact = await client.contacts.create({
    role: "user",
    externalId: `hello-world-${Date.now()}`,
    email: `test-${Date.now()}@example.com`,
    name: "Hello World User",
  });
  console.log(`Contact: ${contact.id}`);

  // 3. List all contacts (paginated)
  const contacts = await client.contacts.list();
  console.log(`Total contacts in workspace: ${contacts.totalCount}`);

  // 4. List conversations
  const conversations = await client.conversations.list();
  console.log(`Total conversations: ${conversations.totalCount}`);
}

main().catch(console.error);

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | not_found (404) | Contact/conversation ID invalid | Verify the ID exists | | parameter_invalid | Missing required field | Check required params in docs | | conflict (409) | Duplicate external_id | Use unique identifiers | | unauthorized (401) | Invalid token | Regenerate access token |

Resources

Next Steps

Proceed to intercom-local-dev-loop for development workflow setup.

Agent Skills: Intercom Hello World

Install this agent skill to your local

Skill Files