Chatwoot

WAHA provides a built-in WhatsApp integration for Chatwoot that you can configure in a few steps using 🧩 Apps!

Chatwoot Overview

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp, ChatWoot, or any of their respective subsidiaries or affiliates. The official websites can be found at https://whatsapp.com and https://chatwoot.com.

For businesses seeking to integrate with WhatsApp for critical applications, we strongly recommend using officially supported methods.

Installation

We cover all installation and configuration aspects in the following series of articles:

ChatWoot Articles

Series of articles about WhatsApp and ChatWoot integration using 🧩 ChatWoot App:

  1. WhatsApp + ChatWoot - Overview
  2. WhatsApp + ChatWoot - Installation Guide
  3. WhatsApp + ChatWoot - Configuration Guide
  4. WhatsApp + ChatWoot - HTTPS Guide
  5. WhatsApp + ChatWoot - How It Works

You can follow them one by one or skip some parts if you don’t need them.

Configuration

To use 🧩 Apps , you need to configure the following environment variables in addition to the standard ⚙️ Configuration:

Apps:

  • WAHA_APPS_ENABLED=True - Enables the 🧩 Apps functionality
  • REDIS_URL=redis://:redis@redis:6379 - Specifies the Redis URL required for processing background jobs
  • WHATSAPP_DEFAULT_ENGINE=GOWS - Sets the recommended engine for reliable WhatsApp automation
  • WAHA_API_KEY_PLAIN=0000000000000000 - plain password required for Apps in environment variables
    • It’s a quick solution, we’re working on removing it so you can use sha512 version as in WAHA_API_KEY

Jobs:

You can configure a background worker http://localhost:3000/jobs

  • WAHA_APPS_JOBS_CONCURRENCY=50 - Maximum number of jobs processed concurrently
  • WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_AGE=259200 - Remove completed jobs after 3 days (in seconds)
  • WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_COUNT=1000 - Maximum number of completed jobs to keep
  • WAHA_APPS_JOBS_REMOVE_ON_FAIL_AGE=2678400 - Remove failed jobs after 31 days (in seconds)
  • WAHA_APPS_JOBS_REMOVE_ON_FAIL_COUNT=1000 - Maximum number of failed jobs to keep

Note: *_AGE parameters are specified in seconds by default.

Under the hood it uses bullmq.

How it works

Apps connect WhatsApp with external services using Redis as a message broker.

Apps architecture consists of:

  • HTTP API, Worker, and Session on WAHA side
  • Redis acts as the central message broker.
  • External Services, like ChatWoot
diagram

WhatsApp to External Service Flow:

  • When a new message arrives in WhatsApp, WAHA captures it and publishes a message event to Redis.
  • The Worker then picks up this event, processes it, and forwards the message to ChatWoot via its API.
  • After successful delivery, the job is marked as processed in Redis.
diagram

External Service to WhatsApp Flow:

  • When a new message is created in ChatWoot, it calls the WAHA API webhook.
  • The API saves this job to the Redis queue, from which the Worker retrieves it.
  • The Worker then requests the WAHA API to send the message to WhatsApp.
  • After WhatsApp confirms delivery, the API acknowledges the Worker, which then marks the job as processed in Redis.
diagram

Error Handling

In case of any errors, WAHA retries a few times and then gives detailed information about the error:

Error Reports and Retries

You can use the WAHA Jobs Dashboard at http://localhost:3000/jobs for monitoring:

WAHA Jobs Dashboard