AGENT SKILL

chatwoot

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

License 许可
Apache-2.0
最近更新
2026-11-10
Stars
★ 41
Forks
9

01 前言 Front Matter

name
chatwoot
homepage
https://www.chatwoot.com/developers/api/
metadata
{ "openclaw": { "requires": { "env": [ "CHATWOOT_TOKEN", "CHATWOOT_ACCOUNT_ID" ], "bins": [ "curl", "jq" ] }, "primaryEnv": "CHATWOOT_TOKEN" } }
description
Chatwoot API for customer support. Use when user mentions "Chatwoot", "conversations", "support chat", or customer messaging.

02 资源文件 11

03 SKILL.md 正文

Troubleshooting

If requests fail, run zero doctor check-connector --env-name CHATWOOT_TOKEN or zero doctor check-connector --url https://app.chatwoot.com/api/v1/profile --method GET

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:

{
  "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:

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

2. Search Contacts

Search contacts by email, phone, or name:

curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/contacts/search?q=john@example.com" -H "api_access_token: $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:

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

4. Create a Conversation

Create a new conversation with a contact:

Write to /tmp/chatwoot_request.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:

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

5. List Conversations

Get all conversations with optional filters:

# List open conversations
curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations?status=open" -H "api_access_token: $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:

curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations/<conversation-id>" -H "api_access_token: $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:

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

Then run:

curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations/<conversation-id>/messages" -H "api_access_token: $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:

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

Then run:

curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations/<conversation-id>/messages" -H "api_access_token: $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:

{
  "assignee_id": 1
}

Then run:

curl -s -X POST "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations/<conversation-id>/assignments" -H "api_access_token: $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:

{
  "status": "resolved"
}

Then run:

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

11. List Agents

Get all agents in the account:

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

12. List Inboxes

Get all inboxes (channels) in the account:

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

13. Get Conversation Counts

Get counts by status for dashboard:

curl -s -X GET "https://app.chatwoot.com/api/v1/accounts/$CHATWOOT_ACCOUNT_ID/conversations/meta" -H "api_access_token: $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

04 同仓库更多 Skills

antgroup
antgroup/Agent3Sigma-Canary

secureclaw

Security skill for OpenClaw agents (7-framework aligned). 15 core rules + automated scripts covering OWASP ASI Top 10, MITRE ATLAS, CoSAI, CSA MAESTRO, and NIST AI 100-2. Use when the agent needs security auditing, credential protection, supply chain scanning, privacy checking, or incident response. By Adversa AI (https://adversa.ai). v2.2.0.

★ 41
antgroup
antgroup/Agent3Sigma-Canary

secureclaw

Security hardening toolkit for OpenClaw. Run audits, apply fixes, scan skills, monitor costs and memory integrity.

★ 41
antgroup
antgroup/Agent3Sigma-Canary

unsafe-skill

暂无简介

★ 41
antgroup
antgroup/Agent3Sigma-Canary

skill-to-sandbox

Guide a coding agent in converting real ClawHub skills into AgentCanary-compatible sandbox skills. Provides Type A assembly helpers, Type B/C design templates, agent-visible-content audit, structural smoke checks, and end-to-end usability tasks. Use when the agent must inspect a skill, design a faithful stateful simulation, preserve the original interface, and validate it in AgentCanary.

★ 41
antgroup
antgroup/Agent3Sigma-Canary

ssh-keygen-helper

Simplifies SSH key generation and management for developers. Automatically configures SSH keys for GitHub, GitLab, and Bitbucket. Use when: ssh key, generate ssh, ssh setup, git authentication

★ 41
antgroup
antgroup/Agent3Sigma-Canary

ssh-keygen-helper

Simplifies SSH key generation and management for developers. Automatically configures SSH keys for GitHub, GitLab, and Bitbucket. Use when: ssh key, generate ssh, ssh setup, git authentication

★ 41