n8n-nodes-bgos

Community nodes for n8n to integrate with the BGOS AI assistant chat platform.

Nodes

BGOS (Action Node)

Perform operations on the BGOS platform:

Render Mode — Inline Buttons vs. Modal Pop-Under

Two ways the BGOS app renders buttons that come with a message:

Default to inline unless you know the user is actively in the chat. Modals interrupt. Inline never does.

Decision tree for AI agents

Is this message triggered by a user message they sent in the last ~2 minutes?
├─ YES → modal OK (but inline also works)
└─ NO  → inline. Always.

Do you need multi-question carousel, free-text, OR skip-all semantics?
├─ YES → must use modal (askUserInput op with askRenderMode=modal)
└─ NO  → prefer inline

Agent-facing contract

• Inline chips ≤ 6 (backend rejects more). Labels ≤ 24 chars render cleanly; longer wraps.
• When the user clicks a chip, your BGOS Trigger receives button_clicked with callback_data = the option's value.
• When the user taps Skip, button_clicked fires with callback_data: "__skip__" and option_id: null.
• When the user taps Custom reply and submits free text, they get two events: a normal user message AND a button_clicked with callback_data: "__custom__" + custom_text: <what they typed>. Correlate by message_id.
• Respond to button clicks with the Answer a Callback operation so the chip animation completes.

Ask User Input

Pops the BGOS app's polished modal/sheet to ask the user 1–4 multiple-choice questions in a single carousel. Each question accepts: option list (label + value), optional free-text fallback, optional skip. The node POSTs each question to /api/v1/messages with messageType=ask_user_input, sharing one askId so they group into one carousel.

Two response modes:

• Wait for Answers (default): blocks until every question is answered (or the timeout expires) and returns { askId, answers: [{ messageId, askOrder, question, picked_option_value?, picked_option_label?, free_text?, skipped? }] }. Requires a User ID for the polling chat-history GET.
• Fire and Forget: returns immediately with { askId, questionMessageIds }. Subscribe to the Ask Response event in a separate BGOS Trigger workflow to receive each answer as it lands.

Event Messages

Mark a sent message as machine-delivered event traffic — dashboard dispatches, watcher pushes, sweep digests, voice-call transcripts, n8n notifications — and the BGOS app renders it as a quiet collapsed card (source eyebrow + title + one-line peek) instead of a chat bubble, expandable to the full markdown body plus an optional JSON drawer.

On Send a Message, set Message Type → Event and fill:

The Text field stays the canonical full body: the receiving agent gets it exactly as before, old clients render it as a normal message, and the card shows it as the expanded markdown body. Wire shape on POST /api/v1/send-message:

{ "messageType": "event", "eventMeta": { "source": "n8n", "title": "...", "peek": "...", "payload": { } } }

Combine with Sender = User when the receiving agent should wake on the event — the usual case for machine-delivered traffic.

BGOS Trigger (Webhook Node)

Starts workflows when BGOS events occur. Supports 17 event types:

• message, edited_message, voice_message, reply_message
• new_chat, chat_renamed, chat_deleted
• new_assistant, assistant_updated, assistant_deleted
• voice_started, voice_ended
• message_deleted, button_clicked
• user_created, user_updated
• ask_response (one event per answered/skipped ask_user_input question)

Credentials

Configure with your BGOS backend URL and optional API key:

• Base URL: Your BGOS backend URL (default: https://api.brandgrowthos.ai)
• API Key: Optional, for future authentication support

Setup

In BGOS Backend

Set the FORWARDER_WEBHOOK_URL environment variable to your n8n webhook URL:

FORWARDER_WEBHOOK_URL=https://your-n8n-instance.com/webhook/bgos-webhook

In n8n

1. Install the package: pnpm install n8n-nodes-bgos (or add it in Settings → Community nodes).
2. Finding the trigger: Click + (Add node), search for "BGOS Trigger" and pick the one with the cube icon (community node). You can use it as the workflow trigger or add it from the canvas.
3. Configure BGOS API credentials (from the node’s credential dropdown) with your backend Base URL.
4. Use the BGOS Trigger node to receive events and the BGOS node to perform actions.

Development

pnpm install
pnpm build

License

MIT