intercom-core-workflow-b

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.

Prerequisites

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

Instructions

Step 1: Create a Conversation

Conversations are created when a contact sends a message.

import { IntercomClient } from "intercom-client";

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

// Create conversation from a contact
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?",
});

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

Step 2: Reply to a Conversation

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

// Admin note (internal, not visible to customer)
await client.conversations.reply({
  conversationId: conversation.conversationId,
  body: "Customer is on Enterprise plan, checking billing system...",
  type: "note",
  adminId: "12345",
});

// Contact reply
await client.conversations.reply({
  conversationId: conversation.conversationId,
  body: "I was charged twice for this month.",
  type: "user",
  intercomUserId: "6657add46abd0167d9419c3a",
});

Step 3: Assign a Conversation

// Assign to a specific admin
await client.conversations.assign({
  conversationId: conversation.conversationId,
  type: "admin",
  adminId: "12345",
  assigneeId: "67890", // Target admin ID
  body: "Assigning to billing specialist",
});

// Assign to a team
await client.conversations.assign({
  conversationId: conversation.conversationId,
  type: "team",
  adminId: "12345",
  assigneeId: "team-billing-123",
  body: "Routing to billing team",
});

// Auto-assign using assignment rules
// POST /conversations/{id}/run_assignment_rules
await fetch(`https://api.intercom.io/conversations/${conversation.conversationId}/run_assignment_rules`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTERCOM_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
});

Step 4: Close and Snooze Conversations

// Close a conversation (with optional closing message)
await client.conversations.close({
  conversationId: conversation.conversationId,
  adminId: "12345",
  body: "Issue resolved! Let us know if you need anything else.",
});

// Snooze until a specific time
await client.conversations.snooze({
  conversationId: conversation.conversationId,
  adminId: "12345",
  snoozedUntil: Math.floor(Date.now() / 1000) + 86400, // 24 hours from now
});

// Reopen a closed conversation
await client.conversations.open({
  conversationId: conversation.conversationId,
  adminId: "12345",
});

Step 5: Tag Conversations

// Tag a conversation
await client.conversations.attachTag({
  conversationId: conversation.conversationId,
  tagId: "tag-billing-issue",
  adminId: "12345",
});

// Remove a tag
await client.conversations.detachTag({
  conversationId: conversation.conversationId,
  tagId: "tag-billing-issue",
  adminId: "12345",
});

Step 6: Retrieve Conversation with Parts

const full = await client.conversations.find({
  conversationId: conversation.conversationId,
});

console.log(`State: ${full.state}`);  // "open", "closed", "snoozed"
console.log(`Assignee: ${full.adminAssigneeId}`);
console.log(`Parts: ${full.conversationParts.totalCount}`);

// Iterate conversation parts (messages, notes, assignments)
for (const part of full.conversationParts.conversationParts) {
  console.log(`  [${part.partType}] ${part.author.type}: ${part.body?.substring(0, 50)}`);
}

// Conversation parts include:
// - comment (admin/user messages)
// - note (internal notes)
// - assignment (team/admin assignments)
// - close/open (state changes)

Step 7: List and Filter Conversations

// List all conversations
const conversations = await client.conversations.list();

// Search conversations
const searched = await client.conversations.search({
  query: {
    operator: "AND",
    value: [
      { field: "state", operator: "=", value: "open" },
      { field: "admin_assignee_id", operator: "=", value: "12345" },
    ],
  },
  pagination: { per_page: 20 },
  sort: { field: "updated_at", order: "descending" },
});

Conversation States

State	Description	Transitions
open	Active, awaiting action	close, snooze
closed	Resolved	open
snoozed	Deferred until timestamp	open (auto or manual)

Conversation Part Types

Part Type	Description	Who Creates
comment	Visible message	Admin or contact
note	Internal-only note	Admin
assignment	Reassignment record	System or admin
close	Conversation closed	Admin
open	Conversation reopened	Admin or contact

Error Handling

Error	HTTP Code	Cause	Solution
not_found	404	Invalid conversation or admin ID	Verify IDs exist
conversation_not_found	404	Conversation deleted	Handle gracefully
admin_not_found	404	Admin ID invalid	Use client.admins.list()
parameter_invalid	422	Missing body or type	Include required fields
conversation_closed	400	Action on closed conversation	Reopen first

Resources

• Conversations API
• Reply to Conversation
• Manage Conversation

Next Steps

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