Chatwoot Contact Operations

Creating Contacts

contacts_create(
  account_id: 1,
  name: "Jane Smith",
  email: "[email protected]",
  phone_number: "+15551234567",
  identifier: "CRM-12345",
  custom_attributes: {
    "plan": "enterprise",
    "company": "Acme Corp"
  }
)

Tips:

• email and phone_number are used for deduplication — Chatwoot may reject if a contact with the same email/phone exists
• identifier is useful for linking to external systems (CRM, billing, etc.)
• custom_attributes are freeform but should match defined attribute keys for consistency

Finding Contacts

Quick text search: contacts_search

Searches across name, email, phone, and identifier fields:

contacts_search(account_id: 1, q: "[email protected]")
contacts_search(account_id: 1, q: "Acme")
contacts_search(account_id: 1, q: "+1555")

Best for: Quick lookups when you have a partial name, email, or phone.

Structured filtering: contacts_filter

Complex queries with boolean logic and operators:

contacts_filter(
  account_id: 1,
  payload: [
    {
      "attribute_key": "email",
      "filter_operator": "contains",
      "values": ["@acme.com"],
      "query_operator": "AND"
    },
    {
      "attribute_key": "last_activity_at",
      "filter_operator": "days_before",
      "values": [90],
      "query_operator": null
    }
  ]
)

Best for: Finding contacts matching specific criteria (inactive contacts, contacts without email, contacts from a specific domain, etc.)

When to use which

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

Updating Contacts

contacts_update(
  account_id: 1,
  id: 42,
  name: "Jane Smith-Jones",
  custom_attributes: {
    "plan": "enterprise-plus",
    "renewal_date": "2026-06-15"
  }
)

Only pass the fields you want to change — other fields are preserved.

Contact Labels

Labels are string tags for categorizing contacts.

List labels

contact_labels_list(account_id: 1, contact_id: 42)
→ ["vip", "enterprise"]

Set labels (replaces all)

contact_labels_set(account_id: 1, contact_id: 42, labels: ["vip", "enterprise", "churning"])

⚠️ Replaces all labels — read first, merge, then set.

Merging Duplicate Contacts

When two contact records represent the same person:

contacts_merge(
  account_id: 1,
  base_contact_id: 42,
  mergee_contact_id: 87
)

• base_contact_id — The contact that survives (keeps its ID)
• mergee_contact_id — The contact that gets merged into the base (deleted)
• Conversations, messages, and attributes from the mergee are transferred to the base

Deduplication workflow

1. contacts_search(q: "[email protected]")
   → Returns contacts [42, 87] with same email

2. contacts_get(id: 42) → Check which has more data
   contacts_get(id: 87) → Compare

3. contacts_merge(base_contact_id: 42, mergee_contact_id: 87)
   → Contact 87's conversations now belong to contact 42

Contact-Inbox Relationships

List contactable inboxes

Find which inboxes a contact can be reached through:

contacts_contactable_inboxes(account_id: 1, id: 42)
→ [{ inbox: { id: 3, name: "Email" }, source_id: "[email protected]" }, ...]

Link contact to inbox

Create a contact-inbox association:

contacts_create_contact_inbox(
  account_id: 1,
  id: 42,
  inbox_id: 5
)

This is needed to create conversations for a contact on a specific inbox channel.

Contact's Conversations

Get all conversations for a specific contact:

contacts_conversations(account_id: 1, id: 42)
→ List of conversations with this contact

Useful for getting a customer's full history before responding.

Deleting Contacts

contacts_delete(account_id: 1, id: 42)

⚠️ Destructive: Permanently removes the contact and their data. Consider merging instead if it's a duplicate.

Common Patterns

See FILTER_GUIDE.md for advanced contact filtering examples.

See EXAMPLES.md for real-world scenario walkthroughs.