🔌 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

Application API (Recommended)

Used for automations and integrations: 1. Get Access Token:

Login to Chatwoot
Go to Profile Settings
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

Manage customer profiles
Import/Export
Custom attributes
Full Documentation

Funnels (Custom)

Manage funnels and stages
Move conversations
Checklists and timers
Full Documentation

💡 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

📖 User Guide

🔌 API Reference

⭐ Exclusive Features

API Reference - Chatwoot

🔌 API Reference - Overview

🎯 Types of APIs

Application APIs

Client APIs

Platform APIs

🔐 Authentication

Application API (Recommended)

🌐 Base URL

📊 Response Structure

Success (2xx)

Error (4xx/5xx)

🚀 Quick Start

1. Get Your Access Token

2. Test Connection

3. List Conversations

📚 Available Endpoints

Conversations

Contacts

Funnels (Custom)

💡 Best Practices

Security

Performance

🔗 SDKs and Libraries

Official

Community

📖 Next Steps

Conversations API

Contacts API

​🔌 API Reference - Overview

​🎯 Types of APIs

Application APIs

Client APIs

Platform APIs

​🔐 Authentication

​Application API (Recommended)

​🌐 Base URL

​📊 Response Structure

​Success (2xx)

​Error (4xx/5xx)

​🚀 Quick Start

​1. Get Your Access Token

​2. Test Connection

​3. List Conversations

​📚 Available Endpoints

​Conversations

​Contacts

​Funnels (Custom)

​💡 Best Practices

​Security

​Performance

​🔗 SDKs and Libraries

​Official

​Community

​📖 Next Steps

Conversations API

Contacts API

🔌 API Reference - Overview

🎯 Types of APIs

🔐 Authentication

Application API (Recommended)

🌐 Base URL

📊 Response Structure

Success (2xx)

Error (4xx/5xx)

🚀 Quick Start

1. Get Your Access Token

2. Test Connection

3. List Conversations

📚 Available Endpoints

Conversations

Contacts

Funnels (Custom)

💡 Best Practices

Security

Performance

🔗 SDKs and Libraries

Official

Community

📖 Next Steps