Skip to content
SocialMate

SocialMate Local API

Claude Agent (Pro)

Manage the Claude Agent, SocialMate Pro’s built-in WhatsApp AI agent: settings and kill switch, usage and cost, approvals, hand-offs and takeover, event jobs, knowledge, memory and senses.

Claude Agent

Claude Agent is SocialMate Pro’s built-in WhatsApp AI agent: one agent per WhatsApp number that replies like a person, hands a chat to a person when it should, asks for approval before risky actions, and keeps to the budget you set. These routes let your own tools — a WordPress screen, an n8n flow, a Slack bot — manage it: settings, the kill switch, usage and cost, the approval and hand-off inbox, human takeover, event-triggered jobs, knowledge and per-contact memory.

Setting an agent up in the app rather than scripting it? Follow the Claude Agent guides, or start with the Claude Agent overview.

Every route here is Pro (aiEnabled). On Free each one answers 402. Reads use read scope (the global settings and senses are admin); POST …/events uses send scope; every other write is admin. A key limited to specific accounts only sees agents on those accounts — any other agent id is a 404.

The agent never picks who to message. Replies go to the chat that wrote in; event jobs go to the recipient in your event. Every message the agent sends goes through the same anti-ban pipeline as everything else (rate limits, jitter, warming, risk checks) and counts against the account's daily budget. Cost is worked out from SocialMate's own price list, per model. Built on Anthropic’s Claude Agent SDK — the model is your choice, a separate setting on your own key: Claude, DeepSeek, OpenRouter, Ollama (local), Kimi, GLM, MiniMax or a custom endpoint.

Global controls

GET /v1/ai/settings

scope: adminPro

Whether every agent is paused by the global kill switch, and the monthly spend cap shared by all agents (0 = no cap). Needs an admin key for all accounts (403 otherwise).

curl http://localhost:3456/v1/ai/settings \
  -H "x-api-key: ADMIN_KEY"
{ "data": { "paused": false, "monthlyCapUsd": 100 } }
PUT /v1/ai/settings

scope: adminPro

The emergency stop and the spend ceiling. Body (both optional): paused (boolean — true stops every agent at once and fires agent.paused with scope: "all"), monthlyCapUsd (0–100000, 0 = no cap). Returns the settings after the change.

curl -X PUT http://localhost:3456/v1/ai/settings \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "paused": true }'
{ "data": { "paused": true, "monthlyCapUsd": 100 } }

Agents

GET /v1/agents

scope: readPro

List agents with today's numbers: status, autonomy, model, today's conversations / replies / tokens / cost, and how many hand-offs and approvals are waiting. Use it to find the agent id for an account.

curl http://localhost:3456/v1/agents \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "b7e2c1d4-…", "accountId": "acct_1", "accountLabel": "Sales · +15551230000", "name": "Shop assistant", "status": "active", "autonomy": "autopilot", "model": "claude-sonnet-5-5", "provider": { "kind": "anthropic", "label": "Anthropic (Claude)" }, "today": { "conversations": 14, "replies": 31, "tokens": 182400, "costUsd": 0.42 }, "openHandoffs": 1, "pendingApprovals": 2 } ] }
GET /v1/agents/{id}

scope: readPro

The full configuration: persona, rules, hours, escalation, budget, senses, jobs, tool policies and connectors, plus jobCatalog (every job the agent can be given). Keep configVersion to send with PATCH. Provider secrets are never returned.

curl http://localhost:3456/v1/agents/AGENT_ID \
  -H "x-api-key: YOUR_KEY"
{ "data": { "id": "b7e2c1d4-…", "name": "Shop assistant", "status": "active", "autonomy": "autopilot", "presetId": "shop", "persona": { "name": "Mona", "languages": "auto", "emoji": "sometimes" }, "model": "claude-sonnet-5-5", "budget": { "dailyUsd": 5, "monthlyUsd": 50, "turnsPerChatPerDay": 40, "onCap": "handoff" }, "senses": { "vision": true, "hearing": true, "voiceReplies": "never" }, "jobs": ["support", "sales", "orders", "order_update"], "configVersion": 7, "jobCatalog": [ … ] } }
POST /v1/accounts/{id}/agent

scope: adminPro

Give a WhatsApp number its agent (one per account). Body: presetId (shop, order_help, cod_confirm, leads, clinic, real_estate, restaurant, services, support_desk, creator or blank — sets the purpose, jobs, voice and hand-off words), name, autonomy (observe = drafts only, copilot = every action waits for approval, autopilot = low-risk actions run, autonomous = everything runs except tools set to approve; default observe), providerId, model, and any field PATCH accepts. A new agent always starts as a draft — it never switches itself on. Without a providerId it starts on the provider the app's own wizard would pick (your Claude key, else one that passed “Test connection”); then call …/resume. 409 if the number already has an agent.

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/agent \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "presetId": "shop", "name": "Shop assistant", "persona": { "name": "Mona" } }'
{ "data": { "id": "b7e2c1d4-…", "name": "Shop assistant", "status": "draft", "autonomy": "observe", "providerId": null, "model": "", "jobs": ["support", "sales", "orders", "order_status", "order_update", "back_in_stock", "owner_assistant"], "configVersion": 2 } }
PATCH /v1/agents/{id}

scope: adminPro

Partial, version-checked update. Only the fields you send change; nested objects merge. Fields: version (the configVersion you last read — or send an If-Match header), name, purpose, customPrompt, autonomy, providerId, model, persona, gate (groups, allow/deny lists, step-aside minutes, opt-out words, hours), escalation, budget (dailyUsd, monthlyUsd, turnsPerChatPerDay, onCap), jobs, ownerNumbers (up to 10 owner numbers that get the owner tools), plus senses, delivery, toolPolicies and connectors. status is ignored — use pause and resume. 409 version_conflict (with currentVersion) if the agent changed since you read it.

curl -X PATCH http://localhost:3456/v1/agents/AGENT_ID \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "version": 7, "persona": { "rules": "Never promise a delivery date." }, "budget": { "dailyUsd": 10 } }'
{ "data": { "id": "b7e2c1d4-…", "budget": { "dailyUsd": 10, "monthlyUsd": 50, "turnsPerChatPerDay": 40, "onCap": "handoff" }, "configVersion": 8, … } }
DELETE /v1/agents/{id}

scope: adminPro

Remove the agent from a number for good. To stop it for a while, pause it instead.

curl -X DELETE http://localhost:3456/v1/agents/AGENT_ID \
  -H "x-api-key: ADMIN_KEY"
{ "data": { "deleted": true } }
POST /v1/agents/{id}/pause  ·  /v1/agents/{id}/resume

scope: adminPro

Pause one agent (for example while staff handle a busy period), or turn a paused or draft agent on. Fire agent.paused / agent.resumed and return the agent's summary row. Resume answers 409 not_configured until a provider and model are chosen; the global kill switch still wins while it is on.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/resume \
  -H "x-api-key: ADMIN_KEY"
{ "data": { "id": "b7e2c1d4-…", "name": "Shop assistant", "status": "active", "autonomy": "autopilot", … } }

Usage, cost & runs

GET /v1/agents/{id}/usage

scope: readPro

What one agent did and cost. Query: range (today, 7d default, 14d, 30d, 90d). Returns totals (runs, conversations, replies, hand-offs, tokens, cost, resolution rate, p50/p95 latency, prompt-injection attempts), a per-day series, spend per model and the most-used tools. monthCostUsd is this calendar month regardless of the window.

curl "http://localhost:3456/v1/agents/AGENT_ID/usage?range=7d" \
  -H "x-api-key: YOUR_KEY"
{ "data": { "range": "2026-09-26T09:14:00.000Z..2026-10-03T09:14:00.000Z", "totals": { "runs": 212, "conversations": 58, "replies": 171, "escalations": 6, "tokens": 1284000, "costUsd": 3.18, "resolutionRate": 0.966, "p50LatencyMs": 3900, "p95LatencyMs": 9100, "injectionAttempts": 0 }, "daily": [ … ], "byModel": [ { "model": "claude-sonnet-5-5", "tokens": 1284000, "costUsd": 3.18 } ], "byTool": [ … ], "monthCostUsd": 4.02 } }
GET /v1/usage/summary

scope: readPro

One call for a spend dashboard across all the agents the key can see: number of agents, today's totals, this month's cost, and a per-day series for the last 14 days.

curl http://localhost:3456/v1/usage/summary \
  -H "x-api-key: YOUR_KEY"
{ "data": { "agents": 2, "today": { "conversations": 14, "replies": 31, "tokens": 182400, "costUsd": 0.42, "escalations": 1 }, "monthCostUsd": 4.02, "daily": [ … ] } }
GET /v1/agents/{id}/runs  ·  /v1/agents/{id}/runs/{runId}

scope: readPro

Audit what the agent decided in each turn, newest first: trigger, status, model, tokens, cost, latency and the acts it sent. Query: limit (1–200, default 50), before (Unix ms — pass the last startedAt to page back), includeSkipped (default true). The single-run route adds steps: every tool call in order with its arguments, a short result and how long it took.

curl "http://localhost:3456/v1/agents/AGENT_ID/runs?limit=20&includeSkipped=false" \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "5d4c3b2a-…", "chatId": "[email protected]", "trigger": "message", "lane": "customer", "status": "completed", "model": "claude-sonnet-5-5", "costUsd": 0.0132, "latencyMs": 4200, "toolCalls": 1, "acts": [ { "kind": "say", "text": "Yes, the 250 g bag is in stock. Want me to add it to your basket?", "quote": null } ], "startedAt": 1759480000000 } ] }

Approvals, hand-offs & takeover

GET /v1/agents/{id}/approvals

scope: readPro

Actions waiting for a decision — build an approval queue in Slack or a WordPress screen. Query: status (pending default, or all for the newest 100). Each item says what the agent wants to do (summary, preview) and when it expires.

curl http://localhost:3456/v1/agents/AGENT_ID/approvals \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "a1b2c3d4-…", "chatId": "[email protected]", "kind": "act", "summary": "Send the order confirmation", "preview": "Your order #1042 is confirmed: 2 × 250 g bag, total $24.", "status": "pending", "expiresAt": 1759566405000 } ] }
POST /v1/agents/{id}/approvals/{aid}

scope: adminPro

Approve or reject a held action. Body: decision (approve | reject, required), decidedBy (for the audit log). On approve the held messages go out through the anti-ban pipeline, or the website action runs. Read ok and message — for example “Already approved.” when someone decided first.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/approvals/APPROVAL_ID \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "decidedBy": "[email protected]" }'
{ "data": { "ok": true, "message": "Approved and sent." } }
GET /v1/agents/{id}/handoffs

scope: readPro

Which customers need a person, and why (reason; trigger is keyword, failures, agent, budget or takeover). Query: status (open default, or all).

curl http://localhost:3456/v1/agents/AGENT_ID/handoffs \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "f1e2d3c4-…", "chatId": "[email protected]", "contactName": "Jane", "contactPhone": "15551230001", "reason": "The customer asked for a person", "trigger": "keyword", "status": "open", "openedAt": 1759480100000 } ] }
GET /v1/agents/{id}/conversations  ·  /v1/agents/{id}/chats/{chatId}/messages

scope: readPro

The chats the agent has worked in, most recent first, with run and reply counts and each chat's state (active, stepped_aside, handoff, paused, opted_out; limit 1–100, default 30). The messages route returns a chat's latest messages, oldest first (limit 1–100, default 40); source says who wrote an outgoing message (agent, app, api, phone). URL-encode the @ in chatId.

curl "http://localhost:3456/v1/agents/AGENT_ID/chats/15551230001%40s.whatsapp.net/messages?limit=20" \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "3EB0C431D5A2F6B1", "body": "Do you have the 250 g bag?", "fromMe": false, "source": "received", "timestamp": 1759479990000 }, { "id": "3EB0C431D5A2F6B2", "body": "Yes, the 250 g bag is in stock. Want me to add it to your basket?", "fromMe": true, "source": "agent", "timestamp": 1759480004000 } ] }
POST /v1/agents/{id}/chats/{chatId}/takeover  ·  /v1/agents/{id}/chats/{chatId}/release

scope: adminPro

Take a chat over: the agent stops replying there (any pending reply is cancelled) and a hand-off stays open until you release it. Release hands the chat back to the agent and resolves its open hand-offs (fires agent.handoff_resolved). No body needed.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/chats/15551230001%40s.whatsapp.net/takeover \
  -H "x-api-key: ADMIN_KEY"
{ "data": { "ok": true } }
POST /v1/agents/{id}/chats/{chatId}/reply

scope: adminPro

Answer a handed-off customer from your own inbox as a person. Body: text (required, up to 4000 characters). The chat is taken over first, then the text goes out through the anti-ban pipeline as a human message. Release the chat when you are done.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/chats/15551230001%40s.whatsapp.net/reply \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "text": "Hi Jane, this is Sam from the team. Your refund is on its way." }'
{ "data": { "ok": true } }

Event jobs

POST /v1/agents/{id}/events

scope: sendPro

Your shop, booking system or n8n flow tells the agent something happened, and the agent writes the customer one message about it. Body: type (required — e.g. order.status_changed, order.paid, order.shipped, booking.reminder, form.submitted, cart.abandoned, stock.back_in; it picks the matching job the agent has enabled), idempotencyKey (required, unique per event), recipient.phone (required, with country code; groups are refused), recipient.name, recipient.locale, data (the facts the agent may use — it only uses what you send), consent (source, at), job, occurredAt, instruction (what you want the agent to do for this event, in your words — up to 1,000 characters; treated as your instruction, while data stays data) and audience (owner tells you instead: the recipient must be one of the agent’s owner numbers, and no consent or frequency cap applies).

The recipient always comes from your event, never from the model. Order updates, booking and payment reminders need no opt-in; other jobs need a recorded opt-in or a consent object. At most 2 messages per job per contact in 12 hours. 202 queued means accepted; 200 means nothing will be sent, with status duplicate or skipped and a reason (for example recipient_not_owner, opted_out, no_consent, frequency_cap, handed_off, agent_paused).

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/events \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
        "type": "order.shipped",
        "idempotencyKey": "wc-order-1042-shipped",
        "recipient": { "phone": "+1 555 123 0001", "name": "Jane" },
        "data": { "orderNumber": "1042", "courier": "DHL", "trackingUrl": "https://track.example.com/JD0142" }
      }'
{ "data": { "status": "queued", "eventId": "0a1b2c3d-…" } }

Knowledge & contact memory

GET /v1/agents/{id}/knowledge

scope: readPro

What the agent can look up when it answers: its own entries plus entries shared across the account (agentId: null). tokens estimates each entry's size.

curl http://localhost:3456/v1/agents/AGENT_ID/knowledge \
  -H "x-api-key: YOUR_KEY"
{ "data": [ { "id": "7c6b5a49-…", "kind": "qa", "title": "Delivery times", "content": "Q: How long does delivery take?\nA: 2–4 working days in the city, 3–6 elsewhere.", "tokens": 28 } ] }
POST /v1/agents/{id}/knowledge  ·  DELETE /v1/agents/{id}/knowledge/{kid}

scope: adminPro

Sync FAQs, policies or product notes from your CMS so the agent answers from your facts. Body: content (required, up to 200,000 characters), kind (text, qa, url, example), title, shared (true stores it for the whole account). The content is stored as sent — no URL is fetched. DELETE removes an entry and is safe to repeat.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/knowledge \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "qa", "title": "Delivery times", "content": "Q: How long does delivery take?\nA: 2–4 working days in the city, 3–6 elsewhere." }'
{ "data": { "id": "7c6b5a49-…", "kind": "qa", "title": "Delivery times", "tokens": 28, "createdAt": "2026-10-01 12:00:00" } }
GET /v1/agents/{id}/memory/{chatId}  ·  POST /v1/agents/{id}/memory/{chatId}

scope: read / adminPro

Read the facts the agent saved about one customer (newest first, up to 50; source is api, owner or agent:…), or teach it something your CRM knows. POST body: fact (2–300 characters). Only the newest 50 facts per contact are kept.

curl -X POST http://localhost:3456/v1/agents/AGENT_ID/memory/15551230001%40s.whatsapp.net \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "fact": "VIP customer since 2023" }'
{ "data": { "id": "2b3c4d5e-…" } }

Senses — voice notes & photos

The agent can understand voice notes and photos and reply with voice notes. Each sense is served by a provider you connect in the app with your own key (for example OpenAI or Groq). Global settings, admin scope, Pro.

GET /v1/ai/senses

scope: adminPro

Which provider and model serves each sense (null = off) and, in options, which configured providers can serve which sense and at what estimated price (hearing per audio minute, seeing per photo, speaking per 1,000 characters).

curl http://localhost:3456/v1/ai/senses \
  -H "x-api-key: ADMIN_KEY"
{ "data": { "settings": { "hearing": { "providerId": "f0e1d2c3-…", "model": "gpt-4o-mini-transcribe" }, "seeing": null, "speaking": { "providerId": "f0e1d2c3-…", "model": "gpt-4o-mini-tts", "voice": "nova" }, "maxVoiceMinutes": 5 }, "options": [ … ] } }
PUT /v1/ai/senses

scope: adminPro

Turn senses on or off. Send only what you change: hearing and seeing ({ providerId, model } or null), speaking ({ providerId, model, voice? } or null), maxVoiceMinutes (0.5–30 — longer voice notes are not transcribed). A provider that cannot serve a sense is refused. Returns the same view as GET.

curl -X PUT http://localhost:3456/v1/ai/senses \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "hearing": { "providerId": "PROVIDER_ID", "model": "gpt-4o-mini-transcribe" }, "seeing": null }'
POST /v1/ai/senses/test

scope: adminPro

Check a saved provider really works before customers rely on it. Body: sense (hearing | seeing | speaking). A failed test still answers 200 with ok: false and the reason. Costs a fraction of a cent at the provider.

curl -X POST http://localhost:3456/v1/ai/senses/test \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "sense": "hearing" }'
{ "data": { "ok": true, "message": "Works: gpt-4o-mini-transcribe transcribed a test clip in 1.2s.", "sample": "", "ms": 1430 } }

Connectors (WordPress)

The free WordPress plugin SocialMate – Messaging & AI Agent (see the plugin and download it here, with step-by-step WordPress guides; it replaced Agent Connect) lets the agent sell and support on your WooCommerce store — products, basket, delivery, a payment link or cash on delivery, order status, returns and back-in-stock alerts — and lets you run the store from WhatsApp. The plugin calls these routes itself during pairing; you rarely call them by hand. All are Pro, admin scope.

After pairing, the plugin's Setup has an agent step: what the agent should do — sell in WhatsApp, answer order questions, confirm cash-on-delivery orders, take bookings, reply to form leads, run a restaurant, or answer from your pages. One click opens the matching tools for customers on the site, creates (or updates) the agent here with that preset and the site attached, and turns on its event jobs (order updates, booking reminders, form follow-ups). On the site, the matching events are set to Agent task on the plugin's Events tab — only events that are still off, never one the owner already sends a message for — so each event reaches the customer one way. An agent made in the app's wizard gets a “one step left” note on the site until its website part is done.

RouteWhat the plugin uses it for
POST /v1/connectors/wordpressRegister (pair) the site: stores its credentials encrypted, creates a signed webhook subscription for the site, and returns the webhook secret once.
POST /v1/connectors/wordpress/{id}/verifyRight after registering: SocialMate makes signed calls to the site and counts its customer and owner tools.
POST /v1/connectors/wordpress/{id}/manifestThe site's tool list changed (a pack was turned on or off) — SocialMate re-reads it.
PATCH /v1/connectors/wordpress/{id}Rotate keys or move the site, then re-verify.
DELETE /v1/connectors/wordpress/{id}Unpair: sends the site a connector.revoked webhook, then removes its subscription.

Agents can also use any MCP server you add in the app. For the webhook side of the agent — replies, approvals, hand-offs, budget warnings — see the Agent events.

Free forever · no card Download free