## Overview

When the **Managed WhatsApp Web proxy** feature is enabled, Conversa Labs reserves a proxy route before
creating the inbox. Provider credentials remain under platform-operator control and are never shown to
account administrators or agents.

**Automatic** is the recommended option. The platform selects a healthy route using region, provider
priority, latency and capacity. After pairing, the phone's country code (DDI) may cause one soft
reconnect to refine the region. The assignment remains fixed for the inbox, and residential gateways use
a sticky session identity.

The flow is **fail-closed**: if no healthy proxy has capacity, creation is blocked before pairing. The
inbox never connects directly without notice. After a later failure, failover tries another approved
route; without a safe replacement, the session is held.

## Prerequisites

- The platform operator has added and tested at least one active proxy connection.
- The **Managed WhatsApp Web proxy** feature is enabled for your account.
- An account administrator can create a WhatsApp Web inbox.
- The phone is available to scan a QR code or enter the pairing code.

The only accepted providers are Webshare, Bright Data and a custom endpoint deliberately supplied by
the operator. Plan purchase and administration take place outside Conversa Labs.

Credentials by provider:

- **Webshare**: an API key can automatically synchronize the static proxy inventory; gateway/backbone
  mode can use the proxy's native username and password. Use the credential type supported by the
  purchased connection mode.
- **Bright Data**: use the Zone username, such as `brd-customer-...-zone-...`, and Zone password from
  **Proxies → Access details**. **Do not use a REST API key.** For HTTP mode, the defaults are
  `brd.superproxy.io` and port `44445` (older accounts and the Proxy Manager still use `33335`;
  if a connection test fails on one, try the other).
- **Custom**: the operator supplies the protocol, host, port, capacity/region and, when required, a
  username and password. Register only controlled and trusted endpoints.

## Step by step

1. Go to **Settings → Inboxes → Add inbox → WhatsApp Web**.
2. Enter the inbox name.
3. Under **Managed connection proxy**, keep **Automatic (recommended)** or choose an available country.
4. Configure the remaining options and click **Create WhatsApp Web channel**.
5. If the platform reports that no safe route is available, do not continue in direct mode. Ask the
   operator to restore capacity and try again.
6. Once the reservation is confirmed, click **Connect WhatsApp** and pair by QR code or phone code.
7. After pairing, the platform confirms the DDI and refines the region when needed. This does not create
   another inbox.

### Going back to direct egress (no proxy)

An inbox already on a managed proxy can go back to exiting through the server IP:

1. Open **Settings → Inboxes → your inbox → Connection**.
2. On the network route card, choose **No proxy (direct egress)**.
3. Click **Use direct egress**. The proxy reservation is released and the gateway exits directly.

The option stays available even if the proxy feature is later disabled on the account — otherwise the
inbox would be stuck on the old route. An inbox routed through **your own device** cannot be returned to
direct egress here: the gateway only tears that route down by deleting the session, which disconnects
WhatsApp.

## Settings & options

- **Automatic**: chooses the best healthy route using geography, priority, health, latency and capacity.
- **Country selection**: requests a region. Another approved region may be chosen when the preferred one
  is unavailable; without any safe route, creation is blocked.
- **Fixed assignment**: a static or dedicated endpoint remains reserved for the inbox.
- **Sticky gateway**: rotating/residential providers receive a stable session identity for the inbox.
- **Automatic failover**: repeated health failures move the inbox to another approved endpoint. A
  cooldown avoids rapid route changes.
- **Safe hold**: if the approved pool is unavailable, the connection is held; there is no automatic
  direct fallback.

## Use cases

- Keep the WhatsApp Web session close to the phone number's country.
- Give each inbox a stable dedicated IP or sticky residential identity.
- Distribute many inboxes across approved subscriptions without exposing credentials.
- Fail over between trusted routes without allowing silent direct egress.

## Tips, limits & best practices

- Prefer stable, dedicated/static endpoints when your provider offers them. Avoid unnecessary region or
  identity changes.
- A proxy improves routing isolation but does not bypass WhatsApp policies, messaging limits or account
  quality controls.
- Never paste provider credentials into the inbox wizard. Account administrators only choose the
  routing preference.
- For Bright Data, the required password belongs to the **proxy Zone**, not the account password or an
  API key.
- For Webshare, immediately revoke any API key exposed in a screenshot, chat or log.
- If you choose a country manually, use the country where the number is normally operated.
- Pausing a provider prevents new assignments. Without an approved replacement, affected routes are
  held.
- In a **hybrid inbox** (WhatsApp Web paired with Cloud), the route only applies to traffic leaving
  through WhatsApp Web. Messages sent through the Cloud API always exit from the server's own IP,
  whichever proxy is selected. The route is managed on the **Connection** tab of the pair's WhatsApp
  Web inbox — the Cloud inbox's **Hybrid** tab shows the current route and links to it.

## Troubleshooting

- **The proxy section is not visible**: ask the operator to enable the feature for your account.
- **No countries are listed**: inventory may be synchronizing or have no healthy capacity. Wait for it
  to recover; creation will not use a direct connection.
- **Creation was blocked because no route was available**: this is intentional. The operator must test
  provider credentials, health, capacity and regions before you try again.
- **Bright Data asks for credentials**: copy the Zone username and password from
  **Proxies → Access details**. Do not create an API key for this adapter.
- **Webshare does not synchronize static proxies**: confirm the API key and selected plan. For
  gateway/backbone mode, check the native username, password, host and port.
- **A custom endpoint fails**: check protocol, DNS/host, port, authentication, capacity and whether the
  Conversa Labs server can reach it safely.
- **The session reconnects once after pairing**: the phone's DDI differed from the initial estimate and
  the route was refined. This is expected.
- **Repeated disconnections**: check provider health. Failover uses only approved endpoints; if all are
  offline, the inbox is held.

## See also

- [Connect WhatsApp Web by QR pairing](/hc/ajuda/articles/inboxes-channels-whatsapp-web-wazmeow-en)
- [WhatsApp hybrid inbox](/hc/ajuda/articles/inboxes-channels-whatsapp-hybrid-inbox-en)
- [WhatsApp Inbox Suite](/hc/ajuda/articles/inboxes-channels-whatsapp-inbox-suite-en)