Proxy

Set an instance proxy override

Sets a proxy for a single instance. The override wins over the tenant-wide proxy. The instance is reconnected so it dials through the new proxy immediately.

PUT
/devices/{deviceID}/proxy

Sets a proxy for a single instance. The override wins over the tenant-wide proxy. The instance is reconnected so it dials through the new proxy immediately.

Authorization

bearerAuth
AuthorizationBearer <token>

Per-user API token (UUID v4) sent as Authorization: Bearer <token>. Identifies the tenant and user.

In: header

Path Parameters

deviceID*string

Instance (device) identifier.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Payload for setting a tenant-wide or per-instance proxy.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/devices/ad14fdc2-b86a-42be-ba69-1107f0ac2244/proxy" \  -H "Content-Type: application/json" \  -d '{    "proxy_url": "http://user:pass@10.0.0.5:8080"  }'
{  "success": true,  "scope": "device",  "device_id": "ad14fdc2-b86a-42be-ba69-1107f0ac2244",  "proxy_url": "http://user:***@10.0.0.5:8080",  "reconnect": "connected"}
{  "success": false,  "error": "validation failed",  "error_code": "VALIDATION_ERROR",  "timestamp": "2026-06-15T12:00:00Z"}
{  "success": false,  "error": "validation failed",  "error_code": "VALIDATION_ERROR",  "timestamp": "2026-06-15T12:00:00Z"}
{  "success": false,  "error": "validation failed",  "error_code": "VALIDATION_ERROR",  "timestamp": "2026-06-15T12:00:00Z"}
{  "success": false,  "error": "validation failed",  "error_code": "VALIDATION_ERROR",  "timestamp": "2026-06-15T12:00:00Z"}

Get the tenant proxy configuration GET

Returns the tenant-wide proxy (applied to every instance that has no override) together with every per-instance override. Passwords in proxy URLs are masked.

Set the tenant-wide proxy PUT

Sets the proxy used by every instance of the tenant that does not have its own override. whatsmeow reads the proxy only when it dials, so the tenant's online instances are reconnected in the background to apply it immediately; offline instances pick it up on their next reconnect.