> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazzapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Support

> Route each WhatsApp device through an HTTP or SOCKS5 proxy

# Proxy Support

You can send each linked WhatsApp device’s traffic through its own HTTP or SOCKS5 proxy. That helps when you need a fixed exit IP, regional routing, or separation between numbers.

Proxy settings are **per device**, not for the whole workspace.

## When to use a proxy

* keep a stable public IP for a number
* run devices on different networks or regions
* meet network or compliance requirements for egress paths

## Supported formats

| Type          | Example                                     |
| :------------ | :------------------------------------------ |
| HTTP          | `http://proxy.example.com:8080`             |
| HTTP + auth   | `http://user:pass@proxy.example.com:8080`   |
| SOCKS5        | `socks5://proxy.example.com:1080`           |
| SOCKS5 + auth | `socks5://user:pass@proxy.example.com:1080` |

<Warning>
  Only `http` and `socks5` are supported. Do not use `https://` proxy URLs. HTTP proxies must include a port.
</Warning>

## Set a proxy in the dashboard

### While linking a device

<Steps>
  <Step title="Start linking">
    Go to **Devices** and link a new WhatsApp account.
  </Step>

  <Step title="Enable proxy">
    Turn on **Enable HTTP/SOCKS5 proxy** and paste your proxy URL.
  </Step>

  <Step title="Test">
    Click **Test Proxy**. Fix host, port, or credentials if the test fails.
  </Step>

  <Step title="Scan the QR code">
    Finish pairing. The device uses the proxy from the first connection.
  </Step>
</Steps>

### On an existing device

1. Open the device in **Devices**.
2. **Disconnect** the device first (you cannot change proxy while connected).
3. Update the proxy URL, run **Test Proxy** if you want, then **Save**.
4. Reconnect the device.

## Use proxies from the API

| Action                   | Method  | Endpoint                     |
| :----------------------- | :------ | :--------------------------- |
| Test a proxy             | `POST`  | `/api/v1/devices/proxy/test` |
| Link a device with proxy | `POST`  | `/api/v1/devices`            |
| Read proxy settings      | `GET`   | `/api/v1/devices/{id}/proxy` |
| Update proxy settings    | `PATCH` | `/api/v1/devices/{id}/proxy` |

Your API key needs permission to manage devices. Updating a proxy on a connected device returns **409** — disconnect, then update.

### Test example

```bash theme={null}
curl -X POST https://api.wazzapi.com/api/v1/devices/proxy/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "proxy_url": "socks5://user:pass@proxy.example.com:1080"
  }'
```

### Link with proxy

```bash theme={null}
curl -X POST https://api.wazzapi.com/api/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales line",
    "proxy": {
      "enabled": true,
      "proxy_url": "http://user:pass@proxy.example.com:8080"
    }
  }'
```

### Credentials in responses

Passwords are hidden when you read settings:

```text theme={null}
socks5://user:pass@proxy.example.com:1080
→ socks5://***@proxy.example.com:1080
```

If you save again without changing the password, you can leave the masked `***` value — your existing password is kept.

## Troubleshooting

| Problem                                  | What to try                                                                    |
| :--------------------------------------- | :----------------------------------------------------------------------------- |
| QR never appears with proxy on           | Run **Test Proxy**, check host/port/auth, try SOCKS5 if HTTP fails             |
| Error when saving proxy                  | Disconnect the device, save, then reconnect                                    |
| Password seems wrong after save          | Submit the full `user:pass@` URL once instead of only `***`                    |
| Test fails but the proxy works elsewhere | Confirm the URL uses `http` or `socks5`, and that the proxy can reach WhatsApp |

<Warning>
  A working proxy does not replace gradual sending on new numbers. See [Auto Warmer](/features/auto-warmer).
</Warning>

## Related

* [Auto Warmer](/features/auto-warmer)
* [Webhooks](/webhooks) for `device.connected` / `device.disconnected`
* [Errors](/errors)