Is your feature request related to a problem? Please describe.
I'm always frustrated when sending a message to an invalid or non-existent WhatsApp number returns HTTP 201 with ack: 1 (SERVER), giving a false sense of success. The message is silently never delivered, with no error or warning in the response — making it very hard to detect and handle the failure in integrated systems.
Describe the solution you'd like
Add an optional checkNumberExists parameter to the send endpoints (sendText, sendImage, etc.). When set to true, WAHA internally runs the existing check-exists logic before processing the send. If the number is not registered on WhatsApp, the request should fail immediately with a clear error instead of a silent false positive:
POST /api/{session}/sendText
{
"chatId": "55000000000000@c.us",
"text": "Hello!",
"checkNumberExists": true
}Expected error response:
HTTP 422 Unprocessable Entity
{
"error": "PHONE_NOT_ON_WHATSAPP",
"message": "The number 55000000000000 is not registered on WhatsApp."
}Optionally, allow this to be enabled globally at the session level so every send request is validated by default:
{
"name": "my-session",
"config": {
"send": {
"checkNumberExists": true
}
}
}The default value should remain false to preserve full backward compatibility.
Describe alternatives you've considered
The current workaround is to call GET /api/{session}/contacts/check-exists before every send request. This works, but it doubles the number of API calls, adds latency, increases integration complexity, and is easy to forget — especially when WAHA is consumed by third-party tools like Chatwoot or n8n that don't implement this guard themselves.
Additional context
This behavior is not a WAHA bug — it is inherited from WhatsApp's own architecture. Meta's Cloud API also does not reject sends upfront for invalid numbers; the failure is only reported asynchronously via webhook (documented as error 131026 - Message Undeliverable). Because the validation cannot happen at the WhatsApp protocol level, it must be handled at the WAHA layer.
The check-exists endpoint already proves this check is technically feasible. This request simply integrates that existing mechanism into the send flow as an opt-in option.
Is your feature request related to a problem? Please describe.
I'm always frustrated when sending a message to an invalid or non-existent WhatsApp number returns
HTTP 201withack: 1 (SERVER), giving a false sense of success. The message is silently never delivered, with no error or warning in the response — making it very hard to detect and handle the failure in integrated systems.Describe the solution you'd like
Add an optional
checkNumberExistsparameter to the send endpoints (sendText,sendImage, etc.). When set totrue, WAHA internally runs the existingcheck-existslogic before processing the send. If the number is not registered on WhatsApp, the request should fail immediately with a clear error instead of a silent false positive:Expected error response:
Optionally, allow this to be enabled globally at the session level so every send request is validated by default:
{ "name": "my-session", "config": { "send": { "checkNumberExists": true } } }The default value should remain
falseto preserve full backward compatibility.Describe alternatives you've considered
The current workaround is to call
GET /api/{session}/contacts/check-existsbefore every send request. This works, but it doubles the number of API calls, adds latency, increases integration complexity, and is easy to forget — especially when WAHA is consumed by third-party tools like Chatwoot or n8n that don't implement this guard themselves.Additional context
This behavior is not a WAHA bug — it is inherited from WhatsApp's own architecture. Meta's Cloud API also does not reject sends upfront for invalid numbers; the failure is only reported asynchronously via webhook (documented as error
131026 - Message Undeliverable). Because the validation cannot happen at the WhatsApp protocol level, it must be handled at the WAHA layer.The
check-existsendpoint already proves this check is technically feasible. This request simply integrates that existing mechanism into the send flow as an opt-in option.