SocialMate Local API

A WhatsApp API on your own machine

SocialMate runs a real local HTTP API — REST + OpenAPI, signed webhooks, and a built-in Cloudflare Tunnel — on localhost:3456. No WABA, no Meta approval, no per-message bill. This is the developer reference; it mirrors the exact server the desktop app ships.

Quickstart

From download to your first sent message in five minutes.

Authentication

x-api-key, hashed keys, and read / send / admin scopes.

Webhooks

35 events, HMAC-signed, retried, with delivery logs.

Cloudflare Tunnel

Expose localhost to the internet — no ports, no firewall surgery.

What it is

When you enable the API server in the desktop app, SocialMate listens on your machine and binds to 127.0.0.1 — it is private by default. Reads, sends, group management, the media archive, the smart queue, webhooks, and key management are all exposed as plain JSON-over-HTTP. Because the server runs on your computer, there is no hosted gateway in the middle: your WhatsApp data never leaves your device unless you choose to open a tunnel.

Base URL	http://localhost:3456
API version	v1 · OpenAPI 3.0.3 · 1.1.0
Auth	x-api-key: <your key>
Format	JSON in, JSON out — every 2xx wrapped in `{ "data": … }`
Live spec	/docs · /docs/openapi.json

Your first call

List the linked accounts on your machine. Every endpoint except /health and the in-app docs requires your key.

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

{
  "data": [
    {
      "id": "a1b2c3",
      "phone": "15551234567",
      "name": "Sales line",
      "status": "connected",
      "riskLevel": "safe",
      "warmingDay": 1,
      "messagesToday": 12,
      "dailyLimit": 500
    }
  ]
}

The response envelope

Every successful response is wrapped in a data object, and every error in an error object with a stable code. This is the v1.1 envelope — see Responses & errors for the full shape and the legacy opt-out.

// success
{ "data": { "sent": true, "messageId": "3EB0…" } }

// error
{ "error": { "code": "rate_limited", "message": "…", "retryAfterMs": 1200 } }

Free vs Pro, at a glance

Every endpoint exists on Free — reads, text sends, webhooks, and a Quick tunnel all work. Pro removes the ceilings: media and group sends, message history and the AI-context export, auto-queue on anti-ban blocks, a stable Named tunnel, and unlimited webhooks. The full matrix lives on Free vs Pro.

Free — 1 account · read accounts, chats, contacts, groups & media · send text (incl. quoted replies, reactions, read receipts, typing) · 2 webhook endpoints (9 events, 100 deliveries/day) · Quick tunnel. Message history, AI-context and poll results are Pro.
Pro — unlimited accounts · media sends · message history & sync · auto-queue · all 35 webhook events, unlimited · Named tunnel.

The spec is always live in the app. Your running build serves its own OpenAPI at http://localhost:3456/docs/openapi.json with browsable Swagger UI at /docs. Point Postman, Insomnia, or a code generator at it to get a typed client for the exact version you run.