OpenAPI Marketplace · Customer Support

Chatwoot Conversations & Contacts

Name: Chatwoot Conversations & Contacts
Author: vx.ai

v1.0.0 · 15 endpoints · 0 connections · shared by vx.ai

For support teams on Chatwoot: see how many conversations are open, read a thread, reply or leave a private note, assign it to an agent or team, label it and mark it resolved. Contact search and canned responses help draft the answer.

Connect this API to an AI agent Browse all specs

What you can do with Chatwoot Conversations & Contacts via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/api/v1/accounts/{account_id}/conversations/meta`	getConversationCounts	Count conversations by status (mine, unassigned, all)
GET	`/api/v1/accounts/{account_id}/conversations`	listConversations	List conversations, filtered by status, inbox, team or label
GET	`/api/v1/accounts/{account_id}/conversations/{conversation_id}`	getConversation	Get one conversation with its contact and assignee
GET	`/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages`	listConversationMessages	Read the messages in a conversation
POST	`/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages`	sendConversationMessage	Reply to the customer or add a private note
POST	`/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status`	toggleConversationStatus	Set a conversation to open, resolved, pending or snoozed
POST	`/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments`	assignConversation	Assign a conversation to an agent or team
POST	`/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels`	addConversationLabels	Set the labels on a conversation
GET	`/api/v1/accounts/{account_id}/contacts/search`	searchContacts	Search contacts by name, email, phone or identifier
GET	`/api/v1/accounts/{account_id}/contacts/{id}`	getContact	Get a contact's details
GET	`/api/v1/accounts/{account_id}/contacts/{id}/conversations`	listContactConversations	List a contact's past conversations
GET	`/api/v1/accounts/{account_id}/inboxes`	listInboxes	List the inboxes (website, email, WhatsApp, ...)
GET	`/api/v1/accounts/{account_id}/agents`	listAgents	List the agents in the account
GET	`/api/v1/accounts/{account_id}/teams`	listTeams	List the teams in the account
GET	`/api/v1/accounts/{account_id}/canned_responses`	listCannedResponses	List saved canned responses (search by short code)

Authentication

userApiKey

API key — sent as the api_access_token header

Chatwoot user access token, sent in the api_access_token header.

How to get a credential

Sign in to Chatwoot (app.chatwoot.com or your self-hosted install).
Click your avatar > Profile settings.
Scroll to Access Token and copy it.
Note your account id: it is the number after /accounts/ in the dashboard URL.

Permissions used

The token acts as that user, with the user's role.

Role needed	Operations
Agent (inboxes they belong to)	getConversationCounts, listConversations, getConversation, listConversationMessages, sendConversationMessage, toggleConversationStatus, addConversationLabels, searchContacts, getContact, listContactConversations, listInboxes, listCannedResponses
Agent or administrator	assignConversation, listAgents, listTeams

Common errors

401 Unauthorized: the token is missing or was reset. Copy it again from Profile settings.
403 / 404: the account_id is wrong or the user is not a member of that inbox.
400 / 422: a field is invalid, e.g. a status other than open, resolved, pending or snoozed.
429 Too Many Requests: slow down and retry after a short pause.

Save it in VX Agents as an API key credential for this spec.

Usage guide

Setup

Credential: your Chatwoot user access token (Profile settings > Access Token), sent as api_access_token. The agent can do what that user's role allows.
Pin account_id: the number after /accounts/ in your dashboard URL. Self-hosted Chatwoot: change the base URL to your own host (e.g. https://support.example.com).

Work the support queue

getConversationCounts to see how many are open, mine and unassigned.
listConversations with status=open and assignee_type=unassigned (or me, assigned, all), plus inbox_id, team_id or labels to narrow it. 25 per page: add page=2, page=3, ...
getConversation and listConversationMessages to read the thread. message_type 0 = incoming (customer), 1 = outgoing (agent), 2 = activity.
Context: getContact and listContactConversations for past issues; searchContacts with q (name, email, phone) when you only know the customer.
Draft the answer, using listCannedResponses for approved wording. Show the draft to the user.
After the user confirms: sendConversationMessage with content and message_type: "outgoing". Set private: true for an internal note the customer never sees.
assignConversation with assignee_id (from listAgents) or team_id (from listTeams). addConversationLabels with the full labels list. Then toggleConversationStatus with status resolved, pending or snoozed (with snoozed_until).

Good to know

Ask before you send a reply, change status or reassign: replies go straight to the customer's email, WhatsApp or web chat.
addConversationLabels replaces the whole label list. Read the current labels from getConversation first and send them along with the new ones.
listInboxes shows each channel type (Channel::WebWidget, Channel::Email, Channel::Whatsapp, ...). Replies go out on the conversation's own channel.
Timestamps are Unix seconds. Ids are integers.
WhatsApp only allows free-form replies within 24 hours of the customer's last message.
Source: Chatwoot API reference (https://developers.chatwoot.com/api-reference/introduction), checked 2026-10-16.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Chatwoot Conversations & Contacts” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.