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 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
/v1/ai/settingsWhether 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 } }
/v1/ai/settingsThe 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
/v1/agentsList 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 } ] }
/v1/agents/{id}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": [ … ] } }
/v1/accounts/{id}/agentGive 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 } }
/v1/agents/{id}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, … } }
/v1/agents/{id}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 } }
/v1/agents/{id}/pause · /v1/agents/{id}/resumePause 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
/v1/agents/{id}/usageWhat 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 } }
/v1/usage/summaryOne 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": [ … ] } }
/v1/agents/{id}/runs · /v1/agents/{id}/runs/{runId}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
/v1/agents/{id}/approvalsActions 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 } ] }
/v1/agents/{id}/approvals/{aid}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." } }
/v1/agents/{id}/handoffsWhich 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 } ] }
/v1/agents/{id}/conversations · /v1/agents/{id}/chats/{chatId}/messagesThe 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 } ] }
/v1/agents/{id}/chats/{chatId}/takeover · /v1/agents/{id}/chats/{chatId}/releaseTake 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 } }
/v1/agents/{id}/chats/{chatId}/replyAnswer 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
/v1/agents/{id}/eventsYour 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
/v1/agents/{id}/knowledgeWhat 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 } ] }
/v1/agents/{id}/knowledge · DELETE /v1/agents/{id}/knowledge/{kid}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" } }
/v1/agents/{id}/memory/{chatId} · POST /v1/agents/{id}/memory/{chatId}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.
/v1/ai/sensesWhich 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": [ … ] } }
/v1/ai/sensesTurn 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 }'
/v1/ai/senses/testCheck 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.
| Route | What the plugin uses it for |
|---|---|
POST /v1/connectors/wordpress | Register (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}/verify | Right after registering: SocialMate makes signed calls to the site and counts its customer and owner tools. |
POST /v1/connectors/wordpress/{id}/manifest | The 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.