Chatwoot Mcp Tools Expert

Chatwoot MCP Tools Expert

You have access to the mcp-chatwoot MCP server which exposes 129 tools covering the full Chatwoot API. This skill teaches you how to use them effectively.

Critical: Every Tool Requires account_id

All mcp-chatwoot tools take account_id as their first required parameter. If you don't know it:

1. Call profile_get (the only tool that doesn't need account_id) to get the current user's profile
2. The response includes account_id in the user's available accounts
3. Use that account_id for all subsequent calls

Tool Categories at a Glance

| Category | Tools | Primary Use | | ------------------------- | -------- | ---------------------------------------------------------------------------------- | | Conversations | 12 tools | Core messaging — list, create, filter, status, priority, labels, custom attributes | | Messages | 3 tools | Send/list/delete messages within conversations | | Contacts | 11 tools | Customer data — CRUD, search, filter, merge, labels | | Agents | 4 tools | Manage support agents | | Teams | 9 tools | Teams + team member management | | Inboxes | 11 tools | Channel configuration + inbox members | | Automation Rules | 5 tools | Event-driven automation | | Canned Responses | 4 tools | Reusable message templates | | Custom Attributes | 5 tools | Define custom data fields | | Custom Filters | 5 tools | Saved filter presets | | Reports | 9 tools | Analytics — overview, agent, inbox, team, label metrics | | Help Center | 5 tools | Knowledge base — portals, categories, articles | | Agent Bots | 5 tools | Bot configuration | | Webhooks | 4 tools | External integrations | | Integrations | 4 tools | App hooks | | Account | 2 tools | Account info | | Audit Logs | 1 tool | Activity audit trail | | Profile | 1 tool | Current user profile | | ⚡ Kanban | 24 tools | Boards, steps, tasks, audit events, preferences (fazer.ai exclusive) | | ⚡ Scheduled Messages | 4 tools | Time-delayed messages (fazer.ai exclusive) |

Tool Naming Convention

Tools follow a consistent _ pattern:

conversations_list          → List conversations (paginated)
conversations_get           → Get single conversation by ID
conversations_create        → Create new conversation
conversations_update        → Update conversation
conversations_filter        → Advanced filtering with query syntax
conversations_toggle_status → Change status (open/resolved/pending/snoozed)

How to Choose the Right Tool

Finding resources

| Need | Tool | When to use | | ---------------- | --------------------- | -------------------------------------------- | | Browse all | *_list | Paginated listing, broad overview | | Find by ID | *_get | You already have the resource ID | | Text search | contacts_search | Free-text search across contact fields | | Structured query | *_filter | Complex conditions (AND/OR, operators) | | Saved queries | custom_filters_list | Reuse previously saved filter configurations |

Search vs Filter

This is the most common source of confusion:

• contacts_search — Simple text search. Pass a q string parameter. Searches across name, email, phone, identifier.
• contacts_filter — Structured query with operators. Supports equal_to, not_equal_to, contains, does_not_contain, is_present, is_not_present. Combine with AND/OR logic.
• conversations_filter — Same structured query system for conversations. Filter by status, assignee, team, label, inbox, custom attributes, etc.

Rule of thumb: Use _search for quick lookups by text. Use _filter for precise, multi-condition queries.

Modifying resources

| Action | Pattern | Example | | --------------- | ------------- | ------------------------------------------------------------------------------------------------- | | Create | *_create | contacts_create, teams_create | | Update | *_update | contacts_update, conversations_update | | Delete | *_delete | messages_delete, webhooks_delete | | Special actions | Named actions | conversations_toggle_status, conversations_toggle_priority, conversation_assignments_assign |

Response Format

All tools return JSON text in this structure:

{
  "content": [
    {
      "type": "text",
      "text": "{ ... JSON response ... }"
    }
  ]
}

The inner text field contains the actual Chatwoot API response as a JSON string. Parse it to extract data.

Pagination

List endpoints are paginated. Common parameters:

• page — Page number (1-indexed)
• Most endpoints return 15-25 items per page by default

To get all results, loop through pages until you receive fewer items than the page size.

MCP Tool Annotations

Tools include safety annotations:

• readOnlyHint: true — Safe to call, doesn't modify data (list, get, search, filter)
• destructiveHint: true — Deletes data permanently (all *_delete tools)
• idempotentHint: true — Safe to retry (updates with same data produce same result)

Always prefer read-only tools first to gather context before making changes.

Common Workflow Patterns

1. Discover → Act pattern

1. profile_get                           → Get account_id
2. conversations_list / _filter          → Find relevant conversations
3. conversations_get                     → Get full details
4. messages_list                         → Read message history
5. messages_create / conversations_update → Take action

2. Bulk operations pattern

1. conversations_filter  → Get matching conversations
2. Loop through results:
   - conversations_toggle_status / _set_labels / conversation_assignments_assign
3. Paginate if needed (check result count vs page size)

3. Setup pattern

1. teams_create              → Create team
2. agents_list               → Find agent IDs
3. team_members_add          → Add agents to team
4. inboxes_create            → Create inbox
5. inbox_members_create      → Assign agents to inbox
6. automation_rules_create   → Set up routing rules

Common Mistakes

❌ Forgetting account_id

Every tool except profile_get requires it. Always resolve it first.

❌ Using wrong ID types

• conversation_id is the display_id (integer shown in UI), NOT the internal UUID
• contact_id, inbox_id, team_id, agent_id are all integers

❌ Confusing filter query syntax

Filter tools accept a payload object with attribute_key, filter_operator, values, and query_operator. See the conversation-management and contact-operations skills for detailed syntax.

❌ Sending messages with wrong type

messages_create requires message_type: "outgoing" (from agent), "incoming" (from contact), or "activity" (system note). Most of the time you want "outgoing".

❌ Not checking conversation status before acting

A resolved conversation may need to be reopened (conversations_toggle_status with status: "open") before sending new messages.

Tool Quick Reference

See TOOL_REFERENCE.md for the complete list of all 129 tools grouped by category with parameters.

See COMMON_MISTAKES.md for detailed error scenarios and fixes.

See SEARCH_GUIDE.md for in-depth coverage of search and filter query syntax.

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.