Skip to main content

​
What’s Included

Chatlevel Nodes - Manage devices and send WhatsApp messages
Chatlevel Trigger Node - Listen for WhatsApp events via webhooks with dedicated output branches

​
Installation

  1. Navigate to Settings → Community Nodes in your n8n instance
  2. Click Install and enter the npm package name: n8n-nodes-Chatlevel
  3. Click Install and wait for completion
Note: Make sure your n8n instance has internet access to download the package from npm.

​
Configuration

​
Getting Your API Key from Chatlevel

  1. Log in to your Chatlevel account
  2. Go to Integrations → Add Integration → n8n
  3. Copy the generated API key

​
Setting Up Credentials in n8n

  1. In n8n, go to Credentials → New and search for “Chatlevel API”
  2. Enter your API key from Chatlevel
  3. (Optional) Set Base URL - Defaults to https://api.Chatlevel.io/v1
  4. Click Save

​
Chatlevel Node

The Chatlevel node allows you to perform operations on devices and send messages.

​
Device Operations

Create Device - Create a new WhatsApp device instance. Optionally provide a name, webhook URL, webhook events, or phone number for pairing code authentication. Get Device - Retrieve a single device by ID. Get Many Devices - Retrieve all your devices. Update Device - Update a device’s name, webhook URL, webhook events, or subscription status (active/inactive). Delete Device - Permanently delete a device. Disconnect Device - Disconnect a device from WhatsApp without deleting it. Restart Device - Restart a device’s WhatsApp connection. Optionally provide a phone number for pairing code.

​
Message Operations

Send Text - Send a text message to a WhatsApp number. Requires device ID, recipient number (digits only with country code), and message text. Send Media - Send an image (PNG, JPEG, GIF, WebP only, max 10MB) to a WhatsApp number. Choose between URL or Base64 source. Optionally add a caption.
Note: Phone numbers must be formatted as digits only with country code (e.g., 31612345678)

​
Chatlevel Trigger Node

The Chatlevel Trigger node listens for events from Chatlevel via webhooks. Each event type outputs to its own dedicated branch.

​
Event Branches

The trigger node provides 10 output branches, one for each event type:
Branch OutputEvent NameDescription
CallcallIncoming or outgoing call detected
Authconnection.authQR / Pairing Code Receipt
Closedconnection.closedConnection closed
Logoutconnection.logoutDevice logged out
Openconnection.openConnection established
Timeoutconnection.timeoutConnection timed out
Msg Deletedmessage.deletedMessage deleted
Msg Receivedmessage.receivedMessage received
Msg Sentmessage.sentMessage sent
Msg Updatedmessage.updatedMessage updated

​
Setup Guide

  1. Add Trigger Node - Add the Chatlevel Trigger node to your n8n workflow
  2. Copy Webhook URL - Click the node to reveal and copy the Webhook URL
  3. Configure in Chatlevel:
    • Go to Integrations → Add Integration → n8n in Chatlevel
    • Paste the webhook URL from step 2
    • In the Integrations tab, adjust which events you want to receive on your webhook
  4. Connect Branches - Connect different nodes to different output branches to handle events separately
Info: Events automatically route to the correct output branch. You can select specific events in Chatlevel’s Integrations tab to reduce webhook traffic.

​
Event Reference

Connection Events:
  • connection.auth - QR / Pairing Code Receipt
  • connection.open - Connection established, device ready
  • connection.closed - Connection closed
  • connection.logout - Device logged out, requires re-authentication
  • connection.timeout - Connection timed out
Message Events:
  • message.received - New message received (most common for automation)
  • message.sent - Message successfully sent
  • message.updated - Message edited or modified
  • message.deleted - Message deleted
Call Events:
  • call - Call detected on WhatsApp

​
Tips & Best Practices

Phone Number Format - Always use digits only with country code: 31612345678 (not +31 6 12345678) Device Selection - Use “From List” when building workflows. Use “By ID” when device IDs are dynamic. Error Handling - Enable “Continue on Fail” in node settings to prevent workflow stops on API errors. Media Messages - Supported formats: PNG, JPEG, GIF, WebP only. Maximum size: 10MB. Event Filtering - Use Chatlevel’s Integrations tab to select specific events and reduce webhook traffic. Multiple Devices - Each trigger node can handle events from multiple devices. Use the deviceId field to identify the source device.

​
Troubleshooting

Webhooks Not Received
  • Verify webhook URL is configured correctly in Chatlevel’s Integrations tab
  • Ensure n8n instance is accessible from the internet
  • Check device is connected and subscription is active
  • Verify correct events are selected in Chatlevel’s Integrations tab
Device Not Connecting
  • Scan QR code within time limit or use pairing code
  • Ensure device subscription status is “active”
  • Try restarting the device
  • Delete and recreate if issues persist
Messages Not Sending
  • Verify recipient number format (digits only with country code)
  • Check device status is “connected”
  • Ensure active subscription
  • For media: verify format (PNG, JPEG, GIF, WebP) and size (less than 10MB)