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
- 参考文档_meta.json584 B
- 参考文档agent_eval/README.md364 B
- 参考文档agent_eval/task_chatwoot_external_state.md1.5 KB
- 参考文档agent_eval/task_chatwoot_usability.md6.2 KB
- 脚本env_audit/check_environment.sh2.0 KB
- 脚本env_audit/fix_environment.sh2.3 KB
- 参考文档mock_assets/api_handlers/app_chatwoot_com.json8.5 KB
- 其他mock_assets/bin/chatwoot-state3.0 KB
- 脚本mock_assets/skill_hooks/00_prepare_chatwoot.sh1.7 KB
- 参考文档MOCK_SKILL_USAGE.md2.6 KB
- 脚本scripts/noop.sh111 B
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
- Get API token from Profile Settings: Log into Chatwoot → Profile → Access Token
- Account ID is in URL: Look at
/app/accounts/{id}/...in your browser - Inbox ID is required: Get inbox IDs first with the list inboxes endpoint
- Use source_id for conversations: Required to create conversations via API
- Private messages: Set
private: truefor internal notes - Cloud only: This skill uses the Chatwoot Cloud API at
https://app.chatwoot.com - Webhooks recommended: Use webhooks for real-time updates instead of polling
04 同仓库更多 Skills
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.
secureclaw
Security hardening toolkit for OpenClaw. Run audits, apply fixes, scan skills, monitor costs and memory integrity.
unsafe-skill
暂无简介
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.
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
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