Configure Proxy

Configure HTTP/HTTPS/SOCKS proxy settings for your WhatsApp instance.

POST /proxy/set/:instanceName

cURL (HTTP Proxy)

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": true,
    "host": "proxy.example.com",
    "port": "8080",
    "protocol": "http"
  }'

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": true,
    "host": "socks-proxy.example.com",
    "port": "1080",
    "protocol": "socks5",
    "username": "proxyuser",
    "password": "proxypass123"
  }'

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": false
  }'

// Configure HTTP proxy
const response = await fetch(
  'https://api.example.com/proxy/set/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      enabled: true,
      host: 'proxy.example.com',
      port: '8080',
      protocol: 'http',
      username: 'proxyuser',
      password: 'proxypass123'
    })
  }
);

const data = await response.json();

import requests

# Configure SOCKS5 proxy
response = requests.post(
    'https://api.example.com/proxy/set/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'enabled': True,
        'host': 'socks-proxy.example.com',
        'port': '1080',
        'protocol': 'socks5',
        'username': 'proxyuser',
        'password': 'proxypass123'
    }
)

data = response.json()

201 Success

{
  "proxy": {
    "enabled": true,
    "host": "proxy.example.com",
    "port": "8080",
    "protocol": "http",
    "username": "proxyuser"
  },
  "validated": true
}

{
  "error": "Invalid proxy",
  "message": "Could not connect to the specified proxy server"
}

{
  "error": "Invalid request",
  "message": "Host, port, and protocol are required when proxy is enabled"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Overview

You can route your WhatsApp instance traffic through a proxy server. This is useful for bypassing network restrictions, improving privacy, or routing traffic through specific geographic locations.

Proxy configuration is validated before being applied. Invalid proxy settings will be rejected to prevent connection issues.

Authentication

This endpoint requires authentication via the apikey header.

header.apikey · string · required

Your Evolution API key for authentication.

Path Parameters

path.instanceName · string · required

The name of your WhatsApp instance.

Request Body

enabled · boolean · default: "false"

Enable or disable the proxy. Set to false to disable proxy and use direct connection.

host · string · required

Proxy server hostname or IP address (e.g., “proxy.example.com” or “192.168.1.100”).

port · string · required

Proxy server port (e.g., “8080” or “3128”).

protocol · string · required

Proxy protocol. Supported values:

• http: HTTP proxy
• https: HTTPS proxy
• socks4: SOCKS4 proxy
• socks5: SOCKS5 proxy

username · string

Proxy authentication username (if required by your proxy server).

password · string

Proxy authentication password (if required by your proxy server).

Response

proxy · object

The configured proxy settings.

Show properties

enabled · boolean

Whether the proxy is enabled.

host · string

Proxy server hostname.

port · string

Proxy server port.

protocol · string

Proxy protocol being used.

username · string

Proxy username (if configured).

validated · boolean

Whether the proxy was successfully validated.

cURL (HTTP Proxy)

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": true,
    "host": "proxy.example.com",
    "port": "8080",
    "protocol": "http"
  }'

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": true,
    "host": "socks-proxy.example.com",
    "port": "1080",
    "protocol": "socks5",
    "username": "proxyuser",
    "password": "proxypass123"
  }'

curl --request POST \
  --url https://api.example.com/proxy/set/my-instance \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": false
  }'

// Configure HTTP proxy
const response = await fetch(
  'https://api.example.com/proxy/set/my-instance',
  {
    method: 'POST',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      enabled: true,
      host: 'proxy.example.com',
      port: '8080',
      protocol: 'http',
      username: 'proxyuser',
      password: 'proxypass123'
    })
  }
);

const data = await response.json();

import requests

# Configure SOCKS5 proxy
response = requests.post(
    'https://api.example.com/proxy/set/my-instance',
    headers={
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'enabled': True,
        'host': 'socks-proxy.example.com',
        'port': '1080',
        'protocol': 'socks5',
        'username': 'proxyuser',
        'password': 'proxypass123'
    }
)

data = response.json()

201 Success

{
  "proxy": {
    "enabled": true,
    "host": "proxy.example.com",
    "port": "8080",
    "protocol": "http",
    "username": "proxyuser"
  },
  "validated": true
}

{
  "error": "Invalid proxy",
  "message": "Could not connect to the specified proxy server"
}

{
  "error": "Invalid request",
  "message": "Host, port, and protocol are required when proxy is enabled"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Instance not found",
  "message": "The instance 'my-instance' does not exist"
}

Proxy Validation

Before applying proxy settings, Evolution API validates the proxy by:

1. Attempting to connect to https://icanhazip.com/ directly
2. Attempting to connect through the configured proxy
3. Comparing the IP addresses to ensure the proxy is working

The proxy must successfully route traffic and change the origin IP address to pass validation.

Supported Proxy Types

HTTP Proxy

Standard HTTP proxy. Most common type, widely supported. Good for basic proxy needs.

{
  "protocol": "http",
  "host": "proxy.example.com",
  "port": "8080"
}

HTTPS Proxy

Encrypted HTTP proxy connection. Provides additional security for the proxy connection itself.

{
  "protocol": "https",
  "host": "secure-proxy.example.com",
  "port": "8443"
}

SOCKS4/SOCKS5

SOCKS proxies work at a lower level and can handle any type of traffic. SOCKS5 supports authentication, while SOCKS4 does not.

{
  "protocol": "socks5",
  "host": "socks-proxy.example.com",
  "port": "1080",
  "username": "user",
  "password": "pass"
}

Usage Notes

Changing proxy settings while the instance is connected may cause a brief disconnection. The instance will automatically reconnect using the new proxy settings.

Always test your proxy configuration with a development instance before applying to production instances.

Proxy credentials (username and password) are stored securely but should still be treated as sensitive information.

Get Current Proxy Configuration

To retrieve current proxy settings:

GET /proxy/find/:instanceName

This returns the currently configured proxy settings (password is not included in the response for security).

cURL

curl --request GET \
  --url https://api.example.com/proxy/find/my-instance \
  --header 'apikey: YOUR_API_KEY'

200 Success

{
  "proxy": {
    "enabled": true,
    "host": "proxy.example.com",
    "port": "8080",
    "protocol": "http",
    "username": "proxyuser"
  }
}

Disabling Proxy

To disable proxy and use a direct connection:

{
  "enabled": false
}

When disabled, the host, port, protocol, username, and password fields are automatically cleared.

Common Use Cases

Geographic Routing

Route your WhatsApp instance through a specific country’s proxy to appear as if you’re connecting from that location.

Network Restrictions

Bypass corporate firewalls or network restrictions that may block WhatsApp’s servers.

Load Distribution

Distribute multiple instances across different proxy servers to balance load and reduce the risk of rate limiting.

Privacy Enhancement

Hide your server’s actual IP address from WhatsApp’s servers by routing all traffic through a proxy.

Troubleshooting

Proxy validation fails

Ensure your proxy server is running and accessible. Check that the host, port, and protocol are correct. Verify firewall rules allow outbound connections to the proxy.

Instance won't connect with proxy

Try disabling the proxy temporarily to verify the instance works without it. Check proxy server logs for connection errors. Ensure the proxy supports HTTPS connections.

Authentication errors

Verify username and password are correct. Check that your proxy server supports authentication. Try connecting without authentication first to isolate the issue.