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.
- 🔒 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
pip install chatwoot-sdk
# or
uv add chatwoot-sdkNote: The PyPI package name is
chatwoot-sdk. The GitHub repository is namedchatwoot-sdk-python.
fromchatwootimportChatwootClient# Initialize the clientclient=ChatwootClient(
base_url="https://app.chatwoot.com",
api_token="your_api_token_here"
)
# Fetch your profileprofile=client.profile.get()
print(f"Logged in as: {profile.name}")
# List open conversationsconversations=client.conversations.list(
account_id=1,
status="open"
)
# Send a messagemessage=client.messages.create(
account_id=1,
conversation_id=42,
content="Hello from Python SDK!"
)
# Always close the client when doneclient.close()fromchatwootimportChatwootClientwithChatwootClient(base_url="...", api_token="...") asclient:
profile=client.profile.get()
conversations=client.conversations.list(account_id=1, status="open")
# Client is automatically closedimportasynciofromchatwootimportAsyncChatwootClientasyncdefmain():
asyncwithAsyncChatwootClient(base_url="...", api_token="...") asclient:
profile=awaitclient.profile.get()
conversations=awaitclient.conversations.list(
account_id=1,
status="open"
)
asyncio.run(main())# List conversations with filtersconversations=client.conversations.list(
account_id=1,
status="open",
assignee_type="me",
inbox_id=5,
labels=["urgent", "billing"]
)
# Get conversation detailsconversation=client.conversations.get(account_id=1, conversation_id=42)
# Update conversationupdated=client.conversations.update(
account_id=1,
conversation_id=42,
status="resolved",
assignee_id=10
)
# Add labels to conversationlabels=client.conversations.labels.add(
account_id=1,
conversation_id=42,
labels=["bug", "priority"]
)# Create a contactcontact=client.contacts.create(
account_id=1,
inbox_id=5,
name="John Doe",
email="john@example.com",
phone_number="+1234567890"
)
# Search contactsresults=client.contacts.search(account_id=1, query="john@example.com")
# Update contactcontact=client.contacts.update(
account_id=1,
contact_id=100,
name="Jane Doe",
custom_attributes={"plan": "premium"}
)
# Add labels to contactlabels=client.contacts.labels.add(
account_id=1,
contact_id=100,
labels=["vip", "premium"]
)# Send a text messagemessage=client.messages.create(
account_id=1,
conversation_id=42,
content="Hello! How can I help you?",
message_type="outgoing"
)
# Send a private notenote=client.messages.create(
account_id=1,
conversation_id=42,
content="Internal note for team",
message_type="outgoing",
private=True
)
# Update a messageupdated=client.messages.update(
account_id=1,
message_id=123,
content="Updated message content"
)# List teamsteams=client.teams.list(account_id=1)
# Create a teamteam=client.teams.create(
account_id=1,
name="Support Team",
description="Customer support team"
)
# Add agents to teamclient.teams.agents.add(
account_id=1,
team_id=5,
agent_ids=[10, 11, 12]
)
# List team membersmembers=client.teams.agents.list(account_id=1, team_id=5)fromchatwootimport (
ChatwootClient,
ChatwootAuthError,
ChatwootNotFoundError,
ChatwootValidationError,
)
client=ChatwootClient(base_url="...", api_token="...")
try:
conversation=client.conversations.get(account_id=1, conversation_id=999)
exceptChatwootAuthErrorase:
print(f"Authentication failed: {e}")
exceptChatwootNotFoundErrorase:
print(f"Resource not found: {e}")
exceptChatwootValidationErrorase:
print(f"Validation error: {e}")
ife.errors:
forerrorine.errors:
print(f" - {error['field']}: {error['message']}")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)
# 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 .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
- Python 3.11+
- httpx
- pydantic
MIT License - see LICENSE file for details
Contributions are welcome! Please feel free to submit a Pull Request.