Quickstart

This walkthrough takes you from a fresh install to a sent WhatsApp message over the local API. You'll need the SocialMate desktop app (Free is fine) and a terminal.

1 · Install & link a number

Download SocialMate for your platform, open it, and link a WhatsApp number by scanning the QR code — exactly like WhatsApp Web. The number now appears as a connected account.

2 · Turn on the API server

Open the API page in the app and switch the local HTTP server on. It binds to 127.0.0.1:3456 — private to your machine until you open a Cloudflare Tunnel.

Confirm it's up with /health — one of the few routes that needs no key (the in-app /docs are the other):

curl http://localhost:3456/health
# { "status": "ok", "app": "SocialMate", "version": "…", "timestamp": "2026-06-28T12:00:00.000Z", "uptimeSec": 12 }

3 · Create an API key

On the same page, create a key and copy it — you'll only see the full value once. Keys are stored SHA-256 hashed and carry scopes (read, send, admin). Send it as the x-api-key header on every request.

curl http://localhost:3456/v1/accounts \
  -H "x-api-key: YOUR_KEY"

Grab the id of the account you want to send from out of that response.

4 · Send your first message

Post to that account. chatId is simply the recipient's phone number in international format (with the country code) — punctuation, a leading + and a 00 prefix are all accepted, so 15551234567 and +1 (555) 123-4567 both work. For a group, pass its JID ending in @g.us. Every send runs through the 8-layer anti-ban pipeline; there is no bypass.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "15551234567", "text": "Hello from SocialMate" }'

{
  "data": {
    "sent": true,
    "messageId": "3EB0…",
    "chatId": "[email protected]",
    "timestamp": 1717245600000,
    "status": "sent"
  }
}

What next

• Authentication & API keys — scopes, rotation, rate limits.
• Sending messages — media, priority, and the auto-queue fallback.
• Webhooks — get events pushed to your own URL.