Wazzap AI API Documentation - Sending WhatsApp Messages

Table of Contents

1. Introduction
2. Prerequisites and API Key Generation
3. Authentication
4. Sending Messages
5. Disabling AI Automatic Response
6. Tracking and Statistics
7. Rate Limiting and Queue
8. Code Examples
9. Error Handling
10. Best Practices

---

Introduction

This API allows you to send WhatsApp messages programmatically using an API key.

Main Features

• Secure authentication via API key
• Text message sending
• Rate limiting: 1230 requests/minute
• Automatic WhatsApp account detection
• International phone number format support

---

Prerequisites and API Key Generation

Step 1: Have a Wazzap AI Premium Account

You or your users must have an active Premium subscription on Wazzap AI.

Step 2: Create an AI Agent

1. Log in to your Wazzap AI account
2. Create a new AI agent from your dashboard
3. Configure your agent according to your needs

Step 3: Connect Your WhatsApp Number

1. From your agent's page, connect your WhatsApp number
2. Scan the QR Code with WhatsApp
3. Wait for the connection to be established

Step 4: Generate Your API Key

1. Go to your account Settings
2. Access the API Keys section
3. Click on Generate a new key
4. Give your key a name (e.g., "Maketou Integration")
5. Select the WhatsApp agent to associate
6. Copy the key immediately (it will not be displayed again)

⚠️ Important: Keep this key secure, it will only be displayed once!

---

Authentication

All requests require an Authorization header with Bearer format:

Authorization: Bearer wz_your_complete_api_key

Key format: wz_xxxxxxxxxxxxxxxxxxxxxx (32 characters after the prefix)

---

Sending Messages

Endpoint

POST https://api21.wazzap.ai/api/wazzap/send-message

Required Headers

Authorization: Bearer wz_your_api_key
Content-Type: application/json

Request Body

{
  "phoneNumber": "+3300000000",
  "message": "Your message here",
  "disableAiResponse": false
}

Parameters

Parameter	Type	Required	Description	Example
phoneNumber	string	Yes	Recipient's number (international format)	"+3300000000"
message	string	Yes	Text message to send	"Hello!"
disableAiResponse	boolean	No	Disables AI automatic response (default: false)	true

Success Response (200)

{
  "success": true,
  "code": 200,
  "message": "Message sent successfully",
  "data": {
    "messageId": "3EB0XXX",
    "phoneNumber": "+3300000000",
    "formattedPhoneNumber": "3300000000",
    "executionTime": 234,
    "provider": "v1",
    "agentId": "agent_123",
    "organizationId": "org_456",
    "aiResponseDisabled": false
  }
}

Error Response (4xx/5xx)

{
  "success": false,
  "code": 400,
  "errorCode": "MISSING_PHONE_NUMBER",
  "message": "The 'phoneNumber' parameter is required"
}

---

Disabling AI Automatic Response

What is disableAiResponse?

The disableAiResponse parameter allows you to disable the automatic conversation handling by the AI agent connected to your WhatsApp account for a specific contact. When activated (true), the contact switches to human mode, which means:

• Your message will be sent normally
• The contact will be created and linked to your agent
• The AI will NOT automatically respond to this contact's messages
• You can respond manually from your Wazzap AI dashboard or from your WhatsApp on your smartphone.

Typical Use Cases

1. VIP Support or Escalation

// Important client requiring human attention
await sendMessage(
  '+3300000000',
  'Hello Mr. Smith, an advisor will respond to you shortly.',
  { disableAiResponse: true }
);

2. One-way Notifications Without Expecting Response

// Delivery notification without requiring AI response
await sendMessage(
  '+33698765432',
  'Your package has arrived at the pickup point.',
  { disableAiResponse: true }
);

3. Personalized Marketing Campaigns

// Send a special offer without activating AI
const clients = ['+33601...', '+33602...'];
for (const client of clients) {
  await sendMessage(
    client,
    'Exclusive offer: -20% this weekend!',
    { disableAiResponse: true }
  );
}

Complete Example

const response = await fetch('https://api21.wazzap.ai/api/wazzap/send-message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wz_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: '+3300000000',
    message: 'Hello, a human will respond to you quickly.',
    disableAiResponse: true  // AI will not automatically respond
  })
});

const data = await response.json();
console.log('AI Response Disabled:', data.data.aiResponseDisabled); // true

How to Reactivate AI for a Contact?

To reactivate automatic AI response for a contact:

1. Log in to your Wazzap AI dashboard
2. Access the contact's conversation
3. Click on the "Reactivate AI" button or similar

Or simply send a new message without the disableAiResponse parameter (or with false):

await sendMessage(
  '+3300000000',
  'AI is now reactivated',
  { disableAiResponse: false }  // AI will respond normally
);

Important to Know

• The parameter applies per contact and persists until reactivation
• A contact with disableAiResponse: true will be marked as "Human mode" in your dashboard
• You can always respond manually via the dashboard
• AI remains active for all other contacts

---

Tracking and Statistics

Statistics Endpoint

Check your API key's performance in real-time:

GET https://api21.wazzap.ai/api/wazzap/stats
Authorization: Bearer wz_your_api_key

Response

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "cm9xxx...",
      "name": "Production API",
      "agentId": "cm9yyy..."
    },
    "stats": {
      "totalRequests": 1250,
      "successRequests": 1200,
      "failedRequests": 50,
      "successRate": 96.0
    },
    "queue": {
      "processing": 2,
      "pending": 5,
      "maxConcurrent": 4
    },
    "rateLimit": {
      "limit": 100,
      "current": 45,
      "remaining": 55,
      "resetAt": "2025-10-15T15:30:00.000Z"
    },
    "recentRequests": [
      {
        "id": "req_xxx",
        "status": "COMPLETED",
        "statusCode": 200,
        "duration": 234,
        "provider": "v1",
        "startedAt": "2025-10-15T15:25:00.000Z",
        "completedAt": "2025-10-15T15:25:00.234Z"
      }
      // ... 9 other recent requests
    ]
  }
}

Available Metrics

Metric	Description
totalRequests	Total number of requests made
successRequests	Number of successful requests
failedRequests	Number of failed requests
successRate	Success rate as percentage
queue.processing	Number of requests being processed
queue.pending	Number of requests waiting
rateLimit.current	Number of requests in current window
rateLimit.remaining	Number of requests remaining before limit

Monitoring Example

async function monitorAPI() {
  const response = await fetch('https://api21.wazzap.ai/api/wazzap/stats', {
    headers: {
      'Authorization': 'Bearer wz_your_api_key'
    }
  });

  const { data } = await response.json();
  
  console.log(`Success rate: ${data.stats.successRate}%`);
  console.log(`Queue: ${data.queue.processing}/${data.queue.maxConcurrent} processing, ${data.queue.pending} pending`);
  console.log(`Rate limit: ${data.rateLimit.remaining}/${data.rateLimit.limit} remaining`);
  
  // Alert if issue detected
  if (data.stats.successRate < 90) {
    console.warn('Low success rate - check WhatsApp connection');
  }
}

// Monitor every 30 seconds
setInterval(monitorAPI, 30000);

---

Rate Limiting and Queue

Automatic Queue System

To ensure stability, each API key has an intelligent queue that processes maximum 4 requests in parallel.

How does it work?

Your requests → [Queue] → [4 processing slots] → WhatsApp Sending
                            ↑
                    Maximum 4 simultaneous
                    Others wait

Rate Limiting

Each API key has configurable limits:

Parameter	Default	Description
rateLimit	100	Requests per window
rateLimitWindow	60s	Window duration

By default: 100 requests per minute

Handling Exceeded Limits

If you exceed the limit:

{
  "success": false,
  "code": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait.",
  "rateLimit": {
    "limit": 100,
    "remaining": 0,
    "reset": "2025-10-15T15:30:00.000Z"
  }
}

Best Practices to Avoid Rate Limiting

// 1. Check before bulk sending
async function sendIfPossible(phoneNumber, message) {
  const stats = await getStats();
  
  if (stats.data.rateLimit.remaining < 5) {
    const resetTime = new Date(stats.data.rateLimit.resetAt);
    const waitTime = resetTime.getTime() - Date.now();
    console.log(`Waiting ${Math.ceil(waitTime/1000)}s...`);
    await new Promise(r => setTimeout(r, waitTime));
  }
  
  return await sendMessage(phoneNumber, message);
}

// 2. Automatically space out sends
async function sendWithSpacing(contacts, intervalMs = 700) {
  for (const contact of contacts) {
    await sendMessage(contact.phone, contact.message);
    await new Promise(r => setTimeout(r, intervalMs));
  }
}

Increasing Your Rate Limit

To increase your rate limit, contact your administrator or upgrade to a higher plan.

---

Code Examples

Simple Message Sending

---

Error Handling

Error Codes

HTTP Code	Error Code	Description	Solution
200	-	Success	-
400	MISSING_PHONE_NUMBER	Missing number	Add phoneNumber
400	MISSING_MESSAGE	Missing message	Add message
400	NO_WHATSAPP_PROVIDER	No WhatsApp connected	Connect WhatsApp
401	API_KEY_MISSING	Missing key	Add Authorization header
401	API_KEY_INVALID_OR_EXPIRED	Invalid key	Verify key
403	NO_WHATSAPP_ACCOUNT_CONNECTED	WhatsApp not connected	Reconnect WhatsApp
404	AGENT_NOT_FOUND	Agent not found	Verify agent
429	-	Too many requests	Wait 1 minute
500	MESSAGE_SEND_ERROR	Server error	Retry

Error Examples

Missing API Key

{
  "success": false,
  "code": 401,
  "errorCode": "API_KEY_MISSING",
  "message": "API key missing. Use the 'Authorization: Bearer YOUR_API_KEY' header"
}

Missing Phone Number

{
  "success": false,
  "code": 400,
  "errorCode": "MISSING_PHONE_NUMBER",
  "message": "The 'phoneNumber' parameter is required"
}

WhatsApp Account Not Connected

{
  "success": false,
  "code": 403,
  "errorCode": "NO_WHATSAPP_ACCOUNT_CONNECTED",
  "message": "No WhatsApp account connected for this agent"
}

---

Best Practices

1. Security

Do:

• Store the key in environment variables
• Never expose the key on client-side
• Use HTTPS only
• Regenerate the key if compromised

Don't:

• Hardcode the key in code
• Commit the key to Git
• Share the key publicly

Secure Example:

// .env
WAZZAP_AI_API_KEY=wz_your_api_key
WAZZAP_AI_API_URL=https://your-domain.wazzap.ai

// config.js
require('dotenv').config();

module.exports = {
  apiKey: process.env.WAZZAP_AI_API_KEY,
  apiUrl: process.env.WAZZAP_AI_API_URL
};

2. Rate Limiting

• Maximum: 1230 requests per minute
• Implement a queue for bulk sends

3. Data Validation

// Validate number
function validateNumber(phoneNumber) {
  const cleaned = phoneNumber.replace(/[^\d+]/g, '');
  if (!/^\+?\d{10,15}$/.test(cleaned)) {
    throw new Error('Invalid number');
  }
  return cleaned.startsWith('+') ? cleaned : '+' + cleaned;
}

// Validate message
function validateMessage(message) {
  if (!message || typeof message !== 'string') {
    throw new Error('Invalid message');
  }
  if (message.length > 4096) {
    throw new Error('Message too long (max 4096 characters)');
  }
  return message.trim();
}

---

📚 Use Cases

Sending Personalized Notifications

const clients = [
  { name: 'John Smith', phone: '+3300000000', order: '#12345' },
  { name: 'Mary Johnson', phone: '+33698765432', order: '#12346' }
];

async function sendNotifications(clients) {
  for (const client of clients) {
    const message = `
Hello ${client.name},

Your order ${client.order} has been confirmed.

Thank you!
    `.trim();
    
    await sendMessage(client.phone, message);
    await new Promise(r => setTimeout(r, 3000)); // Wait 3s
  }
}

---

Support

Common Issues

Message doesn't arrive:

1. Verify the number is correct
2. Verify WhatsApp number is connected in Wazzap AI
3. Test with another number

"Rate limit exceeded":

1. Reduce sending frequency
2. Wait 1 minute
3. Implement a queue

Invalid API key:

1. Verify you copied the complete key
2. Verify the key hasn't expired
3. Regenerate a new key if necessary

---

Contact

For any questions:

• First consult this documentation
• Contact us at contact@wazzap.ai

---