# Lushai.dev WAPI — WhatsApp REST API Gateway & Automation Platform

> Lushai.dev WAPI (WhatsApp REST API Gateway) is an enterprise multi-device WhatsApp automation engine powered by WAPI Engine Enterprise Gateway and Supabase. It enables developers, SaaS applications, and businesses to programmatically send WhatsApp messages, media, stickers, polls, product catalogs, interactive buttons, webhooks, and manage multi-device WhatsApp accounts via simple HTTP REST API requests.

## Key Features & Capabilities
- **REST Messaging API**: Send text, images, videos, PDFs, WebP stickers, polls, VCards, GPS locations, product catalogs, and interactive buttons.
- **Multi-Device Support**: Connect multiple WhatsApp numbers using 8-digit instant pairing codes or QR code scanning.
- **Webhooks System**: Receive real-time incoming WhatsApp messages, delivery receipts, and connection state updates via HTTP Webhook POST requests.
- **Quota & Rate Limits**: Automated rate-limiting, prioritized delay queues, bulk broadcast campaign scheduler, and auto-responder bot engines.
- **Supabase Integration**: Permanent cloud data storage for user accounts, API keys, site settings, and media assets.

## Quick Reference Links
- Full Detailed API Reference: https://wapi.lushai.dev/llms-full.txt
- Interactive Developer Portal & Docs: https://wapi.lushai.dev/api-docs
- Public Site Settings API: https://wapi.lushai.dev/api/public/site-settings
- Platform Terms & Pricing: https://wapi.lushai.dev/pricing
- Open Source / GitHub Repository: https://github.com/ceeprolific/WhatsApp

## Base API Endpoint & Authentication
All API endpoints use HTTP POST/GET requests and return JSON.

- **Base URL**: `https://wapi.lushai.dev/api`
- **Authentication Header**: `Authorization: Bearer <YOUR_API_KEY>` (or JWT Session Cookie for web dashboard)
- **Content-Type**: `application/json`

---

## Core API Endpoints

### 1. Send Text Message
- **Endpoint**: `POST /api/send-message`
- **Description**: Sends a plain text message to a single phone number or WhatsApp group.
- **Request Body**:
```json
{
  "number": "919862123456",
  "message": "Hello from Lushai.dev WAPI Engine!"
}
```

### 2. Send Media File (Image, Video, Document, Audio)
- **Endpoint**: `POST /api/send-media`
- **Description**: Sends an image, video, PDF document, or audio file via public URL.
- **Request Body**:
```json
{
  "number": "919862123456",
  "mediaUrl": "https://wapi.lushai.dev/assets/wapi-analytics-report.jpg",
  "caption": "Project status update report",
  "type": "image"
}
```

### 3. Send Interactive Poll Message
- **Endpoint**: `POST /api/send-poll`
- **Description**: Sends an interactive voting poll with single or multi-choice options.
- **Request Body**:
```json
{
  "number": "919862123456",
  "question": "Which programming language do you prefer?",
  "options": ["TypeScript", "Python", "Go", "Rust"],
  "selectableCount": 1
}
```

### 4. Send Product Catalog Card
- **Endpoint**: `POST /api/send-product`
- **Description**: Sends an e-commerce product catalog card with price, currency, image, and description.
- **Request Body**:
```json
{
  "number": "919862123456",
  "title": "Velocity Elite Pro Athletic Sneaker",
  "description": "Premium athletic running sneakers with responsive cushioning",
  "price": 4999,
  "currency": "INR",
  "imageUrl": "https://wapi.lushai.dev/assets/wapi-product-card.jpg"
}
```

### 5. Send WebP Sticker
- **Endpoint**: `POST /api/send-sticker`
- **Description**: Sends an animated or static WebP sticker.
- **Request Body**:
```json
{
  "number": "919862123456",
  "stickerUrl": "https://wapi.lushai.dev/assets/wapi-sticker-mascot.png"
}
```

### 6. Send Interactive Buttons
- **Endpoint**: `POST /api/send-button`
- **Description**: Sends quick-reply interactive action buttons.
- **Request Body**:
```json
{
  "number": "919862123456",
  "title": "Order Confirmation",
  "body": "Your order #1042 has been shipped. Would you like to track it?",
  "footer": "Lushai.dev WAPI",
  "buttons": [
    { "id": "track_yes", "text": "Track Package" },
    { "id": "support_help", "text": "Contact Support" }
  ]
}
```

### 7. Send Interactive Selection List
- **Endpoint**: `POST /api/send-list`
- **Description**: Sends an interactive popup menu list with sectioned rows.
- **Request Body**:
```json
{
  "number": "919862123456",
  "title": "Customer Care Menu",
  "body": "Select a category from the menu below:",
  "buttonText": "Open Menu",
  "sections": [
    {
      "title": "Services",
      "rows": [
        { "id": "srv_api", "title": "API Gateway", "description": "REST API Integration" },
        { "id": "srv_bot", "title": "Auto Responder", "description": "Smart keyword bot" }
      ]
    }
  ]
}
```

### 8. Send GPS Location
- **Endpoint**: `POST /api/send-location`
- **Description**: Sends a map location pin with latitude, longitude, and address name.
- **Request Body**:
```json
{
  "number": "919862123456",
  "degreesLatitude": 23.7271,
  "degreesLongitude": 92.7176,
  "name": "Lushai.dev HQ",
  "address": "Aizawl, Mizoram, India"
}
```

### 9. Send VCard Contact Card
- **Endpoint**: `POST /api/send-vcard`
- **Description**: Sends a contact business card with name, phone number, and organization.
- **Request Body**:
```json
{
  "number": "919862123456",
  "contactName": "Zosangzuala",
  "contactNumber": "+919862123456",
  "organization": "Lushai.dev Engineering"
}
```

### 10. Generate WhatsApp Pairing Code / QR Code
- **Endpoint**: `POST /api/session/generate-qr`
- **Description**: Generates an 8-digit instant pairing code or QR code string to connect a WhatsApp phone instance.
- **Request Body**:
```json
{
  "phoneNumber": "919862123456"
}
```

### 11. Get Device Connection Status
- **Endpoint**: `GET /api/session/status`
- **Description**: Checks current WhatsApp connection state (`connected`, `connecting`, or `disconnected`).

### 12. Register Webhook Endpoint
- **Endpoint**: `POST /api/webhook/set`
- **Description**: Registers your HTTP server URL to receive real-time incoming WhatsApp messages and status changes.
- **Request Body**:
```json
{
  "url": "https://your-domain.com/api/whatsapp-webhook",
  "events": ["message.received", "status.change"]
}
```

---

## Standard API Response Format

### Success Response (`HTTP 200 OK`)
```json
{
  "status": true,
  "message": "Message sent successfully",
  "messageId": "BAE59A83F1234567"
}
```

### Error Response (`HTTP 400 Bad Request` or `HTTP 500 Server Error`)
```json
{
  "status": false,
  "error": "Invalid phone number format or WhatsApp device disconnected"
}
```

---

## Complete cURL Code Example

```bash
curl -X POST https://wapi.lushai.dev/api/send-message \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "919862123456",
    "message": "Hello from Lushai.dev WAPI Engine!"
  }'
```

## Complete Node.js / TypeScript Example

```typescript
import axios from 'axios';

async function sendWhatsAppMessage() {
  const response = await axios.post(
    'https://wapi.lushai.dev/api/send-message',
    {
      number: '919862123456',
      message: 'Hello from Node.js TypeScript integration!'
    },
    {
      headers: {
        'Authorization': 'Bearer sk_live_your_api_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log('Result:', response.data);
}

sendWhatsAppMessage();
```

## Complete Python Example

```python
import requests

def send_whatsapp_message():
    url = "https://wapi.lushai.dev/api/send-message"
    headers = {
        "Authorization": "Bearer sk_live_your_api_key_here",
        "Content-Type": "application/json"
    }
    payload = {
        "number": "919862123456",
        "message": "Hello from Python script!"
    }
    
    response = requests.post(url, json=payload, headers=headers)
    print(response.json())

send_whatsapp_message()
```

## Complete PHP Example

```php
<?php
$url = "https://wapi.lushai.dev/api/send-message";
$apiKey = "sk_live_your_api_key_here";

$data = array(
    "number" => "919862123456",
    "message" => "Hello from PHP script!"
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer " . $apiKey,
    "Content-Type: application/json"
));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

---
*Generated by Lushai.dev WAPI Engine Enterprise Edition. Machine-readable specification formatted for LLMs and AI Agents.*