WhatsScale API Documentation

Complete API reference for WhatsScale WhatsApp automation

Authentication

All API requests require an API key in the header:

X-Api-Key: your_api_key

Generate your API key from the Dashboard after connecting your WhatsApp.

Base URL

https://proxy.whatsscale.com

Messaging Endpoints

Send Text Message

POST /api/sendText
{
  "session": "your_session_id",
  "chatId": "1234567890@c.us",
  "text": "Hello from WhatsScale!"
}

Send Image

POST /api/sendImage
{
  "session": "your_session_id",
  "chatId": "1234567890@c.us",
  "file": "https://example.com/image.jpg",
  "caption": "Optional caption"
}

Send Video

POST /api/sendVideo
{
  "session": "your_session_id",
  "chatId": "1234567890@c.us",
  "file": "https://example.com/video.mp4",
  "caption": "Optional caption"
}

Returns a jobId for async processing. Use Check Job Status to monitor.

Post Image Story

POST /api/status/image
{
  "session": "your_session_id",
  "file": "https://example.com/image.jpg",
  "caption": "Optional caption"
}

Post Video Story

POST /api/status/video
{
  "session": "your_session_id",
  "file": "https://example.com/video.mp4",
  "caption": "Optional caption"
}

Post Text Story

POST /api/status/text
{
  "session": "your_session_id",
  "text": "Your status text",
  "backgroundColor": "#25D366"
}

Get Sessions

GET /api/sessions

Returns list of connected WhatsApp sessions for the authenticated user.

Get Contacts

GET /api/:session/contacts

Returns list of contacts for the specified session.

Get Groups

GET /api/:session/groups

Returns list of groups for the specified session.

Check Job Status

GET /api/status/:jobId

Check status of async video/story jobs. Returns: QUEUED, PROCESSING, COMPLETED, or FAILED.

CRM Endpoints

Manage your contacts with tags and metadata for targeted messaging.

Create Contact

POST /api/crm/contacts
{
  "phone": "+1234567890",
  "name": "John Doe",
  "tags": ["customer", "vip"]
}

Tags can be a comma-separated string or an array.

List Contacts

GET /api/crm/contacts

Query parameters:

  • page - Page number (default: 1)
  • limit - Results per page (default: 50)
  • tag - Filter by tag
  • search - Search by name or phone

Get Contact

GET /api/crm/contacts/:id

Returns contact details by ID.

Find Contact by Phone

GET /api/crm/contacts/phone/:phone

Find a contact by phone number. Returns 404 if not found.

Update Contact

PATCH /api/crm/contacts/:id
{
  "name": "John Smith",
  "tags": ["customer", "premium"]
}

Delete Contact

DELETE /api/crm/contacts/:id

Permanently deletes a contact.

Add Tag to Contact

POST /api/crm/contacts/:id/tags
{
  "tag": "vip"
}

Remove Tag from Contact

DELETE /api/crm/contacts/:id/tags/:tag

Removes a specific tag from a contact.

List All Tags

GET /api/crm/tags

Returns all unique tags used across your contacts.

Chat ID Format

  • Individual: 1234567890@c.us (phone number without + or spaces)
  • Group: 120363123456789@g.us

Rate Limits

  • Global: 100 requests/minute
  • Send messages: 30 requests/minute
  • Authentication: 10 requests/minute

Getting Started

  1. Sign up at whatsscale.com
  2. Connect your WhatsApp by scanning the QR code
  3. Generate an API key in the Dashboard
  4. Use the API key in the X-Api-Key header for all requests

Support

Questions? Contact support@whatsscale.com