Chatwoot Conversation Management

Chatwoot Conversation Management

Master guide for managing conversations end-to-end using mcp-chatwoot MCP tools.

Conversation Lifecycle

Conversations flow through these statuses:

             ┌──────────┐
    New ────►│   OPEN   │◄──── Reopen
             └────┬─────┘
                  │
         ┌───────┼───────┐
         ▼       ▼       ▼
    ┌─────────┐ ┌──────┐ ┌─────────┐
    │ PENDING │ │SNOOZED│ │RESOLVED │
    └─────────┘ └──────┘ └─────────┘
         │       │              │
         └───────┴──────────────┘
                  │
             Back to OPEN

Status meanings

| Status | Meaning | Typical use | | ---------- | ----------------------- | -------------------------------------- | | open | Active, needs attention | New or reopened conversations | | pending | Waiting on customer | Agent asked a question, awaiting reply | | snoozed | Temporarily hidden | Will resurface at a set time | | resolved | Complete, closed | Issue resolved |

Changing status

conversations_toggle_status(
  account_id: 1,
  conversation_id: 42,
  status: "resolved"
)

Valid values: "open", "resolved", "pending", "snoozed"

Priority Levels

| Priority | When to use | | -------- | ------------------------- | | none | Default, no urgency | | low | Can wait | | medium | Normal priority | | high | Needs attention soon | | urgent | Immediate action required |

conversations_toggle_priority(
  account_id: 1,
  conversation_id: 42,
  priority: "high"
)

Creating Conversations

conversations_create(
  account_id: 1,
  contact_id: 100,
  inbox_id: 5,
  message: {
    content: "Hello, how can I help you?"
  },
  status: "open"
)

Required: contact_id + inbox_id (or source_id for channel-specific creation).

Messages

Sending a message

messages_create(
  account_id: 1,
  conversation_id: 42,
  content: "Thanks for reaching out! Let me look into this.",
  message_type: "outgoing",
  private: false
)

Message types

| Type | Direction | Use case | | ---------- | ---------------- | -------------------------------------------- | | outgoing | Agent → Customer | Standard reply | | incoming | Customer → Agent | Simulate customer message (testing, imports) | | activity | System | Internal activity note |

Private notes

Set private: true to create an internal note visible only to agents:

messages_create(
  account_id: 1,
  conversation_id: 42,
  content: "Customer seems upset, escalating to senior agent.",
  message_type: "outgoing",
  private: true
)

Reading message history

messages_list(
  account_id: 1,
  conversation_id: 42
)

Assignments

Assign to agent

conversation_assignments_assign(
  account_id: 1,
  conversation_id: 42,
  assignee_id: 7
)

Assign to team

conversation_assignments_assign(
  account_id: 1,
  conversation_id: 42,
  team_id: 3
)

Unassign

Set assignee_id: 0 to remove the agent assignment.

Labels

Labels are string tags applied to conversations for categorization.

Get current labels

conversations_get_labels(account_id: 1, conversation_id: 42)
→ ["bug", "urgent"]

Set labels (replaces all)

conversations_set_labels(
  account_id: 1,
  conversation_id: 42,
  labels: ["bug", "urgent", "reviewed"]
)

⚠️ Important: This REPLACES all labels. To add a label, read first, merge, then set.

Add-label pattern

1. conversations_get_labels → ["bug", "urgent"]
2. Append new label → ["bug", "urgent", "reviewed"]
3. conversations_set_labels(labels: ["bug", "urgent", "reviewed"])

Custom Attributes

Set arbitrary key-value data on conversations:

conversations_set_custom_attributes(
  account_id: 1,
  conversation_id: 42,
  custom_attributes: {
    "product": "Enterprise Plan",
    "ticket_ref": "JIRA-1234",
    "sentiment": "negative"
  }
)

Custom attribute definitions must exist first (see admin-configuration skill).

Filtering Conversations

Basic listing by status

conversations_list(
  account_id: 1,
  status: "open",
  assignee_type: "unassigned",
  page: 1
)

Advanced filtering

conversations_filter(
  account_id: 1,
  payload: [
    {
      "attribute_key": "status",
      "filter_operator": "equal_to",
      "values": ["open"],
      "query_operator": "AND"
    },
    {
      "attribute_key": "priority",
      "filter_operator": "equal_to",
      "values": ["high", "urgent"],
      "query_operator": "AND"
    },
    {
      "attribute_key": "team_id",
      "filter_operator": "equal_to",
      "values": [3],
      "query_operator": null
    }
  ]
)

See the mcp-tools-expert skill's SEARCH_GUIDE.md for full filter syntax reference.

Get conversation counts

conversations_meta(account_id: 1)
→ { open: 45, resolved: 1230, pending: 12, snoozed: 3, ... }

Common Workflow Patterns

See WORKFLOW_PATTERNS.md for detailed patterns including triage, escalation, and bulk operations.

See EXAMPLES.md for real-world scenario walkthroughs.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fazer-ai
• Source: fazer-ai/chatwoot-skills
• License: MIT

Install and usage instructions live in the source repository linked above.