Connection, settings & operations

This page is the settings and operation reference for the SocialMate action node. For the trigger node and its events see Trigger node & events.

Create a connection in the app

Let SocialMate provision the credential for you — it mints a correctly-scoped key and pre-registers the webhook secret in one step:

1. In the desktop app open API & Integrations → n8n → New connection.
2. Pick the account scope — This account, Selected accounts, or All accounts. The key is bound to that scope; it can never touch an account you didn't allow.
3. Copy the Server URL and API key into the n8n credential below.

The SocialMate API credential

The Account setting (scope-aware)

Every operation has an Account dropdown that lists only the accounts your key allows — and auto-selects when the key is bound to a single account, so there's nothing to type. This replaces the old "Default Account ID" field. Server-side scope enforcement means even an All accounts key only ever sees the accounts it was granted.

Key scopes

Keys carry one or more scopes; an operation that needs an ungranted scope returns a clear 403:

Local vs remote reach

Operation reference

One node, grouped by resource. Free operations work on every tier; Pro operations need a Pro license (the API returns a clear 402 on Free so your workflow fails loudly, not silently).

Send Text — the result envelope

A send can resolve three ways, and the node surfaces each so your workflow can branch:

Queue a Batch — many personalised messages, one call

Pro Queue → Queue a Batch takes a template with {{column}} placeholders and up to 5,000 rows, creating one managed batch: one individual, personalised message per person, each paced by the anti-ban engine. Use it when several people who are already waiting on you need the same news — an order delay, a new pickup time.

This is not a broadcast. Identical text to many contacts is blocked by the duplicate-content guard, so personalise every row. Only for people who contacted you or explicitly opted in — never a list you bought, scraped or guessed. Batch sending is off by default: switch it on deliberately, with consent, in the app first (it returns 403 until then). Each row carries a chatId plus the fields your template references; the smart queue paces every send through anti-ban and lets you pause, resume, retry or cancel the whole batch.

template: "Hi {{name}}, your appointment is {{time}} on {{date}}."
rows: [
  { "chatId": "15551234567", "fields": { "name": "Jordan", "time": "10:00", "date": "Mon" } },
  { "chatId": "15557654321", "fields": { "name": "Sam",    "time": "11:30", "date": "Mon" } }
]
options: { "priority": 1, "scheduledAt": "2026-07-01T08:00:00Z", "batchName": "july-reminders" }

Get Anti-Ban Status — observe before you push

Account → Get Anti-Ban Status returns live risk, warming phase, pause state and the per-minute/hour/day rate limits for an account — read it in a workflow to throttle yourself, or to alert when an account enters cooling. Pair it with the anti-ban reference.

Errors you'll see

An anti-ban block is data, not an error

Since v2.7.0, when the anti-ban engine refuses a send, Send Text and Send Media return it as structured data rather than throwing:

{ "blocked": true, "reason": "night_mode", "retryAfterMs": 27000000, "hint": "…", "upgrade": "…" }

Branch on blocked. The node deliberately does not retry these: the older behaviour slept through Retry-After (which can be hours during quiet hours) and then threw a generic error that lost the reason. Route a blocked send to Queue → Enqueue Message on Pro and the smart queue replays it when the block clears; on Free, inspect reason and decide. A workflow that ignores blocked will look like it succeeded while sending nothing.