Chatwoot SDK for Python

A modern, type-safe Python SDK for the Chatwoot API. This SDK provides both synchronous and asynchronous interfaces to interact with Chatwoot's REST API, with full type hints for better IDE support and code safety.

Features

• 🔒 Type-safe: Full type hints with Pydantic models
• ⚡ Async support: Both sync and async clients available
• 🎯 Comprehensive: Covers all major Chatwoot API resources
• 🛡️ Error handling: Custom exceptions for different error types

Installation

pip install chatwoot-sdk
# or
uv add chatwoot-sdk

Note: The PyPI package name is chatwoot-sdk. The GitHub repository is named chatwoot-sdk-python.

Quick Start

from chatwoot import ChatwootClient

# Initialize the client
client = ChatwootClient(
    base_url="https://app.chatwoot.com",
    api_token="your_api_token_here"
)

# Fetch your profile
profile = client.profile.get()
print(f"Logged in as: {profile.name}")

# List open conversations
conversations = client.conversations.list(
    account_id=1,
    status="open"
)

# Send a message
message = client.messages.create(
    account_id=1,
    conversation_id=42,
    content="Hello from Python SDK!"
)

# Always close the client when done
client.close()

Usage Examples

Using Context Manager

from chatwoot import ChatwootClient

with ChatwootClient(base_url="...", api_token="...") as client:
    profile = client.profile.get()
    conversations = client.conversations.list(account_id=1, status="open")
    # Client is automatically closed

Async Usage

import asyncio
from chatwoot import AsyncChatwootClient

async def main():
    async with AsyncChatwootClient(base_url="...", api_token="...") as client:
        profile = await client.profile.get()
        conversations = await client.conversations.list(
            account_id=1,
            status="open"
        )

asyncio.run(main())

Working with Conversations

# List conversations with filters
conversations = client.conversations.list(
    account_id=1,
    status="open",
    assignee_type="me",
    inbox_id=5,
    labels=["urgent", "billing"]
)

# Get conversation details
conversation = client.conversations.get(account_id=1, conversation_id=42)

# Update conversation
updated = client.conversations.update(
    account_id=1,
    conversation_id=42,
    status="resolved",
    assignee_id=10
)

# Add labels to conversation
labels = client.conversations.labels.add(
    account_id=1,
    conversation_id=42,
    labels=["bug", "priority"]
)

Managing Contacts

# Create a contact
contact = client.contacts.create(
    account_id=1,
    inbox_id=5,
    name="John Doe",
    email="john@example.com",
    phone_number="+1234567890"
)

# Search contacts
results = client.contacts.search(account_id=1, query="john@example.com")

# Update contact
contact = client.contacts.update(
    account_id=1,
    contact_id=100,
    name="Jane Doe",
    custom_attributes={"plan": "premium"}
)

# Add labels to contact
labels = client.contacts.labels.add(
    account_id=1,
    contact_id=100,
    labels=["vip", "premium"]
)

Sending Messages

# Send a text message
message = client.messages.create(
    account_id=1,
    conversation_id=42,
    content="Hello! How can I help you?",
    message_type="outgoing"
)

# Send a private note
note = client.messages.create(
    account_id=1,
    conversation_id=42,
    content="Internal note for team",
    message_type="outgoing",
    private=True
)

# Update a message
updated = client.messages.update(
    account_id=1,
    message_id=123,
    content="Updated message content"
)

Managing Teams

# List teams
teams = client.teams.list(account_id=1)

# Create a team
team = client.teams.create(
    account_id=1,
    name="Support Team",
    description="Customer support team"
)

# Add agents to team
client.teams.agents.add(
    account_id=1,
    team_id=5,
    agent_ids=[10, 11, 12]
)

# List team members
members = client.teams.agents.list(account_id=1, team_id=5)

Error Handling

from chatwoot import (
    ChatwootClient,
    ChatwootAuthError,
    ChatwootNotFoundError,
    ChatwootValidationError,
)

client = ChatwootClient(base_url="...", api_token="...")

try:
    conversation = client.conversations.get(account_id=1, conversation_id=999)
except ChatwootAuthError as e:
    print(f"Authentication failed: {e}")
except ChatwootNotFoundError as e:
    print(f"Resource not found: {e}")
except ChatwootValidationError as e:
    print(f"Validation error: {e}")
    if e.errors:
        for error in e.errors:
            print(f"  - {error['field']}: {error['message']}")

API Resources

The SDK provides access to the following Chatwoot API resources:

• Profile: User profile information
• Conversations: Conversation management and filtering
• Messages: Send and manage messages
• Contacts: Contact management and search
• Inboxes: Inbox configuration
• Teams: Team management
• Agents: Agent management
• Labels: Label management (nested under conversations and contacts)

Development

Setup

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=chatwoot --cov-report=term-missing

# Type check
uvx ty check .

# Lint
uv run ruff check .

# Format code
uv run ruff format .

Project Structure

chatwoot-sdk-python/
├── chatwoot/
│   ├── __init__.py           # Public API
│   ├── client.py             # Main client classes
│   ├── exceptions.py         # Custom exceptions
│   ├── _http.py              # HTTP client wrapper
│   ├── types/                # Pydantic models
│   │   ├── common.py
│   │   ├── conversation.py
│   │   ├── message.py
│   │   ├── contact.py
│   │   └── ...
│   └── resources/            # API resource implementations
│       ├── _base.py
│       ├── profile.py
│       ├── conversations.py
│       ├── messages.py
│       └── ...
├── tests/
│   └── unit/
├── examples/
└── README.md

Requirements

• Python 3.11+
• httpx
• pydantic

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Documentation
• Issue Tracker
• Chatwoot API Documentation