Waalfa.

Documentation

Everything you need to integrate and use the WhatsApp Business API

Try API Playground Get Support

Getting Started

Quick start guide to set up your first integration in minutes.

1. Create Your Account

Sign up for a Waalfa account and verify your email address.

Visit: https://waalfa.com/register

2. Connect WhatsApp Business

Link your WhatsApp Business Account through Meta Business Manager.

  • Go to Settings → WhatsApp Integration
  • Click "Connect WhatsApp Business"
  • Follow the Meta authentication flow
  • Select your business phone number

3. Generate API Key

Create your first API key for authentication.

# Navigate to Settings → API Keys
# Click "Generate New Key"
# Copy and store securely

4. Send Your First Message

curl -X POST "https://api.waalfa.com/api/v1/messages/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"to": "1234567890",
"template_name": "hello_world",
"templateParams": ["John Doe"]
}'

API Reference

Complete API documentation with examples and response formats.

Base URL

https://api.waalfa.com/api/v1

Common Endpoints

POST /messages/send Send Message

Send template messages to WhatsApp users. Recipient name is required and contacts are saved uniquely per WhatsApp account + phone.

GET /templates List Templates

Retrieve all approved message templates

POST /broadcasts Create Broadcast

Send bulk messages to contact segments

Authentication

Learn how to authenticate API requests securely.

Bearer Token Authentication

All API requests require a valid API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Security Best Practices

  • Never expose API keys in client-side code
  • Use environment variables to store keys
  • Rotate keys regularly (every 90 days recommended)
  • Use different keys for development and production
  • Implement IP whitelisting for additional security

Rate Limiting

API requests are limited based on your plan:

100/min
Starter Plan
500/min
Professional
Unlimited
Enterprise

Webhooks

Set up real-time event notifications for message delivery, reads, and more.

Webhook Events

message.delivered

Triggered when a message is successfully delivered

message.read

Triggered when a message is read by the recipient

message.received

Triggered when you receive an incoming message

message.failed

Triggered when message delivery fails

Setup Instructions

  1. Go to Settings → Webhooks in your dashboard
  2. Enter your webhook URL (must be HTTPS)
  3. Select events you want to receive
  4. Save and verify the webhook

Example Payload

{
"event": "message.delivered",
"timestamp": "2024-12-29T07:25:00Z",
"data": {
"message_id": "msg_123456",
"to": "1234567890",
"status": "delivered"
}
}

Message Templates

Create and manage WhatsApp-approved message templates.

Template Categories

UTILITY

Account updates, order confirmations

MARKETING

Promotional offers, announcements

AUTHENTICATION

OTP codes, verification

Approval Guidelines

  • Use clear, concise language
  • Avoid promotional content in utility templates
  • Include proper opt-out instructions for marketing
  • Use variables for personalization (1, 2)
  • Follow WhatsApp's content policy

Example Template

Order Confirmation

Hi 1, your order #2 has been confirmed! Expected delivery: 3. Track your order: 4

Category: UTILITY | Variables: 4

Best Practices

Tips for optimal performance and compliance.

Message Delivery

  • Always obtain user consent before messaging
  • Respect user opt-out requests immediately
  • Send messages during business hours (9 AM - 9 PM local time)
  • Avoid sending duplicate messages
  • Use template messages for first contact

Performance Optimization

  • Implement retry logic with exponential backoff
  • Cache template data to reduce API calls
  • Use batch endpoints for bulk operations
  • Monitor webhook delivery and implement fallbacks
  • Set appropriate timeout values (30s recommended)

Compliance

⚠️ Important

Violating WhatsApp's policies can result in account suspension. Always follow the WhatsApp Business Policy and Commerce Policy guidelines.

Quality Rating

Maintain a high-quality rating to ensure message deliverability:

High
Excellent delivery
Medium
Good delivery
Low
Limited delivery