Agent skill

chatwoot

Chatwoot API for customer support. Use when user mentions "Chatwoot", "conversations", "support chat", or customer messaging.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/chatwoot

SKILL.md

Chatwoot

Use Chatwoot via direct curl calls to manage customer support across multiple channels (website, email, WhatsApp, etc.).

Official docs: https://developers.chatwoot.com/api-reference/introduction

When to Use

Use this skill when you need to:

  • Manage contacts - create, search, and update customer profiles
  • Handle conversations - create, assign, and track support conversations
  • Send messages - reply to customers or add internal notes
  • List agents - get support team information
  • Automate workflows - integrate with CRM, ticketing, or notification systems

Prerequisites

  1. Set up Chatwoot (Cloud or Self-hosted)
  2. Log in and go to Profile Settings to get your API access token
  3. Note your Account ID from the URL (e.g., /app/accounts/1/...)
bash
export CHATWOOT_TOKEN="your-api-access-token"
export CHATWOOT_ACCOUNT_ID="1"

API Types

API Type Auth Use Case
Application API User access_token Agent/admin automation
Client API inbox_identifier Custom chat interfaces
Platform API Platform App token Multi-tenant management (self-hosted only)

How to Use

All examples use the Application API with user access token.

1. Create a Contact

Create a new contact in your account:

Write to /tmp/chatwoot_request.json:

json
{
  "inbox_id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone_number": "+1234567890",
  "identifier": "customer_123",
  "additional_attributes": {
    "company": "Acme Inc",
    "plan": "premium"
  }
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

2. Search Contacts

Search contacts by email, phone, or name:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts/search?q=john@example.com" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" | jq '.payload[] | {id, name, email}'

3. Get Contact Details

Get a specific contact by ID. Replace <contact-id> with the actual contact ID from the "Search Contacts" or "Create a Contact" response:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/contacts/<contact-id>" -H "api_access_token: $(printenv CHATWOOT_TOKEN)"

4. Create a Conversation

Create a new conversation with a contact:

Write to /tmp/chatwoot_request.json:

json
{
  "source_id": "api_conversation_123",
  "inbox_id": 1,
  "contact_id": 123,
  "status": "open",
  "message": {
    "content": "Hello! How can I help you today?"
  }
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

5. List Conversations

Get all conversations with optional filters:

bash
# List open conversations
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations?status=open" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" | jq '.data.payload[] | {id, status, contact: .meta.sender.name}'

6. Get Conversation Details

Get details of a specific conversation. Replace <conversation-id> with the actual conversation ID from the "List Conversations" or "Create a Conversation" response:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>" -H "api_access_token: $(printenv CHATWOOT_TOKEN)"

7. Send a Message

Send a message in a conversation. Replace <conversation-id> with the actual conversation ID from the "List Conversations" response:

Write to /tmp/chatwoot_request.json:

json
{
  "content": "Thank you for contacting us! Let me help you with that.",
  "message_type": "outgoing",
  "private": false
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

8. Add Private Note

Add an internal note (not visible to customer). Replace <conversation-id> with the actual conversation ID from the "List Conversations" response:

Write to /tmp/chatwoot_request.json:

json
{
  "content": "Customer is a VIP - handle with priority",
  "message_type": "outgoing",
  "private": true
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/messages" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

9. Assign Conversation

Assign a conversation to an agent. Replace <conversation-id> with the actual conversation ID and <agent-id> with the agent ID from the "List Agents" response:

Write to /tmp/chatwoot_request.json:

json
{
  "assignee_id": 1
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/assignments" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

10. Update Conversation Status

Change conversation status (open, resolved, pending). Replace <conversation-id> with the actual conversation ID from the "List Conversations" response:

Write to /tmp/chatwoot_request.json:

json
{
  "status": "resolved"
}

Then run:

bash
curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/<conversation-id>/toggle_status" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" -H "Content-Type: application/json" -d @/tmp/chatwoot_request.json

11. List Agents

Get all agents in the account:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/agents" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" | jq '.[] | {id, name, email, role, availability_status}'

12. List Inboxes

Get all inboxes (channels) in the account:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/inboxes" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" | jq '.payload[] | {id, name, channel_type}'

13. Get Conversation Counts

Get counts by status for dashboard:

bash
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$(printenv CHATWOOT_ACCOUNT_ID)/conversations/meta" -H "api_access_token: $(printenv CHATWOOT_TOKEN)" | jq '.meta.all_count, .meta.mine_count'

Conversation Status

Status Description
open Active conversation
resolved Closed/completed
pending Waiting for response
snoozed Temporarily paused

Message Types

Type Value Description
Outgoing outgoing Agent to customer
Incoming incoming Customer to agent
Private private: true Internal note (not visible to customer)

Response Fields

Contact

Field Description
id Contact ID
name Contact name
email Email address
phone_number Phone number
identifier External system ID
custom_attributes Custom fields

Conversation

Field Description
id Conversation ID
inbox_id Channel/inbox ID
status Current status
assignee Assigned agent
contact Customer info

Message

Field Description
id Message ID
content Message text
message_type incoming/outgoing
private Is internal note
status sent/delivered/read/failed

Guidelines

  1. Get API token from Profile Settings: Log into Chatwoot → Profile → Access Token
  2. Account ID is in URL: Look at /app/accounts/{id}/... in your browser
  3. Inbox ID is required: Get inbox IDs first with the list inboxes endpoint
  4. Use source_id for conversations: Required to create conversations via API
  5. Private messages: Set private: true for internal notes
  6. Cloud only: This skill uses the Chatwoot Cloud API at https://app.chatwoot.com
  7. Webhooks recommended: Use webhooks for real-time updates instead of polling

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vm0-ai/vm0-skills

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

50 8
Explore
vm0-ai/vm0-skills

supadata

Supadata API for YouTube/web data. Use when user mentions "Supadata", "YouTube data", "channel stats", or web scraping data.

50 8
Explore
vm0-ai/vm0-skills

roadmap-planning

Build and prioritize product roadmaps using scoring models like RICE, ICE, and value-effort matrices. Activate when creating a product roadmap, prioritizing features, sequencing initiatives, mapping dependencies, balancing team capacity, choosing between Now/Next/Later or quarterly planning, or communicating roadmap tradeoffs to executives and stakeholders.

50 8
Explore
vm0-ai/vm0-skills

qdrant

Qdrant API for vector search. Use when user mentions "Qdrant", "vector database", "semantic search", or embeddings storage.

50 8
Explore
vm0-ai/vm0-skills

calendly

Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.

50 8
Explore
vm0-ai/vm0-skills

stripe

Stripe API for payments. Use when user mentions "Stripe", "payment", "subscription", "billing", "invoice", or asks about payment processing.

50 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results