curl --request POST \
--url https://api.wppfy.com/instance/proxy \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"mode": "custom",
"proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080",
"proxy_fallback": "internal"
}
'{
"details": "Proxy configurado",
"proxy": {
"mode": "custom",
"effective_mode": "custom",
"fallback": {
"active": false,
"reason": "",
"since": 0
},
"proxy_url": "http://***:***@proxy-do-cliente.example:8080",
"proxy_fallback": "internal",
"managed": false,
"last_test_at": 0,
"last_test_error": "",
"validation_error": false
},
"restart_requested": true
}Configure or change the proxy
Explicitly sets one of the three accepted states:
mode=custom: uses your own proxy provided inproxy_url;mode=internal: uses the internal infrastructure; ormode=none: direct connection, allowed only withconfirm_no_proxy=true.
Important: POST /instance/proxy confirms that the configuration was saved, not that the proxy has already been proven to be in use.
The main operational validation happens in the instance’s next real connection cycle.
In practical terms:
200 OKhere = configuration persisted successfully;- real connectivity failures may appear later; and
- to observe the real state, query
GET /instance/proxyand read:effective_modeeffective_detailfallback.activelast_test_errorvalidation_error
When mode=custom, you can also define the fallback via proxy_fallback:
internal: tries the internal infrastructure and, if it still fails, may use direct as a last resort;never: does not use a fallback; or- a fallback proxy URL controlled by the client.
When mode=internal, rotate_now: true immediately replaces the persisted internal proxy.
If more than one internal source is available, the platform picks another source without exposing the provider.
If there is only one source, it only swaps the proxy/IP within that source.
Protocols accepted in custom proxy URLs:
http://usuario:senha@host:portahttps://usuario:senha@host:portasocks5://usuario:senha@host:portasocks5h://usuario:senha@host:porta
The generic socks:// scheme is not accepted. For SOCKS proxies, use socks5:// or socks5h://.
curl --request POST \
--url https://api.wppfy.com/instance/proxy \
--header 'Content-Type: application/json' \
--header 'token: <api-key>' \
--data '
{
"mode": "custom",
"proxy_url": "http://usuario:senha@proxy-do-cliente.example:8080",
"proxy_fallback": "internal"
}
'{
"details": "Proxy configurado",
"proxy": {
"mode": "custom",
"effective_mode": "custom",
"fallback": {
"active": false,
"reason": "",
"since": 0
},
"proxy_url": "http://***:***@proxy-do-cliente.example:8080",
"proxy_fallback": "internal",
"managed": false,
"last_test_at": 0,
"last_test_error": "",
"validation_error": false
},
"restart_requested": true
}Authorizations
Body
Canonical field for defining the proxy strategy.
custom, internal, none Required when mode=custom.
Accepted protocols: http://, https://, socks5://, and socks5h://.
The generic socks:// scheme is not supported; use socks5:// or socks5h://.
"http://usuario:senha@ip:porta"
Fallback policy for mode=custom.
Accepts internal, never, or a fallback proxy URL using http://, https://, socks5://, or socks5h://.
Required when mode=none.
When true with mode=internal, immediately switches the persisted internal proxy without exposing the provider used.
ISO alpha-2 country used to validate the managed proxy egress. Use only with mode=internal.
"br"
State/province of the geographic target returned by the city catalog.
"sp"
City slug returned by GET /proxy-managed/cities.
"campinas"