Skip to content
SocialMate

The Claude Agent · Connect

REST API and webhooks

Drive agents from your own code.

Pro

Everything you do with agents in the app can be done from your own code: a WordPress screen, an n8n flow, a Slack bot. This page is the overview; every route, field and response is in the Claude Agent API reference.

Before you start

  • The REST API runs on the machine SocialMate runs on, at http://localhost:3456/v1 by default. Creating your first key switches it on; the Tunnel tab under API & Integrations shows the API server and holds the tunnel for reaching it from elsewhere.
  • Create a key under API & Integrations → API Keys and send it as the x-api-key header. Reads need read scope (the global /v1/ai/settings and /v1/ai/senses need an admin key for all accounts), POST …/events needs send, every other write needs admin.
  • Every agent route is Pro. On Free each one answers 402.

The routes

Three examples

Find your agents and what waits for you

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

Each agent comes with its id, status, autonomy, model, today’s numbers and the count of open hand-offs and pending approvals.

Approve a held action

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]" }'

Tell the agent an order shipped

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" }
      }'

202 means queued. The agent needs an event job for that type switched on (here Order updates); consent, the frequency cap and retries are explained in Jobs and event jobs.

Webhooks

Subscribe to these under API & Integrations → Webhooks to mirror the agent in your own tools. Payloads are in Agent events.

  • agent.reply_sent — the agent replied in a chat (messages sent, the run’s cost)
  • agent.draft_created — a draft reply waits for a person (Observe mode)
  • agent.approval_requested — an action is waiting for approval
  • agent.approval_decided — an approval was approved or rejected, and by whom
  • agent.handoff_requested — a chat was handed to a person, with the reason
  • agent.handoff_resolved — a chat was handed back to the agent
  • agent.paused — an agent (or, from the kill switch, every agent) was paused
  • agent.resumed — an agent was resumed
  • agent.budget_warning — an agent reached 80% of its monthly budget, or a cap was reached and the fallback model could not take over
  • agent.injection_detected — a prompt-injection attempt was detected
  • agent.job_failed — an event job could not run
  • agent.lead_captured — the agent saved a lead’s details on the contact

n8n and MCP

No code needed: the SocialMate n8n node has an Agent resource and the agent trigger events (n8n docs), and the open-source socialmate-mcp server exposes the agent to Claude Desktop, Cursor or any MCP client through its whatsapp_agent_* tools (MCP server docs).

Put the Claude Agent on your WhatsApp number.

Download SocialMate, link your number, connect the model you want and create an agent from a preset. Start a free 7-day Pro trial from inside the app — test it on your real questions before a customer sees a word.

Pro: $99/year or $10/month. Built on Anthropic’s Claude Agent SDK — the model is your choice.

Free forever · no card Download free