ChatWoot

Consume ChatWoot API

Actions11

Overview

The ChatWoot node for n8n enables you to interact with the ChatWoot API, specifically to create new contacts within your ChatWoot account. This is useful for automating the process of adding leads, customers, or users into your ChatWoot CRM from various sources such as web forms, other CRMs, or support systems.

Common scenarios:

Automatically creating a contact in ChatWoot when a new user signs up on your website.
Syncing contacts from another platform (like HubSpot or Salesforce) into ChatWoot.
Adding contacts based on incoming messages or events from other workflows.

Practical example:
When a new lead fills out a form on your website, this node can be used to create a corresponding contact in ChatWoot, including their name, email, phone number, and any custom attributes.

Properties

Below are the input properties relevant for the Contact → Create operation:

Display Name	Type	Meaning
Authentication	options	Choose between providing parameters directly or using predefined Chatwoot credentials.
BaseUrl	string	The base URL of your ChatWoot instance (e.g., `https://chatwoot.org`).
Access Token	string	Your ChatWoot access token; can override credentials if provided directly.
Account ID	string	(Optional) Reference to a specific ChatWoot account; overrides credentials if set.
Source ID	string	Internal source contact identifier (URL-escaped or HEX); used for search or identification.
Contact Identifier	string	(Optional) External API contact identifier for the contact being created.
Name	string	The name of the contact to be created.
Inbox ID	string	The inbox ID to associate with the contact.
Phone Number	string	The contact's phone number.
E-Mail	string	The contact's email address.
Custom Attributes	fixedCollection	Key-value pairs for any additional custom attributes to store with the contact.

Output

The node outputs a JSON object representing the newly created contact. The structure typically includes:

{
  "id": "string",
  "name": "string",
  "email": "string",
  "phone_number": "string",
  "inbox_id": "string",
  "custom_attributes": {
    "key1": "value1",
    "key2": "value2"
  },
  // ...other fields returned by the ChatWoot API
}

If an error occurs and "Continue On Fail" is enabled, the output will include an error field with the error message.

Dependencies

External Service: Requires access to a ChatWoot instance (cloud or self-hosted).
API Key: You must provide a valid ChatWoot access token.
n8n Credentials: Optionally, you can use predefined ChatWoot credentials configured in n8n.
Environment Variables: None required unless your n8n instance is configured to load credentials from environment variables.

Troubleshooting

Common issues:

Invalid Credentials: If the access token or base URL is incorrect, authentication will fail.
Missing Required Fields: Not providing mandatory fields like Name or Email may result in API errors.
Incorrect Account ID: Supplying an invalid or unauthorized Account ID can cause failures.
Network Issues: Ensure that your n8n instance can reach your ChatWoot server.

Error messages:

"Authentication failed": Check your access token and base URL.
"Required parameter missing": Make sure all required fields are filled.
"Resource not found": Verify the Account ID, Inbox ID, or other identifiers.

How to resolve:

Double-check your credentials and endpoint URLs.
Ensure all required properties are provided.
Review the ChatWoot API documentation for expected request formats.