# How to Configure a Proxy for Each Individual WhatsApp Session in OpenWA

> Learn how to configure a proxy for each individual WhatsApp session in OpenWA. This guide details storing proxy details in the database and injecting Puppeteer arguments for secure and private messaging.

- Repository: [Yudhi Armyndharis/OpenWA](https://github.com/rmyndharis/OpenWA)
- Tags: how-to-guide
- Published: 2026-05-21

---

**OpenWA supports per-session proxy configuration by storing `proxyUrl` and `proxyType` in the database and injecting `--proxy-server` arguments into Puppeteer when launching each WhatsApp Web client.**

OpenWA is an open-source WhatsApp API server that treats each connection as an isolated session, making it possible to run multiple WhatsApp Web clients simultaneously with different network configurations. When you set up a proxy for each individual WhatsApp session, the configuration travels through the entire stack—from the initial API request to the underlying Puppeteer browser instance—ensuring complete network isolation between sessions.

## How Per-Session Proxy Configuration Works in OpenWA

OpenWA implements session-scoped proxying by extending the `Session` entity with two dedicated columns and piping those values through the engine creation pipeline. Unlike global proxy settings, this architecture allows every session to route through a distinct endpoint without affecting other active connections.

### The Data Flow from API to Puppeteer

The proxy configuration follows a strict path through the codebase:

1. **API ingestion** – The `CreateSessionDto` at [`src/modules/session/dto/create-session.dto.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/dto/create-session.dto.ts) accepts optional `proxyUrl` and `proxyType` fields from the HTTP request payload.

2. **Persistence** – `SessionService.create()` (located at [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts) lines 103-108) writes these values to the `proxyUrl` and `proxyType` columns of the `Session` entity defined in [`src/modules/session/entities/session.entity.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/entities/session.entity.ts).

3. **Engine initialization** – When you start the session, `SessionService.initializeEngine()` (lines 224-231) retrieves the stored proxy fields and passes them to `EngineFactory.create()` at [`src/engine/engine.factory.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/engine/engine.factory.ts) (lines 9-13).

4. **Plugin forwarding** – The factory forwards the options to the `WhatsAppWebJsPlugin` at [`src/plugins/engines/whatsapp-web-js/index.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/plugins/engines/whatsapp-web-js/index.ts), specifically within the `createEngine()` method (lines 45-60).

5. **Puppeteer injection** – Finally, the `WhatsAppWebJsAdapter` at [`src/engine/adapters/whatsapp-web-js.adapter.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/engine/adapters/whatsapp-web-js.adapter.ts) (lines 73-89) constructs the Puppeteer launch arguments, appending `--proxy-server=<proxyUrl>` when a proxy is present.

Because the proxy information is stored per-session in the database, you can restart individual sessions without re-entering proxy credentials, and multiple sessions can run concurrently with completely different proxy endpoints.

## Step-by-Step Implementation Guide

### 1. Create a Session with Proxy Settings

Send a POST request to the `/sessions` endpoint including the `proxyUrl` and `proxyType` fields in the JSON body:

```bash
curl -X POST http://localhost:3000/sessions \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-bot-1",
        "config": { "autoReconnect": true },
        "proxyUrl": "http://user:pass@proxy.example.com:8080",
        "proxyType": "http"
      }'

```

This stores the proxy configuration in the `sessions` table alongside the session metadata. The `proxyType` supports standard protocols including `http`, `https`, `socks4`, and `socks5`.

### 2. Start the Session to Activate the Proxy

Initialize the WhatsApp Web client by starting the session:

```bash
curl -X POST http://localhost:3000/sessions/<session-id>/start

```

During startup, `SessionService.initializeEngine()` injects the stored proxy URL into the Puppeteer launch arguments. The client will route all WhatsApp Web traffic through the specified proxy endpoint rather than the host machine's default connection.

### 3. Verify Proxy Connection in Logs

The `WhatsAppWebJsAdapter` logs a sanitized confirmation line when it applies the proxy configuration:

```

Using proxy: http://***@proxy.example.com:8080

```

Monitor your server console or log files (generated by the internal `createLogger` utility) to confirm the proxy is active. If authentication fails or the proxy is unreachable, Puppeteer will throw a timeout error during the browser launch phase.

### 4. Running Multiple Sessions with Different Proxies

To run several WhatsApp accounts through different geographic endpoints, create multiple sessions with distinct proxy configurations:

```bash

# Session A – US proxy

curl -X POST http://localhost:3000/sessions \
  -d '{"name":"bot-us","proxyUrl":"http://us-proxy:3128","proxyType":"http"}'

# Session B – EU proxy  

curl -X POST http://localhost:3000/sessions \
  -d '{"name":"bot-eu","proxyUrl":"http://eu-proxy:3128","proxyType":"http"}'

```

Start each session independently. Because OpenWA maintains separate Puppeteer instances for each session—each with its own `--proxy-server` argument—the traffic from `bot-us` routes through the US endpoint while `bot-eu` routes through the EU endpoint, with no cross-contamination between sessions.

## Supported Proxy Types and Authentication

The `proxyType` field accepts the following values as implemented in the `Session` entity:

- **http** – Standard HTTP proxy
- **https** – SSL/TLS proxy connections  
- **socks4** – SOCKS version 4
- **socks5** – SOCKS version 5 with additional authentication support

Include username and password directly in the `proxyUrl` string (e.g., `http://user:pass@host:port`) for authenticated proxies. OpenWA passes this string verbatim to Puppeteer's `--proxy-server` argument; authentication is handled at the browser level during the WhatsApp Web connection handshake.

## Summary

- OpenWA stores `proxyUrl` and `proxyType` per session in the `Session` entity database table.
- The `SessionService.create()` method persists proxy settings during session creation, while `SessionService.initializeEngine()` retrieves them at startup.
- The `WhatsAppWebJsAdapter` converts stored proxy data into Puppeteer's `--proxy-server` launch argument.
- Multiple concurrent sessions can each use different proxies because the configuration is scoped to individual database records.
- No global environment variables or external proxy managers are required—the functionality is native to the OpenWA source code.

## Frequently Asked Questions

### How do I update the proxy for an existing session?

You cannot update the proxy URL for a running session without stopping and recreating it. According to the `SessionService` implementation in [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts), proxy fields are only read during the `initializeEngine()` phase when the Puppeteer browser launches. To change proxies, delete the session and create a new one with the updated `proxyUrl` value.

### Does OpenWA support rotating proxies within a single session?

No, the current architecture binds one proxy URL to one session for its entire lifecycle. The `WhatsAppWebJsAdapter` sets the `--proxy-server` argument once during browser initialization at line 73-89 of [`src/engine/adapters/whatsapp-web-js.adapter.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/engine/adapters/whatsapp-web-js.adapter.ts). To implement rotation, you must implement a rotating proxy endpoint upstream that provides different IPs through a single proxy URL, or programmatically restart sessions with new configurations.

### What happens if the proxy connection fails during startup?

If Puppeteer cannot establish a connection through the specified proxy, the `EngineFactory` will throw an initialization error before the WhatsApp Web client loads. The session status remains in a pre-authentication state, allowing you to troubleshoot the proxy settings or network connectivity without corrupting the session record in the database. Check the sanitized proxy log line to verify the URL was parsed correctly before the connection attempt.

### Can I use different proxy types for different sessions simultaneously?

Yes, the `proxyType` field is stored per-session in the database alongside `proxyUrl`. You can run one session with `socks5` while another uses `http` on the same OpenWA instance. The adapter passes the proxy URL directly to Puppeteer, which handles the protocol negotiation based on the URL scheme (`socks5://` vs `http://`), though OpenWA logs the `proxyType` value for administrative clarity.