Skip to main content

​
🔌 API Reference - Overview

Complete REST API documentation for Chatwoot. This API allows full integration with the platform for automation, custom integrations and application development.

​
🎯 Types of APIs

Chatwoot offers 3 types of APIs for different use cases:

Application APIs

For: Automation and management
Authentication: User Access Token
Use: Manage conversations, contacts, agents

Client APIs

For: Custom chat widget
Authentication: Inbox Token
Use: Integrate chat in apps/sites

Platform APIs

For: Multi-tenancy
Authentication: Platform App Token
Use: Manage multiple accounts

​
🔐 Authentication

Used for automations and integrations: 1. Get Access Token:
  1. Login to Chatwoot
  2. Go to Profile Settings
  3. Copy Access Token
2. Use in Requests: 
curl -X GET https://chat.yourdomain.com/api/v1/accounts/1/conversations \
  -H "api_access_token: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"
Required Headers: 
api_access_token: YOUR_ACCESS_TOKEN
Content-Type: application/json

​
🌐 Base URL

All requests use your installation’s base URL: 
https://chat.yourdomain.com/api/v1
Complete example: 
https://chat.yourdomain.com/api/v1/accounts/1/conversations

​
📊 Response Structure

​
Success (2xx)

{
  "id": 123,
  "status": "open",
  "messages": [...]
}

​
Error (4xx/5xx)

{
  "error": "Unauthorized",
  "message": "Invalid access token"
}

​
🚀 Quick Start

​
1. Get Your Access Token

# Login → Profile Settings → Copy Access Token

​
2. Test Connection

curl -X GET https://chat.yourdomain.com/api/v1/accounts \
  -H "api_access_token: YOUR_TOKEN"

​
3. List Conversations

curl -X GET https://chat.yourdomain.com/api/v1/accounts/1/conversations \
  -H "api_access_token: YOUR_TOKEN"

​
📚 Available Endpoints

​
Conversations

  • List, create, update conversations
  • Send messages
  • Manage status and assignments
  • Full Documentation

​
Contacts

​
Funnels (Custom)

​
💡 Best Practices

​
Security

✅ Never expose tokens: Don’t commit to Git
✅ Use environment variables: Store tokens securely
✅ Rotate periodically: Regenerate tokens regularly
✅ HTTPS only: Always use secure connection

​
Performance

✅ Pagination: Use for large lists
✅ Filters: Reduce unnecessary data
✅ Webhooks: Better than polling
✅ Rate limits: Respect API limits

​
🔗 SDKs and Libraries

​
Official

  • JavaScript/Node.js: Coming soon
  • Python: Coming soon
  • PHP: Coming soon

​
Community

Check GitHub for community contributions!

​
📖 Next Steps

Conversations API

Manage interactions programmatically

Contacts API

Manage customer database