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 <resource>_<action> 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.