n8n-nodes-bgos 1.3.1 → 1.3.4

package/README.md

@@ -16,6 +16,37 @@ Perform operations on the BGOS platform:
 | **User** | Get or Create, Update |
 | **Scheduled Task** | Get, Get User Tasks, Delete |
 
+#### Render Mode — Inline Buttons vs. Modal Pop-Under
+
+Two ways the BGOS app renders buttons that come with a message:
+
+| Mode | Looks Like | When It Makes Sense |
+|---|---|---|
+| **Inline** (default on `sendMessage`) | Telegram-style chips inside a warm off-white card below the message. Skip (top-left), "✍ Custom reply" footer link. Stays clickable forever — user can answer now, tomorrow, or never. | The message is **not** a direct reply to something the user just typed: cron, scheduler, external webhook, unprompted check-in. Single question, up to 6 labeled choices. |
+| **Modal** (default on `askUserInput`) | Bottom sheet / pop-under that demands attention. Multi-question carousel, free-text fallback, skip-all. | Active back-and-forth conversation — user just sent a message and you need their answer to continue. Also use for multi-question flows. |
+
+**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.

package/dist/nodes/BGOSAction/BGOSAction.node.js

@@ -7,7 +7,7 @@ class BGOSAction {
     description = {
         displayName: 'BGOS Action',
         name: 'bgosAction',
-        icon: 'file:bgos.svg',
+        icon: 'file:bgos-icon.svg',
         group: ['transform'],
         version: 1,
         subtitle: '={{$parameter["resource"] + ": " + $parameter["operation"]}}',
@@ -228,6 +228,17 @@ class BGOSAction {
                         placeholder: '[{"label":"Yes","value":"yes"},{"label":"No","value":"no"}]',
                         description: 'JSON array of button options to display with the message',
                     },
+                    {
+                        displayName: 'Render Mode',
+                        name: 'renderMode',
+                        type: 'options',
+                        default: 'inline',
+                        options: [
+                            { name: 'Inline buttons (Telegram-style, asynchronous)', value: 'inline' },
+                            { name: 'Modal pop-under (interactive, blocks UI)', value: 'modal' },
+                        ],
+                        description: 'Rule: If the message is NOT a direct reply to something the user just typed — cron, scheduler, external webhook, unprompted check-in — use INLINE. If the user just sent a message within the last ~2 min and you want their full attention, MODAL is acceptable. When in doubt, pick INLINE — it never interrupts. Max 6 options for inline.',
+                    },
                 ],
             },
             // ── Delete a Message ──────────────────────────────────────────────────
@@ -340,6 +351,18 @@ class BGOSAction {
                 description: 'Whether the node should block until every question is answered (or the timeout expires) and return structured answers. When disabled, the node returns immediately after posting; subscribe to the Ask Response event in a BGOS Trigger to receive each answer.',
                 displayOptions: { show: { resource: ['message'], operation: ['askUserInput'] } },
             },
+            {
+                displayName: 'Render Mode',
+                name: 'askRenderMode',
+                type: 'options',
+                default: 'modal',
+                options: [
+                    { name: 'Modal pop-under (interactive, blocks UI)', value: 'modal' },
+                    { name: 'Inline buttons (Telegram-style, asynchronous)', value: 'inline' },
+                ],
+                description: 'MODAL is the default because askUserInput is typically used mid-conversation. Switch to INLINE if this ask is triggered by cron/schedule/external webhook, or if you do NOT want to interrupt the user. Note: only MODAL supports multi-question carousel, free-text, and skip-all. INLINE renders 1 question with up to 6 chips plus a "Custom reply" / "Skip" footer.',
+                displayOptions: { show: { resource: ['message'], operation: ['askUserInput'] } },
+            },
             {
                 displayName: 'Additional Fields',
                 name: 'askAdditionalFields',
@@ -569,6 +592,9 @@ class BGOSAction {
                     nodeParams.fileId = String(additionalFields.fileId ?? '');
                     nodeParams.sender = String(additionalFields.sender ?? 'assistant');
                     nodeParams.options = String(additionalFields.options ?? '');
+                    nodeParams.renderMode = additionalFields.renderMode
+                        ? String(additionalFields.renderMode)
+                        : 'inline';
                 }
                 if (operation === 'deleteMessage') {
                     nodeParams.deleteMessageId = String(this.getNodeParameter('deleteMessageId', i, '') ?? '');
@@ -577,6 +603,7 @@ class BGOSAction {
                     nodeParams.chatId = String(this.getNodeParameter('chatId', i, '') ?? '');
                     nodeParams.userId = String(this.getNodeParameter('askUserId', i, '') ?? '');
                     nodeParams.waitForAnswers = Boolean(this.getNodeParameter('waitForAnswers', i, true));
+                    nodeParams.renderMode = String(this.getNodeParameter('askRenderMode', i, 'modal') ?? 'modal');
                     const askQuestionsRaw = this.getNodeParameter('askQuestions', i, {});
                     const questions = (askQuestionsRaw.question ?? []).map((q) => ({
                         text: String(q.text ?? '').trim(),

package/dist/nodes/BGOSAction/handler/eventHandler.d.ts

@@ -37,6 +37,7 @@ type NodeParams = {
     waitForAnswers?: boolean;
     askTimeoutSeconds?: number;
     askPollIntervalMs?: number;
+    renderMode?: string;
     [key: string]: unknown;
 };
 export declare function handleEventByType(this: IExecuteFunctions, eventType: string, eventData: Record<string, unknown>, nodeParams: NodeParams): Promise<unknown>;

package/dist/nodes/BGOSAction/handler/eventHandler.js

@@ -50,6 +50,10 @@ async function handleEventByType(eventType, eventData, nodeParams) {
             else if (Array.isArray(eventData.options)) {
                 buttonOptions = eventData.options;
             }
+            const renderMode = (nodeParams.renderMode
+                ?? eventData.renderMode
+                ?? eventData.render_mode
+                ?? 'inline');
             return await techWebhook_1.sendMessageToBackend.call(this, apiOptions, {
                 assistantId: assistantId,
                 chatId: chatId,
@@ -57,6 +61,7 @@ async function handleEventByType(eventType, eventData, nodeParams) {
                 text,
                 options: buttonOptions,
                 files,
+                renderMode,
                 isCode: (eventData.isCode ?? message?.isCode ?? null),
                 artifactCode: (eventData.artifactCode ?? message?.artifactCode ?? null),
                 isArticle: (eventData.isArticle ?? message?.isArticle ?? null),
@@ -108,6 +113,10 @@ async function handleEventByType(eventType, eventData, nodeParams) {
                 if (!q.options.length)
                     throw new Error(`Question ${idx + 1}: at least one option is required.`);
             }
+            const renderMode = (nodeParams.renderMode
+                ?? eventData.renderMode
+                ?? eventData.render_mode
+                ?? 'modal');
             // Post each question. The first call's response carries the
             // backend-generated askId; reuse it for the rest so they group into
             // one carousel/sheet on the frontend.
@@ -124,6 +133,7 @@ async function handleEventByType(eventType, eventData, nodeParams) {
                     allowFreeText: q.allowFreeText,
                     allowSkip: q.allowSkip,
                     options: q.options,
+                    renderMode,
                 });
                 postedIds.push(posted.id);
                 if (!askId && posted.askId)

package/dist/nodes/BGOSAction/techWebhook.d.ts

@@ -25,6 +25,7 @@ export declare function sendMessageToBackend(this: IExecuteFunctions, options: B
     text?: string | null;
     options?: unknown[];
     files?: unknown[];
+    renderMode?: string | null;
     isCode?: boolean | null;
     artifactCode?: string | null;
     isArticle?: boolean | null;
@@ -67,6 +68,7 @@ export declare function postAskQuestion(this: IExecuteFunctions, options: BgosAp
         label: string;
         value: string;
     }>;
+    renderMode?: string | null;
 }): Promise<AskQuestionPosted>;
 export interface ChatMessageEntry {
     message: {

package/dist/nodes/BGOSAction/techWebhook.js

@@ -117,6 +117,8 @@ async function sendMessageToBackend(options, payload) {
         options: payload.options ?? [],
         files: payload.files ?? [],
     };
+    if (payload.renderMode)
+        body.renderMode = payload.renderMode;
     return this.helpers.httpRequest({
         method: 'POST',
         url,
@@ -148,6 +150,8 @@ async function postAskQuestion(options, payload) {
     };
     if (payload.askId)
         body.askId = payload.askId;
+    if (payload.renderMode)
+        body.renderMode = payload.renderMode;
     const result = (await this.helpers.httpRequest({
         method: 'POST',
         url,

package/dist/nodes/Bgos/Bgos.node.js

@@ -52,7 +52,7 @@ class Bgos {
     description = {
         displayName: 'BGOS',
         name: 'bgos',
-        icon: 'file:bgos.svg',
+        icon: 'file:bgos-icon.svg',
         group: ['transform'],
         version: 1,
         subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',

package/dist/nodes/BgosTrigger/BgosTrigger.node.js

@@ -26,7 +26,7 @@ class BgosTrigger {
     description = {
         displayName: 'BGOS Trigger',
         name: 'bgosTrigger',
-        icon: 'file:bgos.svg',
+        icon: 'file:bgos-icon.svg',
         group: ['trigger'],
         version: 1,
         subtitle: '={{$parameter["updates"]}}',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-bgos",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "description": "n8n community nodes for BGOS (Brand Growth OS) - AI assistant chat platform",
   "keywords": [
     "n8n-community-node-package",