API Documentation - Wavvy
v1.0 Stable

API Documentation

Integrate WhatsApp messaging into your applications with our powerful REST API. Send messages, manage sessions, and automate your communication.

Get API Key Quick Start

Introduction

The Wavvy API allows you to programmatically interact with WhatsApp through your connected sessions. You can send messages, manage sessions, check phone numbers, and more.

Key Features

Send Messages

Text, images, videos, documents

Multi-Session

Manage multiple WhatsApp numbers

Number Validation

Verify WhatsApp registration

Webhooks

Real-time event notifications

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header.

Header 
X-API-Key: your_api_key_here

Security Notice

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

Base URL

All API endpoints are relative to the base URL:

Base URL 
https://your-domain.com/api
GET

List Sessions

Get session counts for your account.

/api/sessions

Response

200 OK 
{
  "success": true,
  "counts": {
    "total": 5,
    "connected": 3,
    "connecting": 1,
    "qr": 1,
    "disconnected": 0
  }
}
POST

Create Session

Create a new WhatsApp session.

/api/sessions

Request Body

JSON 
{
  "sessionName": "My Business Account"
}

Response

201 Created 
{
  "success": true,
  "sessionId": "abc-123-def-456",
  "message": "Session created successfully"
}
GET

Get Session Status

Get detailed status of a specific session.

/api/sessions/:sessionId

Response

{
  "success": true,
  "session": {
    "id": "abc-123-def-456",
    "name": "My Business Account",
    "status": "connected",
    "phone_number": "923001234567"
  }
}

Status Values

connecting qr connected disconnected
GET

Get QR Code

Get QR code for session authentication.

/api/sessions/:sessionId/qr

Response

{
  "success": true,
  "qrCode": "data:image/png;base64,iVBORw0KGgo..."
}
DELETE

Delete Session

Permanently delete a session.

/api/sessions/:sessionId

Warning

This action cannot be undone. All auto-replies and configurations will be deleted.

POST

Send Message

Send a text message via WhatsApp.

/api/sessions/:sessionId/send

Parameters

Name Type Description
to string Phone number with country code
message string Message text (max 4096 chars)

Request Body

JSON 
{
  "to": "923001234567",
  "message": "Hello from Wavvy API!"
}

Response

200 OK 
{
  "success": true,
  "messageId": "3EB0C767D71D8D6E2CD5",
  "message": "Message sent successfully"
}
POST

Send Media

Send media files (images, videos, audio, documents).

/api/sessions/:sessionId/send-media

Supported Media Types

.jpg .png .gif

.mp4 .mov

.mp3 .wav

.pdf .doc

Example (cURL)

cURL 
curl -X POST /api/sessions/abc-123/send-media \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "to=923001234567" \
  -F "message=Check this out!" \
  -F "media=@/path/to/image.jpg"
POST

Check WhatsApp Numbers

Validate if phone numbers are registered on WhatsApp.

/api/number-checker/check

Request Body

{
  "sessionId": "abc-123-def-456",
  "phoneNumbers": ["923001234567", "923009876543"]
}

Response

{
  "success": true,
  "summary": { "total": 2, "valid": 1, "invalid": 1 },
  "results": [
    { "phoneNumber": "923001234567", "isValid": true },
    { "phoneNumber": "923009876543", "isValid": false }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code Description
200 Success
201 Created successfully
400 Bad request - Invalid parameters
401 Unauthorized - Invalid API key
404 Not found - Resource doesn't exist
429 Too many requests - Rate limit exceeded
500 Server error

Rate Limits

API requests are rate limited based on your plan.

60

Requests/minute (Free)

300

Requests/minute (Pro)

Unlimited

Enterprise