Skip to main content
POST
/
proxy
/
set
/
:instanceName
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"
  }'

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

​
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.
​
validated
boolean
Whether the proxy was successfully validated.
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"
  }'

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

​
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 --request GET \
  --url https://api.example.com/proxy/find/my-instance \
  --header 'apikey: YOUR_API_KEY'

{
  "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

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.
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.
Verify username and password are correct. Check that your proxy server supports authentication. Try connecting without authentication first to isolate the issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us