wsgo - WhatsApp API

REST API powered by whatsmeow (Go) | Multi-device compatible

Auth Connection Messaging Groups Contacts Webhooks Events QR Pairing

Authentication

All API endpoints (except /docs, /qr, /health) require authentication via API key when API_KEY env var is set.

Send the key in one of these ways:

Header: X-API-Key: your-api-key
Query:  ?api_key=your-api-key

Connection & Status

GET /health

Health check

Response: {"status": "ok"}
GET /api/status AUTH

Get current connection status, device info

{
  "connected": true,
  "loggedIn": true,
  "device": "573000000:00@s.whatsapp.net",
  "pushName": "My Business",
  "platform": "smba"
}
GET /api/qr AUTH

Get QR code for WhatsApp pairing

Query Parameters

format: image (PNG), base64 (JSON with base64), omit for raw text
POST /api/reconnect AUTH

Disconnect and reconnect (generates new QR if needed)

POST /api/logout AUTH

Logout from WhatsApp (unpair device)

Messaging

POST /api/send/text AUTH

Send a text message

Request:
{
  "phone": "573001234567",
  "message": "Hello from wsgo!"
}

Response:
{
  "status": "sent",
  "messageID": "3EB0ABC123...",
  "timestamp": "2026-06-09T12:00:00Z"
}
POST /api/send/image AUTH

Send an image with optional caption

Request:
{
  "phone": "573001234567",
  "image_base64": "/9j/4AAQSkZJRg...",
  "caption": "Check this out!",
  "mime_type": "image/jpeg"
}
POST /api/send/document AUTH

Send a document (PDF, XLSX, etc.)

Request:
{
  "phone": "573001234567",
  "document_base64": "JVBERi0xLjQ...",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "caption": "Monthly report"
}

Groups

GET /api/groups AUTH

Get all joined groups

[{
  "jid": "120363000000@g.us",
  "name": "Work Group",
  "topic": "Project discussion",
  "participants": 15,
  "createdAt": "2024-01-15T10:00:00Z"
}]
POST /api/send/group AUTH

Send a text message to a group

Request:
{
  "group_jid": "120363000000@g.us",
  "message": "Hello group!"
}

Contacts

GET /api/contacts AUTH

Get all contacts from the device

POST /api/check-phone AUTH

Check if phone numbers are on WhatsApp

Request: {"phones": ["+573001234567", "+573009876543"]}

Response:
[
  {"query": "+573001234567", "jid": "573001234567@s.whatsapp.net", "isOnWhatsApp": true},
  {"query": "+573009876543", "jid": "573009876543@s.whatsapp.net", "isOnWhatsApp": false}
]

Webhooks

POST /api/webhook AUTH

Set webhook URL for incoming messages

{"url": "https://your-n8n.example.com/webhook/whatsapp"}
GET /api/webhook AUTH

Get current webhook URL

Webhook Payload

{
  "event": "message",
  "data": {
    "from": "573001234567@s.whatsapp.net",
    "chat": "573001234567@s.whatsapp.net",
    "messageID": "3EB0ABC...",
    "pushName": "John",
    "timestamp": "2026-06-09T12:00:00Z",
    "text": "Hello!",
    "isGroup": false
  }
}

Events Log

GET /api/events AUTH

Get recent events (last 500: messages, connections, disconnections)

wsgo API v1.0 — Built with whatsmeow | Go