API Documentation

System Capabilities & Architecture

Our architecture provides stable WhatsApp connectivity using the Baileys library and supports multiple concurrent user sessions isolated natively via unique API keys.

Authentication

All requests to the messaging endpoints require authentication using the x-api-key header. x-api-key.

🔑 How to get your API Key: Once you pair a device in the dashboard, navigate into the "Settings" menu to view and copy your active Session API Key. Each device you pair runs independently under its given key.

curl -X POST https://ws.erickvillon.dev/api/messages/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SESSION_API_KEY" \
  -d '{"phone": "593991234567", "message": "Hello World"}'

Send simple text messages to any WhatsApp number in the world. Valid phone format avoids symbols and uses the standard country code upfront.

Request Body Requirements

• phone (string, required): Your recipient's phone number exactly digits-only (e.g. 593981234567).
• message (string, required): The plaintext message body. You can use newline characters for spacing (\n).

{
  "phone": "593991234567", 
  "message": "Hola, este es un mensaje de prueba con la nueva URL!" 
}

Send images and videos to any chat. High-quality media is processed and delivered via WhatsApp's native media handling.

{ 
  "phone": "593981234567", 
  "imageUrl": "https://picsum.photos/500/300", 
  "caption": "¡Increíble promoción sólo por hoy!" 
}

{ 
  "phone": "593981234567", 
  "videoUrl": "https://example.com/demo.mp4", 
  "caption": "Check this video!" 
}

Deliver audio notes or music files. Supported formats: mp3, ogg, wav.

{ 
  "phone": "593981234567", 
  "audioUrl": "https://example.com/voice.mp3"
}

Send PDF, Word, Excel, or other files as native document attachments.

{ 
  "phone": "593981234567", 
  "documentUrl": "https://example.com/report.pdf",
  "fileName": "Monthly Report Q1.pdf"
}

Generate an interactive map preview block by pinpointing exact geographic coordinates. Helpful for businesses needing immediate navigational context.

Request Body Requirements

• phone (string, required): The digits-only recipient number.
• latitude (float, required): Precision latitude coordinate logic (e.g. -2.13).
• longitude (float, required): Precision longitude coordinate logic.

{ 
  "phone": "593991234567", 
  "latitude": -2.13289, 
  "longitude": -79.90123 
}

Group Management

Programmatically create groups, add participants, and manage metadata.

{
  "subject": "Company Team",
  "participants": ["593991234560", "593991234561"]
}

Webhooks & Events

Configure your webhook URL in the Dashboard to receive real-time notifications about incoming messages, status updates, and session changes.

{
  "sessionId": "Support-Bot",
  "event": "messages.upsert",
  "data": {
    "key": { "remoteJid": "593991234567@s.whatsapp.net", "fromMe": false, "id": "..." },
    "message": { "conversation": "Hello, how can I help?" },
    "pushName": "John Doe"
  }
}

Error Codes & Limits