Available Credits: 0

API Credentials

Use these credentials to authenticate your API requests

Important: Keep your API key secure. Never share it publicly or commit it to version control. Use environment variables to store sensitive credentials.

Quick Start Guide

1. Authentication

All API requests require authentication using your API key in the request header:

X-API-Key: your-api-key-here
2. Making Your First Request

Send a WhatsApp message using the simple send endpoint:

curl -X POST http://localhost:3000/api/sessions/send-simple \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "phoneNumber": "2348012345678",
    "message": "Hello from Wappi API!"
  }'
const axios = require('axios');

const API_ENDPOINT = 'http://localhost:3000';
const API_KEY = 'your-api-key';

async function sendWhatsAppMessage() {
  try {
    const response = await axios.post(
      `${API_ENDPOINT}/api/sessions/send-simple`,
      {
        phoneNumber: '2348012345678',
        message: 'Hello from Wappi API!'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': API_KEY
        }
      }
    );

    console.log('Message sent:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendWhatsAppMessage();
import requests
import json

API_ENDPOINT = 'http://localhost:3000'
API_KEY = 'your-api-key'

def send_whatsapp_message():
    url = f"{API_ENDPOINT}/api/sessions/send-simple"

    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }

    payload = {
        'phoneNumber': '2348012345678',
        'message': 'Hello from Wappi API!'
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()

        print('Message sent:', response.json())
    except requests.exceptions.RequestException as error:
        print('Error:', error)

send_whatsapp_message()
<?php

$apiEndpoint = 'http://localhost:3000';
$apiKey = 'your-api-key';

$data = [
    'phoneNumber' => '2348012345678',
    'message' => 'Hello from Wappi API!'
];

$ch = curl_init($apiEndpoint . '/api/sessions/send-simple');

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if ($httpCode === 200) {
    echo "Message sent: " . $response;
} else {
    echo "Error: " . $response;
}

?>
3. Sending a Video to a Phone Number

Upload the video file itself as multipart/form-data. The file goes in a field named video, and the recipient in phoneNumber:

curl -X POST http://localhost:3000/api/sessions/send-video-simple \
  -H "X-API-Key: your-api-key" \
  -F "phoneNumber=2348012345678" \
  -F "caption=Our new product!" \
  -F "video=@promo.mp4;type=video/mp4"

The number can be 2348012345678, +2348012345678 or 08012345678 — all three work. Videos must be 40 MB or less and 60 seconds or shorter. See Sending Video for captions, GIF playback and video notes.

4. Sending a Photo (standard or HD)

Same idea as video: the photo goes in a field named image. Add hd=true to send the original at full resolution instead of standard quality:

curl -X POST http://localhost:3000/api/sessions/send-image-simple \
  -H "X-API-Key: your-api-key" \
  -F "phoneNumber=2348012345678" \
  -F "caption=Our new product!" \
  -F "hd=true" \
  -F "image=@product.jpg;type=image/jpeg"

Photos are never re-encoded, so the recipient gets exactly the bytes you upload. hd=true raises the size limit from 16 MB to 32 MB; the response's image.hd.deliveredAsHd tells you whether the photo was large enough (over 1600 px on its longest edge) to show as HD on the recipient's phone. Accepted formats are JPEG, PNG and WebP.

Available Endpoints

Complete list of API endpoints available in your plan

Session Management
POST /api/sessions/create
Create a new WhatsApp session and generate QR code for scanning
GET /api/sessions
Get all WhatsApp sessions with their status and details
GET /api/sessions/:sessionId
Get specific session details including QR code and connection status
DELETE /api/sessions/:sessionId
Disconnect and delete a WhatsApp session
Message Sending
POST /api/sessions/send-simple
Send a WhatsApp message using the first connected session (recommended for quick start)
POST /api/sessions/:sessionId/send
Send a WhatsApp message via a specific session
GET /api/sessions/:sessionId/messages
Get message history for a specific session with pagination
Video Sending
POST /api/sessions/send-video-simple
Send a video using the first connected session (max 40 MB, max 60 seconds)
POST /api/sessions/:sessionId/send-video
Send a video via a specific session, with optional caption, GIF playback or video note
GET /api/sessions/video-limits
Get the accepted video size, duration and formats so you can validate before uploading
Image Sending
POST /api/sessions/send-image-simple
Send a photo using the first connected session (max 16 MB, or 32 MB with hd=true)
POST /api/sessions/:sessionId/send-image
Send a photo via a specific session, with optional caption, view-once or HD quality
GET /api/sessions/image-limits
Get the accepted image size (standard and HD) and formats so you can validate before uploading
WhatsApp Link & QR Code
POST /api/messages/send
Generate a WhatsApp click-to-chat link with pre-filled message
POST /api/messages/qrcode
Generate a QR code for WhatsApp message (PNG or SVG format)
GET /api/messages/history
Get message history with pagination support
GET /api/messages/stats
Get usage statistics (total messages, QR codes generated, etc.)

Sending Video

Upload the video file itself as multipart/form-data — the same way you'd upload any file. The file goes in a part named video; everything else rides along as ordinary form fields. We detect the format from the file's own header, so a missing or wrong Content-Type on the part is fine.

Video limits

• Max file size: 40 MB

• Max duration: 60 seconds

• Formats: mp4, 3gp, mov, webm, mkv — mp4 (H.264 + AAC) plays everywhere, the rest may not

• Cost: 1 credit per video, automatically refunded if delivery fails

Form Fields
video         (file)   required — the video file, field name must be "video"
phoneNumber   (text)   required — 2348012345678, +2348012345678 or 08012345678
caption       (text)   optional — text shown under the video
gifPlayback   (text)   optional — "true" sends a silent looping clip
asVideoNote   (text)   optional — "true" sends a round video note (mp4 only, no caption)
Example
curl -X POST http://localhost:3000/api/sessions/send-video-simple \
  -H "X-API-Key: your-api-key" \
  -F "phoneNumber=2348012345678" \
  -F "caption=Our new product!" \
  -F "video=@promo.mp4;type=video/mp4"
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const API_ENDPOINT = 'http://localhost:3000';
const API_KEY = 'your-api-key';

async function sendWhatsAppVideo() {
  const form = new FormData();
  form.append('phoneNumber', '2348012345678');
  form.append('caption', 'Our new product!');
  form.append('video', fs.createReadStream('promo.mp4'));

  try {
    const response = await axios.post(
      `${API_ENDPOINT}/api/sessions/send-video-simple`,
      form,
      {
        headers: { ...form.getHeaders(), 'X-API-Key': API_KEY },
        maxBodyLength: Infinity,
        timeout: 300000 // large uploads take a while
      }
    );

    console.log('Video sent:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

sendWhatsAppVideo();
import requests

API_ENDPOINT = 'http://localhost:3000'
API_KEY = 'your-api-key'

def send_whatsapp_video():
    url = f"{API_ENDPOINT}/api/sessions/send-video-simple"

    headers = {'X-API-Key': API_KEY}   # requests sets the multipart Content-Type

    data = {
        'phoneNumber': '2348012345678',
        'caption': 'Our new product!'
    }

    try:
        with open('promo.mp4', 'rb') as f:
            files = {'video': ('promo.mp4', f, 'video/mp4')}
            response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

        response.raise_for_status()
        print('Video sent:', response.json())
    except requests.exceptions.RequestException as error:
        print('Error:', error)

send_whatsapp_video()
<?php

$apiEndpoint = 'http://localhost:3000';
$apiKey = 'your-api-key';

$data = [
    'phoneNumber' => '2348012345678',
    'caption'     => 'Our new product!',
    'video'       => new CURLFile('promo.mp4', 'video/mp4', 'promo.mp4')
];

$ch = curl_init($apiEndpoint . '/api/sessions/send-video-simple');

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);   // array => multipart/form-data
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if ($httpCode === 200) {
    echo "Video sent: " . $response;
} else {
    echo "Error: " . $response;
}

?>
Successful Response
{
  "success": true,
  "data": {
    "messageId": "3EB0ABCD1234",
    "sessionId": "session_abc",
    "phoneNumber": "2348012345678",
    "caption": "Our new product!",
    "video": {
      "mimetype": "video/mp4",
      "sizeBytes": 8412345,
      "durationSeconds": 42.5,
      "fileName": "promo.mp4"
    },
    "creditsDeducted": 1,
    "creditsRemaining": 87
  }
}
Video Errors
Status Meaning
400 No file attached, wrong field name, missing phone number, unsupported format, or video longer than 60 seconds
402 Not enough credits
403 That session belongs to another account
413 Video is over 40 MB
500 Delivery failed — your credit is refunded automatically

Rate Limits & Usage

Current Plan: Free Tier

• 100 messages per day

• 1 WhatsApp device connection

• Rate limit: 10 requests per minute

• Webhook support: Not available

Upgrade to a paid plan for higher limits and advanced features:

Upgrade Plan

Response Format

All API responses follow this standard format:

Success Response (200 OK)
{
  "success": true,
  "data": {
    "messageId": "msg_123456",
    "sessionId": "session_abc",
    "phoneNumber": "+2348012345678",
    "message": "Hello from Wappi API!",
    "sentVia": "+2349087654321"
  }
}
Error Response (4xx/5xx)
{
  "success": false,
  "error": "No active WhatsApp session found",
  "hint": "Open http://localhost:3000/qr-scanner.html and scan QR code to connect"
}

Best Practices

1. Secure Your API Key

Never expose your API key in client-side code. Always make API calls from your backend server.

2. Handle Errors Gracefully

Always check the response status and handle errors appropriately. Implement retry logic with exponential backoff.

3. Respect Rate Limits

Monitor your usage and implement request throttling to avoid hitting rate limits.

4. Phone Number Format

Always use international format with country code (e.g., +2348012345678). Include the + symbol.

5. Session Management

Keep your WhatsApp session connected. If disconnected, you'll need to scan the QR code again to reconnect.