How to Enable the WhatsApp Gateway for Dexter: A Complete Setup Guide

Enable Dexter’s WhatsApp gateway by adding a channels.whatsapp configuration block to your gateway config file, running dexter gateway run, and scanning the QR code with your phone to authenticate.

Dexter is an open-source AI agent framework that supports multiple communication channels. When you enable the WhatsApp gateway for Dexter, you allow users to interact with your agent directly through the WhatsApp app on their phones. This integration works by bridging WhatsApp Web with Dexter’s core processing logic, handling inbound messages and outbound replies through a dedicated plugin system.

Prerequisites and Configuration Schema

Before starting the gateway, you need to understand how Dexter validates WhatsApp configuration. The system uses a strict schema defined in src/gateway/config.ts to ensure all required fields are present.

Understanding the WhatsApp Account Schema

The WhatsAppAccountSchema (lines 18-43 in src/gateway/config.ts) defines the structure for each account entry. Each account requires an authDir property that specifies where the WhatsApp Web credentials will be stored after QR code authentication.

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "accounts": {
        "default": {
          "authDir": "./.whatsapp/auth"
        }
      },
      "defaultAccountId": "default"
    }
  }
}

The loadGatewayConfig function reads this configuration from JSON or YAML files, while resolveWhatsAppAccount (lines 150-159 in src/gateway/config.ts) retrieves the specific account details when the gateway initializes.

Step-by-Step: Enable the WhatsApp Gateway for Dexter

Follow these steps to activate the WhatsApp channel and establish a connection with your phone.

1. Configure Your WhatsApp Account

Create a gateway.config.json file in your project root with the WhatsApp channel enabled. The authDir path is where Dexter will store the creds.json file after successful authentication.

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "accounts": {
        "default": {
          "authDir": "./.whatsapp/auth"
        }
      },
      "defaultAccountId": "default"
    }
  }
}

2. Authenticate with QR Code Login

Run the gateway using the Dexter CLI. The loginWhatsApp function in src/gateway/channels/whatsapp/login.ts initiates the QR code flow.

npx dexter gateway run --config ./gateway.config.json

The terminal will display a QR code. Open WhatsApp on your phone, navigate to Settings → Linked Devices → Link a Device, and scan the code. Once scanned, the gateway stores your credentials in the authDir location and begins monitoring for messages.

3. Monitor Inbound Messages

After authentication, monitorWhatsAppChannel in src/gateway/channels/whatsapp/runtime.ts creates a WhatsApp Web client that listens for incoming messages. When a message arrives, the gateway processes it through the handleInbound function in src/gateway/gateway.ts (lines 46-115).

The inbound handler sanitizes the message content and routes it to Dexter’s core agent logic. You can test this by sending any message to your WhatsApp number; the gateway will receive it and generate a response.

4. Handle Outbound Replies

When Dexter generates a response, sendMessageWhatsApp in src/gateway/channels/whatsapp/outbound.ts formats the output and sends it back to the user. This function converts Markdown formatting to WhatsApp’s limited markup set using cleanMarkdownForWhatsApp (defined in src/gateway/gateway.ts), ensuring that bold and italic text renders correctly in the WhatsApp client.

How the WhatsApp Gateway Processes Messages

The WhatsApp integration follows a structured pipeline defined in the gateway plugin system (src/gateway/extension-points.ts). When you enable the WhatsApp gateway for Dexter, the createWhatsAppPlugin function (invoked in src/gateway/index.ts lines 5-38) registers the channel with the core gateway runtime.

The message flow works as follows:

1. Receive: monitorWhatsAppChannel captures incoming WhatsApp Web events
2. Parse: The gateway extracts text content and sender metadata
3. Process: handleInbound routes the message to Dexter’s agent logic
4. Format: cleanMarkdownForWhatsApp converts rich text to WhatsApp-compatible markup
5. Send: sendMessageWhatsApp delivers the response via the WhatsApp Web client

This architecture ensures that enabling the WhatsApp gateway requires only configuration changes, with no modifications to Dexter’s core agent logic.

Troubleshooting and File Reference

When you enable the WhatsApp gateway for Dexter, these source files handle specific functions:

File	Role
src/gateway/config.ts	Defines the WhatsAppAccountSchema, loads configuration via loadGatewayConfig, and resolves accounts with resolveWhatsAppAccount
src/gateway/index.ts	Bootstraps the gateway, registers the WhatsApp plugin via createWhatsAppPlugin, and starts the event loop
src/gateway/gateway.ts	Core inbound/outbound handling, markdown cleaning (cleanMarkdownForWhatsApp), and message routing
src/gateway/channels/whatsapp/login.ts	QR-code login flow (loginWhatsApp) and credential persistence to creds.json
src/gateway/channels/whatsapp/runtime.ts	Message monitoring via monitorWhatsAppChannel and WhatsApp Web client management
src/gateway/channels/whatsapp/outbound.ts	Reply formatting and sending via sendMessageWhatsApp

If the gateway fails to start, verify that your authDir path is writable and that you have scanned the QR code within the timeout window defined in loginWhatsApp.

Summary

• Enable the WhatsApp gateway for Dexter by adding a channels.whatsapp block to your gateway configuration file with enabled: true and a valid authDir path.
• The loadGatewayConfig and resolveWhatsAppAccount functions in src/gateway/config.ts validate your setup before the gateway starts.
• Authenticate by running dexter gateway run and scanning the QR code with your phone’s WhatsApp app; credentials are stored in creds.json within your specified authDir.
• Incoming messages are processed by monitorWhatsAppChannel in src/gateway/channels/whatsapp/runtime.ts and routed through handleInbound in src/gateway/gateway.ts.
• Outbound replies are formatted by cleanMarkdownForWhatsApp and sent via sendMessageWhatsApp in src/gateway/channels/whatsapp/outbound.ts.

Frequently Asked Questions

How do I restart the WhatsApp gateway if it loses connection?

If the WhatsApp Web client disconnects, stop the gateway with Ctrl+C and run npx dexter gateway run --config ./gateway.config.json again. The monitorWhatsAppChannel function in src/gateway/channels/whatsapp/runtime.ts will attempt to restore the session using the existing creds.json file in your authDir. If restoration fails, delete the creds.json file and scan the QR code again to re-authenticate.

Can I run multiple WhatsApp accounts with Dexter?

Yes, the WhatsAppAccountSchema in src/gateway/config.ts supports multiple account entries under the accounts object. Define unique account IDs (e.g., "business" and "personal") with separate authDir paths for each, then set the defaultAccountId to specify which account the gateway should use at startup. You can switch accounts by changing the defaultAccountId and restarting the gateway.

Where are WhatsApp credentials stored?

WhatsApp Web credentials are stored in a creds.json file located inside the directory specified by the authDir property in your configuration. The loginWhatsApp function in src/gateway/channels/whatsapp/login.ts writes this file after successful QR code authentication, and monitorWhatsAppChannel reads it to restore sessions on subsequent gateway starts. Keep this directory secure and add it to your .gitignore file to prevent credential leaks.

Does Dexter support WhatsApp Business API or only WhatsApp Web?

The current implementation uses WhatsApp Web via the monitorWhatsAppChannel function in src/gateway/channels/whatsapp/runtime.ts, which requires a phone with an active WhatsApp installation to remain connected. This differs from the official WhatsApp Business API, which requires Meta approval and uses cloud-based webhooks. Dexter’s gateway is designed for self-hosted deployments using the WhatsApp Web protocol, making it suitable for personal or small-scale use without third-party API registration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}