Intercom Conversations & Messaging

Overview

Manage the full conversation lifecycle: create, reply (as admin or contact), assign to teams, close, snooze, and tag. Conversations contain threaded "parts" including messages, notes, and assignments.

This SKILL.md gives you the high-level workflow and the essential skeleton. The complete step-by-step code for all seven operations lives in references/implementation.md; realistic end-to-end scenarios are in references/examples.md.

Prerequisites

• Completed intercom-install-auth setup (provides the INTERCOMACCESSTOKEN)
• Admin ID (from client.admins.list())
• Contact IDs for conversation participants

Authentication

All calls authenticate with a bearer access token supplied to the SDK client — see intercom-install-auth for how to obtain and store it. Read it from the environment, never hard-code it:

import { IntercomClient } from "intercom-client";

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

The raw runassignmentrules endpoint (Step 3) uses the same token as an Authorization: Bearer header.

Instructions

The workflow is seven operations against client.conversations.*. Reach for the one you need — they are independent once you have a conversation ID.

1. Create — conversations.create({ from, body }) opens a conversation from a contact and returns its conversationId.
2. Reply — conversations.reply(...) adds a part. type: "admin" is customer-visible, type: "note" is internal-only, type: "user" is a contact reply.
3. Assign — conversations.assign(...) routes to an admin (type: "admin") or team (type: "team"); or POST runassignmentrules for auto-routing.
4. Close / snooze / reopen — conversations.close(...), conversations.snooze({ snoozedUntil }) (Unix seconds), and conversations.open(...).
5. Tag — conversations.attachTag(...) / detachTag(...).
6. Retrieve — conversations.find(...) returns state, assignee, and the conversationParts thread.
7. List / search — conversations.list() or conversations.search({ query, pagination, sort }) with AND/OR field filters.

Essential skeleton (create then reply); see references/implementation.md for every step in full:

const conversation = await client.conversations.create({
  from: { type: "user", id: "6657add46abd0167d9419c3a" }, // Contact ID
  body: "Hi, I'm having trouble with my billing. Can you help?",
});

await client.conversations.reply({
  conversationId: conversation.conversationId,
  body: "Hi there! I'd be happy to help. What's the issue?",
  type: "admin",
  adminId: "12345",
});

Output

Each operation returns the affected conversation (or acknowledges the mutation):

• create → a conversation object exposing conversationId (use it for every follow-up call).
• reply / assign / close / snooze / open → the updated conversation with its new state and appended part.
• find → the full conversation: state ("open" | "closed" | "snoozed"), adminAssigneeId, and conversationParts (totalCount + the ordered thread of comment / note / assignment / close / open parts).
• search / list → a paginated collection of matching conversations, ordered by your sort clause.

Conversation States

Conversation Part Types

Error Handling

For common errors and debugging, see intercom-common-errors.

Examples

Three end-to-end scenarios are worked in full in references/examples.md:

1. Handle a billing complaint end-to-end — create → reply → assign to team → close.
2. Tag, snooze, and follow up — attach a tag, leave an internal note, snooze 24h, reopen.
3. Audit an open queue — search open conversations for an admin, then inspect a thread's parts.

The billing flow, in brief:

const conversation = await client.conversations.create({
  from: { type: "user", id: "6657add46abd0167d9419c3a" },
  body: "Hi, I'm having trouble with my billing. Can you help?",
});
await client.conversations.assign({
  conversationId: conversation.conversationId,
  type: "team",
  adminId: "12345",
  assigneeId: "team-billing-123",
  body: "Routing to billing team",
});
await client.conversations.close({
  conversationId: conversation.conversationId,
  adminId: "12345",
  body: "Issue resolved! Let us know if you need anything else.",
});

Resources

• references/implementation.md — full seven-step walkthrough with every code block
• references/examples.md — three end-to-end worked scenarios
• Conversations API
• Reply to Conversation
• Manage Conversation