SetSmart API Documentation

Complete REST API reference for integrating SetSmart with your applications. Automate lead management, WhatsApp messaging, and AI assistants with our powerful API endpoints.

Requires a managed Agency account

White-label API

Run SetSmart entirely under your own brand. Your backend creates client workspaces, connects their WhatsApp and Instagram through SetSmart's native flows, builds their AI assistants and displays their conversations — your customers never see SetSmart.

Your own onboarding

Create a full SetSmart workspace for each of your customers with one API call, from your own signup funnel.

Native channel connections

Put SetSmart's real WhatsApp embedded signup and Instagram OAuth behind your own "Connect" buttons via one-time links.

Assistant builder

Generate and edit each client's AI setter through the API or through hosted white-label pages served on your own domain.

Your own inbox

Read every client conversation (list, filters, full threads) and render them in your product's UI.

Requirements

1. A managed Agency account. The white-label API is exclusively for MANAGED agencies: agencies that run on a normal SetSmart plan. Any active Pro, Scale or Enterprise subscription becomes one in one click from /app/upgrade-agency-managed. No AI keys to bring: SetSmart pays the AI bill and every message your client workspaces send is counted on your plan's message quota, with top-up packs applying exactly as usual.

2. The owner account's API key. Grab it in the SetSmart app under Settings. All calls below authenticate with that key — a client workspace's own key is rejected with 403, so the key you integrate is always the agency's.

The legacy seat-based BYOK Agency plan does NOT include the white-label API (calls return 403 MANAGED_AGENCY_REQUIRED). It keeps its in-app dashboard and /api/agency/usage for rebilling.

Authentication

Base URL

https://setsmart.io

Header (the only accepted method)

x-api-key: your_owner_api_key

White-label endpoints are deliberately header-only: these calls create workspaces, mint login links and manage domains, so the key must never appear in URLs (proxies, CDNs and browsers log those). The single exception is the read-only /api/agency/usage, which also accepts ?api_key= for backwards compatibility.

Session cookies work too: every endpoint on this page is the same one the SetSmart agency dashboard uses, so anything the dashboard can do, your backend can do.

Quickstart: onboard a client end-to-end

Create their workspace

POST /api/agency/create-client
x-api-key: your_owner_api_key
{ "email": "client@brand.com", "client_name": "brandco" }

→ { "ok": true, "user_id": "9f8e…", "email": "client@brand.com" }

Re-adding an email you previously removed re-attaches the old workspace with all its data ("relinked": true).

Put a "Connect WhatsApp" button in YOUR app

POST /api/agency/form-token
{ "clientUserId": "9f8e…" }

→ { "connectUrls": {
      "whatsapp":  "https://setsmart.io/p/<token>/connect/whatsapp",
      "instagram": "https://setsmart.io/p/<token>/connect/instagram" } }

Point your own button at that URL (add ?nav=0 to hide the client portal menu). Your customer gets ONE screen with ONE button and nothing branded: they click, authorize on Meta, done. No password, no SetSmart account, and no session is ever created, so they can never reach the SetSmart app.

Build their AI assistant

POST /api/agency/form-token
{ "clientUserId": "9f8e…" }

→ { "createUrl": "https://app.youragency.com/p/<token>/new",
    "editUrl":   "https://app.youragency.com/p/<token>/edit" }

Hosted, unbranded create/edit pages, served only while "Show assistants in the client portal" is on in your White-label settings (off by default: your customers then get connections and analytics only, and you build their assistant from your side). The URLs automatically use YOUR custom domain once you have attached and verified one via /api/agency/domains (White-label Domains); with no custom domain yet, they are served on setsmart.io. Prefer full API control? Use GET /api/agency/client-assistants + POST /api/agency/client-prompt.

Show their conversations in your product

GET /api/agency/client-conversations?user_id=9f8e…&page=1&limit=20

→ { "conversations": [ { "id": …, "name": "Lea", "channel": "instagram",
      "qualified": true, "booked": false, "lastMessage": "…", … } ],
    "total": 132, "hasMore": true }

GET /api/agency/client-conversation?user_id=9f8e…&id=812

→ { "conversation": { …,
      "messages": [ { "role": "user", "content": "hey…", … }, … ],
      "message_log": [ { "sender_type": "ai", "status": "read",
                         "channel": "instagram", … }, … ] } }

messages is the display thread; message_log is the per-message source of truth (delivery status sent/delivered/read/played/failed, AI vs template vs human attribution, provider error codes) — everything a real inbox UI needs.

Endpoint reference

Click any endpoint for the full page: parameters, example request and response, error codes, and a live tester (plug your owner API key, requests hit your real agency).

Control everything inside a workspace (MCP)

The endpoints above manage the agency layer (workspaces, connections, assistants, conversations, billing). Everything inside a workspace, every setting, toggle and automation, is driven through SetSmart's MCP server: 202 tools, and a client workspace authenticates with its own API key as the Bearer token. No OAuth consent flow, and rotating the key revokes access instantly.

POST https://setsmart.io/api/mcp
Headers:
  Authorization: Bearer sk_<workspace_api_key>
  Content-Type: application/json

A sample of what that covers per workspace:

Settings

settings.get / settings.update / settings.list_allowed_fields — delays, opt-in limits, night hours, off-days, blocked countries, notifications, locale, webhook URL, follow-ups…

whatsapp.get_profile / whatsapp.update_profile / whatsapp.get_status / whatsapp.get_phone_info / whatsapp.disconnect

Comment to DM

comment_reply.get_auto_reply / set_auto_reply / list_global_triggers / set_global_triggers / add_global_trigger (Instagram, or Facebook with platform: "facebook") / instagram_post.* / facebook_post.list / get_triggers / set_triggers / delete_triggers

DM triggers

dm_trigger.list / set_keywords / add_keywords / remove_keywords / set_strict_mode / dm_trigger.test

AI control

Pause / resume the AI per channel or per contact, assistants, knowledge base, voice, templates

Everything else

Contacts, conversations, campaigns, scheduling, analytics, Calendly / Cal.com / GoHighLevel / iClosed / Shopify integrations

Full tool list in the MCP Server section. Plug a workspace into Claude, ChatGPT, Cursor or your own agents — or call the JSON-RPC endpoint directly from your backend.

How billing works

Your plan is the meter. Nothing else to set up.

• Client workspaces run on SetSmart's AI keys — you never touch OpenAI or Anthropic
• Every weighted message a client sends counts on YOUR plan's quota, exactly like your own messages
• Top-up packs, cycle resets and quota emails work unchanged on your normal Stripe billing
• When the quota (plus purchased packs) is exhausted, all client workspaces pause together until the next pack or cycle
• /api/agency/usage gives you per-client weighted message counts to price your own offer on top; how you bill your clients is entirely yours

Security notes

• connect-link URLs are login links. Each one signs the browser into that client workspace. Generate them server-side, deliver them only to that client, never log or reuse them. They are single-use and short-lived.

• Keep the owner API key server-side. Never ship it in frontend code — anyone holding it can manage every client workspace. Rotate it anytime from Settings.

• Ownership is enforced everywhere. Any user_id that is not one of YOUR client workspaces returns a generic 404.

• Capacity. Up to 100 client workspaces per agency. Workspace deletion is a soft detach: data is kept and re-adding the same email restores it.