Quickstart — n8n Cloud

You need: a SynapsAI account on GROWTH or above with an agent that answers in the Playground, and an n8n Cloud account.

Verification in progress

n8n verification is in progress. Until n8n approves the community node, it is available on self-hosted n8n; follow the self-hosted quickstart.

1. Mint an API key

1. In the SynapsAI console open Account → API keys → New key.
2. Name it n8n, tick messages:write, agents:read, conversations:read, leads:read and — for triggers — hooks:write (plus contacts:read for a trigger that includes the contact; Lead captured needs leads:read). Write scopes ask you to sign in again.
3. Copy the sk_live_… key. It is shown once.

2. Turn on the agent’s API channel

1. Agents → your agent → Extensions → Workflow API (n8n · Make) → Turn on.
2. Copy the signing secret shown once (Rotate secret replaces it later).

3. Add the SynapsAI node

1. After n8n verification is approved, open a new workflow, press +, search SynapsAI and add the community node.
2. Credential → Create new: paste the API key in API Key and the signing secret in Agent Signing Secret. Save — n8n checks it with GET /v1/me. On a plan below GROWTH the test fails with PLAN_FEATURE_UNAVAILABLE.

4. Ask the agent and wait for the reply

1. Start the workflow with Manual Trigger (or any trigger you already use).
2. Configure SynapsAI: Resource Agent, Operation Ask.
   • Agent: pick yours.
   • External User ID: demo-1 (in real flows: your CRM id, a phone number, a ticket id).
   • Text: Hi! What are your opening hours?
   • Wait for Reply: on (default), Limit Wait Time 10.
3. Execute workflow. The node shows Waiting; a few seconds later it resumes with:

{ "status": "REPLIED", "messageId": "msg_…", "conversationId": "…", "text": "We are open…", "components": [], "metadata": null, "errorCode": null }

Map {{ $json.text }} into the next node (Slack, e-mail, your messaging provider…). The conversation is in the SynapsAI console under Conversations with the API channel badge.

When Wait for Reply is on, the node adds a reserved _n8n field to metadata to bind the signed reply to this execution. Do not set _n8n yourself. Metadata remains limited to 20 top-level keys and 2 KB of JSON; the reserved field counts toward both limits, so leave room for at most 19 of your own keys while waiting.

Read-only AI Agent tool

Use SynapsAI Tool (read-only) when connecting SynapsAI to an n8n AI Agent. It exposes conversation, contact, lead, message, template and campaign reads only. Never connect an AI Agent to a key with campaigns:write or contacts:write.

Waiting needs HTTPS

n8n Cloud is reachable over HTTPS, so nothing else is needed. The reply is accepted only when its signature matches your agent’s signing secret; anything else gets 401 and the execution keeps waiting.

5. React to events (optional)

Add a new workflow that starts with SynapsAI Trigger: pick the agent and the events (Agent replied, Operator replied, Conversation ended, Human requested, Lead captured), then Activate. The trigger subscribes itself (you will see it with an API badge on the agent’s hooks page) and unsubscribes when you deactivate the workflow.

Next

Example workflows: Lead captured → CRM, CSAT radar, Human requested → Slack, BSP pipeline, Morning digest, Sheet contacts and lead qualification, Latest conversations, Latest leads, and Lead captured to text.

For campaigns, see sending a WhatsApp template and its note about explicit idempotency keys for recurring sends with identical input.

• Templates — import a ready workflow.
• API reference — every field and error code.