Best Practices
Recommended patterns for reliable, scalable WhatsApp automation.
Building reliable WhatsApp automation requires attention to message delivery, error handling, rate limiting, anti-ban measures, and compliance. These best practices help you build production-grade workflows.
Always implement message queuing on your side. WAStack queues messages internally, but having your own queue ensures messages aren't lost during network issues or API downtime.
Handle errors gracefully. The API returns detailed error responses with codes, messages, and suggestions. Implement retry logic for 5xx errors and exponential backoff for 429 rate limit errors.
Respect rate limits. Monitor X-RateLimit headers and adjust your request rate proactively. Don't wait for 429 responses - throttle before hitting limits.
Use timezone-aware scheduling. When scheduling messages, specify the recipient's timezone using the 'zone' parameter (IANA format like 'America/New_York'). WAStack enforces quiet hours (10 PM - 8 AM local time) to prevent messages during sleeping hours and reduce spam reports.
Personalize messages to avoid spam filters. Use the {name} placeholder in templates to customize each message. Sending identical messages to large batches is a primary trigger for WhatsApp spam detection.
Use staggered delays for bulk sends. Set minimum and maximum delays (5-30 seconds recommended) between messages to simulate natural human behavior.
Keep sessions healthy. Monitor session status via webhooks and the API. Implement alerts for disconnections and have a recovery plan ready.
Follow WhatsApp's terms of service. Only message opted-in users. Include opt-out mechanisms. Respect sending windows. Review WhatsApp's terms for your use case.
Monitor plan quotas. All endpoints enforce limits (messages_limit, contact_limit, device_limit, template_limit). When a quota is reached, the API returns 403 Forbidden. Use -1 for unlimited quotas on eligible plans.
Message Queuing
Implement your own message queue alongside WAStack's internal queue. This ensures messages survive network issues and API downtime.
Error Handling
Handle API errors with retries for 5xx, exponential backoff for 429, and immediate failure for 4xx client errors. Log all errors for debugging.
Rate Limiting
Monitor X-RateLimit headers and throttle proactively. Implement token bucket or sliding window rate limiting in your application.
Anti-Ban Measures
Use timezone-aware scheduling (10 PM - 8 AM quiet hours). Personalize messages with {name} to avoid spam detection. Set staggered delays (5-30s) for bulk sends.
Plan Quotas
All endpoints enforce limits (messages_limit, contact_limit, device_limit, template_limit). Returns 403 when exceeded. Use -1 for unlimited on eligible plans.
Compliance
Only message opted-in users. Include opt-out mechanisms. Respect sending windows. Review WhatsApp's terms for your use case.
Code Examples
async function sendWithRetry(api, payload, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await api.messages.send(payload);
} catch (error) {
if (error.status === 429) {
const wait = Math.pow(2, i) * 1000;
await new Promise(r => setTimeout(r, wait));
continue;
}
throw error;
}
}
throw new Error("Max retries exceeded");
}Ready to implement?
Start building with WAStack APIs. Connect your WhatsApp in under 5 minutes.
Start FreeFrequently asked questions
Common questions about best practices.
Browse all documentation
From getting started to advanced API patterns, find everything you need to build WhatsApp automation.