How to Build a Pre-Flight WhatsApp Validation Layer

#whatsapp #api #backend #tutorial

When building communication-heavy applications, sending messages to invalid numbers is a quick way to degrade your delivery metrics and waste resources. A robust integration strategy involves a "pre-flight" check to verify if a contact is actually registered on WhatsApp before triggering your primary messaging workflow.

In this guide, we will implement a validation layer using the WALookup API, which provides a synchronous check for registration, avatar availability, and business account status.

1. Normalization: The E.164 Requirement

Before hitting any API, your application must ensure phone numbers are in E.164 format (e.g., +14155552671). Relying on raw user input often leads to validation errors. Use a standard library—similar to the modular pattern found in lightweight form validation packages—to strip non-numeric characters and ensure the country code is present.

2. Choosing Your Service Type

The /api/v1/check endpoint is your primary interface. It accepts three distinct service types, allowing you to tailor the data returned to your specific business logic:

ws: Confirms basic registration.
ws_avatar: Returns registration status plus avatar availability and URL.
ws_business: Returns registration status and confirms if the number is a business account.

3. Implementation Pattern

Since the API is synchronous, you receive the result in the same HTTP response. This makes it ideal for real-time form validation or gatekeeping a messaging queue.

Example Request

curl -X POST "https://walookup.com/api/v1/check" \
 -H "X-API-Key: wac_your_api_key" \
 -H "Content-Type: application/json" \
 -d '{
 "service_type": "ws_avatar",
 "identifier": "+14155552671"
 }'

Handling the Response

Every response follows a consistent envelope. Use the data.registered boolean as your primary signal. Note that avatar or business flags being false does not necessarily mean the number is unregistered—always rely on the registered field for that status.

{
 "code": 0,
 "msg": "ok",
 "data": {
 "id": 123,
 "identifier": "+14155552671",
 "registered": true,
 "transaction_id": "chk_example123",
 "status": "success",
 "service_type": "ws_avatar",
 "avatar": true,
 "avatar_url": "https://...",
 "charged_amount_micros": 4000
 }
}

4. Operational Considerations

Concurrency: The API supports up to three concurrent checks. If you receive a 42901 error, your application should pause briefly before retrying, as this indicates all slots are occupied.
Billing: Failed or undetermined checks are refunded automatically. You are only billed for successful registration signals.
Scope: Remember that these checks provide account-presence signals. They do not confirm online status, message history, or contact consent.

Conclusion

By integrating a synchronous pre-flight check, you can filter out invalid numbers at the point of entry. This keeps your downstream messaging clean and ensures you are only interacting with active WhatsApp accounts. For further details on managing your API keys and reviewing your spend, visit https://walookup.com.

This article was drafted with AI assistance and reviewed before publishing.

DEV Community