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

> Learn how to enable the WhatsApp gateway for Dexter with this complete setup guide. Configure your gateway, run Dexter, and scan the QR code to connect your WhatsApp.

- Repository: [Virat Singh/dexter](https://github.com/virattt/dexter)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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.

```json
{
  "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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/gateway.config.json) file in your project root with the WhatsApp channel enabled. The `authDir` path is where Dexter will store the [`creds.json`](https://github.com/virattt/dexter/blob/main/creds.json) file after successful authentication.

```json
{
  "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`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/login.ts) initiates the QR code flow.

```bash
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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/gateway/extension-points.ts)). When you enable the WhatsApp gateway for Dexter, the `createWhatsAppPlugin` function (invoked in [`src/gateway/index.ts`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/gateway/config.ts) | Defines the `WhatsAppAccountSchema`, loads configuration via `loadGatewayConfig`, and resolves accounts with `resolveWhatsAppAccount` |
| [`src/gateway/index.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/index.ts) | Bootstraps the gateway, registers the WhatsApp plugin via `createWhatsAppPlugin`, and starts the event loop |
| [`src/gateway/gateway.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/gateway.ts) | Core inbound/outbound handling, markdown cleaning (`cleanMarkdownForWhatsApp`), and message routing |
| [`src/gateway/channels/whatsapp/login.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/login.ts) | QR-code login flow (`loginWhatsApp`) and credential persistence to [`creds.json`](https://github.com/virattt/dexter/blob/main/creds.json) |
| [`src/gateway/channels/whatsapp/runtime.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/runtime.ts) | Message monitoring via `monitorWhatsAppChannel` and WhatsApp Web client management |
| [`src/gateway/channels/whatsapp/outbound.ts`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/creds.json) within your specified `authDir`.
- Incoming messages are processed by `monitorWhatsAppChannel` in [`src/gateway/channels/whatsapp/runtime.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/runtime.ts) and routed through `handleInbound` in [`src/gateway/gateway.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/gateway.ts).
- Outbound replies are formatted by `cleanMarkdownForWhatsApp` and sent via `sendMessageWhatsApp` in [`src/gateway/channels/whatsapp/outbound.ts`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/runtime.ts) will attempt to restore the session using the existing [`creds.json`](https://github.com/virattt/dexter/blob/main/creds.json) file in your `authDir`. If restoration fails, delete the [`creds.json`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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.