Skip to main content

​
Introduction

The Chatwoot API is a RESTful JSON API that allows you to programmatically interact with your Chatwoot account. Use it to build integrations, automate workflows, and extend Chatwoot’s functionality.

​
Base URL

All API requests should be made to: 
https://app.chatwoot.com/api/v1
For self-hosted installations, replace app.chatwoot.com with your installation URL: 
https://your-domain.com/api/v1

​
API Versioning

The Chatwoot API uses versioning to ensure backward compatibility. The current stable version is v1.
  • v1: Current stable version (recommended)
  • v2: Available for specific endpoints (reports, accounts)
Version is specified in the URL path:
  • v1 endpoints: /api/v1/*
  • v2 endpoints: /api/v2/*

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

​
Success Response

{
  "id": 1,
  "name": "John Doe",
  "email": "[email protected]"
}

​
Error Response

{
  "error": "Error message description",
  "message": "Detailed error information"
}

​
HTTP Status Codes

CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid parameters
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not Found - Resource not found
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error

​
Rate Limiting

API requests are rate-limited to ensure system stability. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
Rate limits vary by endpoint and account type. Contact support for specific rate limit information.

​
Pagination

List endpoints return paginated results. Use the page parameter to navigate through pages.
​
page
integer
default:"1"
Page number for pagination
Default page size is 15 items for most endpoints. 
GET /api/v1/accounts/{account_id}/contacts?page=2

​
Date Format

All timestamps are returned in Unix timestamp format (seconds since epoch) or ISO 8601 format.

​
Getting Started

  1. Create an Account: Sign up at app.chatwoot.com
  2. Generate Access Token: Navigate to Profile Settings → Access Token
  3. Authenticate: Include the token in your API requests
  4. Make Your First Request: Try the accounts endpoint
curl -X GET https://app.chatwoot.com/api/v1/accounts/{account_id} \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

​
API Resources

The Chatwoot API provides access to the following resources:

​
Need Help?

If you need assistance with the API:

Build docs developers (and LLMs) love

Get started for freeTalk to us