Create a Chatwoot conversation via the API channel and build an Agent Bot handoff pattern
domain: developers.chatwoot.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Obtain either a User API key (Profile Settings → Access Token, full permission of the issuing user) or an Agent Bot API key (issued by a system admin), and send it in the api_access_token header
Create a contact, then create a conversation with POST /api/v1/accounts/{account_id}/conversations, supplying the required source_id tied to that contact/inbox plus optional inbox_id, additional_attributes, custom_attributes, status, assignee_id, and an initial message block
Send further messages into the conversation with POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages
For a bot integration, receive conversation events via webhooks configured on the Agent Bot, reply through the Create Message API, and flip conversation status from pending to open to hand off to a human agent
Substitute your own self-hosted instance URL in place of app.chatwoot.com if not using Chatwoot Cloud
Known gotchas
source_id is required and must be tied to a contact/inbox of type Website, Phone, Api, or Email — a missing or mismatched source_id is the most common integration error
User API keys and Agent Bot API keys share the identical api_access_token header name but carry different permission scopes, so a route must be explicit about which key type it's using
The base URL differs between Chatwoot Cloud (app.chatwoot.com) and self-hosted deployments — don't hardcode the cloud domain
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?