Handling Conditional Response Schemas in Synchronous WhatsApp API Integrations

When building integrations that rely on external identity or presence signals, the contract between your application and the provider is everything. In many APIs, you might expect a static response object. However, when working with the WALookup API, the response schema is polymorphic—it changes based on the service_type you request.

Understanding how to handle these conditional schemas is critical for building robust, error-tolerant integration layers.

The Schema-Switch Pattern

The POST /api/v1/check endpoint is a synchronous, single-number checker. Because it supports three distinct check types—ws, ws_avatar, and ws_business—the fields returned in the data object vary significantly.

• ws: Returns the registered status.
• ws_avatar: Includes registered, avatar (boolean), and avatar_url (string, conditional on availability).
• ws_business: Includes registered and business (boolean).

If your application logic assumes a field like avatar_url will always be present, you will encounter runtime errors when switching between service types.

Step 1: Normalize Your Input

Before calling the API, ensure your input is formatted correctly. The API requires E.164-formatted phone numbers. Using an incorrect format will lead to failed checks, which are automatically refunded, but still represent a wasted round-trip in your application flow.

Step 2: Implement a Polymorphic Adapter

Instead of parsing the raw JSON response directly in your business logic, implement an adapter layer. This layer should inspect the service_type field and map the response to a unified internal model.

Conceptual Implementation

// Conceptual: Adapter pattern for polymorphic response handling
function processCheckResult(response) {
 const { data } = response;
 const baseResult = {
 isRegistered: data.registered,
 type: data.service_type
 };

 // Handle conditional fields based on service_type
 if (data.service_type === 'ws_avatar') {
 return {
 ...baseResult,
 hasAvatar: data.avatar,
 avatarUrl: data.avatar_url || null // Handle missing/empty URL
 };
 }

 if (data.service_type === 'ws_business') {
 return {
 ...baseResult,
 isBusiness: data.business
 };
 }

 return baseResult;
}

Step 3: Handling Missing Fields Safely

Notice that avatar_url is only present when the upstream service supplies one. In your code, always treat these fields as optional. Use null-coalescing operators or safe-navigation patterns to ensure your application doesn't crash if a field is omitted.

Error Handling and Idempotency

Because the API is synchronous, your error handling strategy should focus on the immediate HTTP cycle.

1. Always use your server-side API Key: Never expose your X-API-Key in client-side code, as anyone with the key can spend your balance.
2. Check the Balance: Use GET /api/v1/balance before initiating large batch operations to prevent mid-process failures.
3. Automatic Refunds: Remember that failed or undetermined checks are automatically refunded. Your error handling should account for the fact that a "failed" result is a standard part of the lifecycle, not necessarily a system-level exception.

Conclusion

By treating the response schema as conditional and implementing a dedicated adapter layer, you can safely leverage the flexibility of the ws, ws_avatar, and ws_business service types. This approach keeps your core business logic clean and ensures that your application remains resilient as you scale your integration.

For more details on the specific request structure, visit the official API documentation.

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