Chatwoot Automation Patterns

Chatwoot Automation Patterns

Guide for building automated workflows using Chatwoot's automation tools.

Automation Building Blocks

| Tool | Purpose | When to use | | --------------------- | ---------------------------- | ---------------------------------------- | | Automation Rules | Event → conditions → actions | Simple routing, labeling, status changes | | Agent Bots | Programmable bot per inbox | Custom bot logic, API-driven responses | | Webhooks | Notify external services | Integrate with 3rd party systems | | Integration Hooks | App-level integrations | Connect Chatwoot apps |

Pattern 1: Auto-Assignment

Round-robin by team

Automatically distribute new conversations across team members:

automation_rules_create(
  account_id: 1,
  name: "Round-robin assignment",
  description: "Distribute new conversations to team members equally",
  event_name: "conversation_created",
  conditions: [
    { "attribute_key": "inbox_id", "filter_operator": "equal_to", "values": [5], "query_operator": null }
  ],
  actions: [
    { "action_name": "assign_team", "action_params": [3] }
  ]
)

When a team is assigned, Chatwoot's internal round-robin distributes to team members.

Direct agent assignment

For specific routing (e.g., VIP customers to senior agent):

automation_rules_create(
  account_id: 1,
  name: "VIP direct assignment",
  event_name: "conversation_created",
  conditions: [
    { "attribute_key": "email", "filter_operator": "contains", "values": ["@vip-client.com"], "query_operator": null }
  ],
  actions: [
    { "action_name": "assign_agent", "action_params": [7] },
    { "action_name": "change_priority", "action_params": ["high"] },
    { "action_name": "add_label", "action_params": ["vip"] }
  ]
)

Pattern 2: SLA-Based Escalation

Programmatic escalation

Since automation rules can't time-trigger, use Claude + MCP tools for periodic checks:

Step 1: Find overdue conversations
  conversations_filter(account_id: 1, payload: [
    { attribute_key: "status", filter_operator: "equal_to", values: ["open"], query_operator: "AND" },
    { attribute_key: "created_at", filter_operator: "days_before", values: [1], query_operator: null }
  ])

Step 2: Check first response
  For each: messages_list(account_id: 1, conversation_id: )
  If no outgoing message → SLA breached

Step 3: Escalate
  conversations_toggle_priority(account_id: 1, conversation_id: , priority: "urgent")
  conversation_assignments_assign(account_id: 1, conversation_id: , team_id: )
  messages_create(account_id: 1, conversation_id: ,
    content: "⚠️ SLA Alert: No first response within 24 hours",
    message_type: "outgoing", private: true)

Pattern 3: Channel Routing

Route conversations based on their source inbox:

# Chat → immediate response team
automation_rules_create(name: "Route chat",
  event_name: "conversation_created",
  conditions: [{ attribute_key: "inbox_id", filter_operator: "equal_to", values: [] }],
  actions: [{ action_name: "assign_team", action_params: [] }])

# Email → async team
automation_rules_create(name: "Route email",
  event_name: "conversation_created",
  conditions: [{ attribute_key: "inbox_id", filter_operator: "equal_to", values: [] }],
  actions: [{ action_name: "assign_team", action_params: [] }])

Pattern 4: Bot-to-Human Handoff

Setting up the bot

1. Create the bot
   agent_bots_create(account_id: 1,
     name: "Welcome Bot",
     description: "Greets customers and collects initial info",
     outgoing_url: "https://your-app.com/bot-webhook")
   → agent_bot_id: 2

2. Attach to inbox
   inboxes_set_agent_bot(account_id: 1, id: 5, agent_bot_id: 2)

Handoff flow

The bot's webhook endpoint should:

1. Handle incoming messages
2. Collect required information
3. When ready for handoff: update conversation to remove bot assignment

On the Chatwoot side, create a rule for handoff:

automation_rules_create(name: "Bot handoff",
  event_name: "conversation_updated",
  conditions: [
    { attribute_key: "status", filter_operator: "equal_to", values: ["open"], query_operator: "AND" },
    { attribute_key: "inbox_id", filter_operator: "equal_to", values: [5], query_operator: null }
  ],
  actions: [
    { action_name: "assign_team", action_params: [] }
  ])

Detach bot from inbox

inboxes_set_agent_bot(account_id: 1, id: 5, agent_bot_id: null)

Pattern 5: Webhook-Driven Integration

External notification system

1. Create webhook
   webhooks_create(account_id: 1,
     url: "https://your-app.com/chatwoot-events",
     subscriptions: [
       "conversation_created",
       "conversation_status_changed",
       "message_created"
     ])

2. Your endpoint receives POST requests with event data:
   {
     "event": "conversation_created",
     "data": { "id": 42, "inbox_id": 5, "contact": {...}, ... }
   }

Common integrations via webhooks

| Integration | Webhook events | Action at endpoint | | ------------------- | ----------------------------------------- | ---------------------------- | | Slack notifications | conversation_created, message_created | Post to Slack channel | | CRM sync | contact_created, contact_updated | Update CRM records | | Issue tracker | conversation_created + label filter | Create ticket in Jira/Linear | | Analytics | All events | Log to analytics platform | | SLA monitoring | conversation_created | Start SLA timer |

Pattern 6: Content-Based Categorization

Auto-label conversations based on message content:

automation_rules_create(name: "Detect billing issues",
  event_name: "message_created",
  conditions: [
    { attribute_key: "content", filter_operator: "contains",
      values: ["billing", "invoice", "charge", "refund", "payment"], query_operator: null }
  ],
  actions: [
    { action_name: "add_label", action_params: ["billing"] },
    { action_name: "assign_team", action_params: [] }
  ])

automation_rules_create(name: "Detect technical issues",
  event_name: "message_created",
  conditions: [
    { attribute_key: "content", filter_operator: "contains",
      values: ["bug", "error", "crash", "broken", "not working"], query_operator: null }
  ],
  actions: [
    { action_name: "add_label", action_params: ["technical"] },
    { action_name: "change_priority", action_params: ["high"] }
  ])

See AGENT_BOTS.md for detailed bot setup guide.

See WEBHOOK_PAYLOADS.md for complete webhook payload structures with real examples for all event types.

See INTEGRATION_PATTERNS.md for integration hooks and integration recipes.

See EXAMPLES.md for end-to-end automation scenarios.

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.