@ihazz/bitrix24 1.0.0 → 1.0.2

package/README.md

@@ -37,7 +37,7 @@ Create an inbound webhook in Bitrix24:
 2. Create a webhook for your OpenClaw bot
 3. Grant scopes:
    - `imbot` — the minimum scope required for full bot operation
-   - `im` — additionally required only for `agentMode`, so the bot can read incoming messages addressed to the webhook owner
+   - `im` — reserved for future `agentMode` support; `agentMode` is not production-ready yet and will be available in future versions
    - you may also grant any extra scopes beyond this set if they are needed for your Bitrix24 scenarios
 4. Save the webhook and copy the URL
 
@@ -94,15 +94,17 @@ If `eventMode` is omitted, the plugin uses:
 | `eventMode` | auto | `fetch` or `webhook`. Auto-selects from `callbackUrl` when omitted. |
 | `botName` | `"OpenClaw"` | Bot display name. |
 | `botCode` | auto | Optional explicit bot code. If omitted, the plugin registers the bot as `openclaw_<webhookUserId>`, and if that code is occupied it tries `openclaw_<webhookUserId>_2`, `_3`, and so on. |
-| `botToken` | derived from `webhookUrl` | Optional explicit bot token for `imbot.v2.Bot.*`. If omitted, it is derived automatically from `webhookUrl`. |
+| `botToken` | `md5(webhookUrl)` | Bot token for `imbot.v2` authentication (32-char hex string). If omitted, derived as `md5(webhookUrl)`. **Strongly recommended to set explicitly** if your `webhookUrl` may change (e.g. ngrok, dynamic DNS) — otherwise the plugin loses control of the previously registered bot. You can find the token in the Bitrix24 admin panel or compute it as `md5` of the original webhook URL. |
 | `botAvatar` | — | Optional base64 avatar override. |
 | `dmPolicy` | `"webhookUser"` | Access policy: `webhookUser` or `pairing`. |
 | `showTyping` | `true` | Sends typing indicator before response. |
 | `enabled` | `true` | Enables or disables the account. |
-| `agentMode` | `false` | Enables additional user-event integration. Requires `im` scope. |
+| `agentMode` | `false` | Reserved for future user-event integration. Not working yet; planned for future versions. |
 | `pollingIntervalMs` | `3000` | Base poll interval for `fetch` mode. |
 | `pollingFastIntervalMs` | `100` | Fast follow-up poll interval when more events are pending. |
 
+### Agent-Driven Reactions
+
 To enable agent-driven reactions, add `reactions` to the channel capabilities in your OpenClaw config:
 
 ```json
@@ -118,6 +120,32 @@ To enable agent-driven reactions, add `reactions` to the channel capabilities in
 
 The plugin maps standard Unicode emoji (👍, 🔥, 👀, etc.) to Bitrix24 reaction codes automatically. B24 reaction codes (like `like`, `fire`, `eyes`) can also be used directly.
 
+### Inline Buttons
+
+To enable agent-driven inline buttons, add `inlineButtons` to the channel capabilities in your OpenClaw config:
+
+```json
+{
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "...",
+      "capabilities": ["inlineButtons"]
+    }
+  }
+}
+```
+
+The plugin supports two button input forms:
+
+- native Bitrix24 keyboard payload via `channelData.bitrix24.keyboard`
+- generic OpenClaw button rows via `channelData.telegram.buttons`, which the plugin converts to Bitrix24 `KEYBOARD`
+
+For converted generic buttons:
+
+- `callback_data` starting with `/` becomes a native Bitrix24 slash command button
+- any other `callback_data` becomes `ACTION=PUT`
+- `primary`, `attention`, and `danger` button styles are mapped to Bitrix24 color tokens
+
 ## Access Policies
 
 ### `webhookUser`
@@ -161,7 +189,7 @@ openclaw pairing approve bitrix24 <CODE>
 - Direct messages
 - Typing indicators
 - Text replies with BBCode conversion
-- Inline keyboard buttons
+- Inline keyboard buttons (`channelData.bitrix24.keyboard` and converted generic button rows)
 - Reactions (agent can add/remove reactions on messages via `imbot.v2.Chat.Message.Reaction.*`)
 - File upload to chat via `imbot.v2.File.upload`
 - File download via `imbot.v2.File.download`
@@ -188,7 +216,7 @@ There is already account-config scaffolding in the plugin, but the current produ
 
 - Verify `webhookUrl` is valid and active.
 - If you use `eventMode: "webhook"`, verify `callbackUrl` is reachable from the internet over HTTPS.
-- If `agentMode` is enabled, verify the webhook also has `im` scope.
+- Do not rely on `agentMode` yet. It is not working in the current release and is planned for future versions.
 - Do not expect the bot to work in group chats.
 - If file transfer fails, verify the file size and Bitrix24-side availability of the attachment.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihazz/bitrix24",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Bitrix24 Messenger channel for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",

package/skills/bitrix24/SKILL.md

@@ -66,5 +66,6 @@ When you see a message from a Bitrix24 user, you can react to acknowledge it bef
 ## Writing Style (Bitrix24)
 
 - Direct, professional, moderate length.
+- **Always reply in the same language the user writes in.** If the user writes in Russian, reply in Russian. If in English, reply in English.
 - Bitrix24 uses BBCode for formatting (conversion is automatic).
 - Inline keyboard buttons are supported for interactive responses.

package/src/channel.ts

@@ -552,8 +552,10 @@ export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
           b24Btn.COMMAND_PARAMS = parts.slice(1).join(' ');
         }
       } else if (btn.callback_data) {
-        b24Btn.ACTION = 'PUT';
-        b24Btn.ACTION_VALUE = btn.callback_data;
+        b24Btn.ACTION = 'SEND';
+        // Always use button text as ACTION_VALUE so the user sees readable text in chat,
+        // not opaque English identifiers like "answer_piano"
+        b24Btn.ACTION_VALUE = btn.text;
       }
 
       if (btn.style === 'primary') {
@@ -595,6 +597,39 @@ export function extractKeyboardFromPayload(
   return undefined;
 }
 
+/**
+ * Extract inline button JSON embedded in message text by the agent.
+ *
+ * Agents (especially GPT-4o) sometimes embed button markup directly in text
+ * as `[[{...},{...}]]` instead of using tool call parameters.
+ * This function detects such patterns, extracts the keyboard, and returns
+ * cleaned text without the JSON fragment.
+ */
+export function extractInlineButtonsFromText(
+  text: string,
+): { cleanText: string; keyboard: B24Keyboard } | undefined {
+  // Match [[...]] containing JSON array of button objects
+  const match = text.match(/\[\[\s*(\{[\s\S]*?\}(?:\s*,\s*\{[\s\S]*?\})*)\s*\]\]/);
+  if (!match) return undefined;
+
+  try {
+    const parsed = JSON.parse(`[${match[1]}]`);
+    if (!Array.isArray(parsed) || parsed.length === 0) return undefined;
+
+    // Validate it looks like button objects (must have "text" property)
+    if (!parsed.every((b: unknown) => typeof b === 'object' && b !== null && 'text' in b)) return undefined;
+
+    // Wrap in rows array (single row)
+    const buttons: ChannelButton[][] = [parsed as ChannelButton[]];
+    const keyboard = convertButtonsToKeyboard(buttons);
+    const cleanText = text.replace(match[0], '').trim();
+
+    return { cleanText, keyboard };
+  } catch {
+    return undefined;
+  }
+}
+
 function normalizeCommandReplyPayload(params: {
   commandName: string;
   commandParams: string;
@@ -1066,7 +1101,17 @@ export const bitrix24Plugin = {
     }) => {
       const sendCtx = resolveOutboundSendCtx(ctx);
       if (!sendCtx || !gatewayState) throw new Error('Bitrix24 gateway not started');
-      const result = await gatewayState.sendService.sendText(sendCtx, ctx.text);
+
+      // Agent may embed button JSON in text as [[{...}]]
+      let text = ctx.text;
+      let keyboard: B24Keyboard | undefined;
+      const extracted = extractInlineButtonsFromText(text);
+      if (extracted) {
+        text = extracted.cleanText;
+        keyboard = extracted.keyboard;
+      }
+
+      const result = await gatewayState.sendService.sendText(sendCtx, text, keyboard ? { keyboard } : undefined);
       return { messageId: String(result.messageId ?? '') };
     },
 
@@ -1152,11 +1197,11 @@ export const bitrix24Plugin = {
 
   actions: {
     listActions: (_params: { cfg: Record<string, unknown> }): string[] => {
-      return ['react'];
+      return ['react', 'send'];
     },
 
     supportsAction: (params: { action: string }): boolean => {
-      return params.action === 'react';
+      return params.action === 'react' || params.action === 'send';
     },
 
     handleAction: async (ctx: {
@@ -1167,6 +1212,59 @@ export const bitrix24Plugin = {
       params: Record<string, unknown>;
       [key: string]: unknown;
     }): Promise<Record<string, unknown> | null> => {
+      // ─── Send with buttons ──────────────────────────────────────────────
+      if (ctx.action === 'send') {
+        // Only intercept send when buttons are present; otherwise let gateway handle normally
+        const rawButtons = ctx.params.buttons;
+        if (!rawButtons) return null;
+
+        const { config } = resolveAccount(ctx.cfg, ctx.accountId);
+        if (!config.webhookUrl || !gatewayState) return null;
+
+        const bot = gatewayState.bot;
+        const to = String(ctx.params.to ?? ctx.to ?? '').trim();
+        if (!to) {
+          defaultLogger.warn('handleAction send: no "to" in params or ctx, falling back to gateway');
+          return null;
+        }
+
+        const sendCtx: SendContext = { webhookUrl: config.webhookUrl, bot, dialogId: to };
+        const message = String(ctx.params.message ?? '').trim();
+
+        // Parse buttons: may be array or JSON string
+        let buttons: ChannelButton[][] | undefined;
+        try {
+          const parsed = typeof rawButtons === 'string' ? JSON.parse(rawButtons) : rawButtons;
+          if (Array.isArray(parsed)) buttons = parsed;
+        } catch {
+          // invalid buttons JSON — send without keyboard
+        }
+
+        const keyboard = buttons?.length ? convertButtonsToKeyboard(buttons) : undefined;
+
+        const toolResult = (payload: Record<string, unknown>) => ({
+          content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+          details: payload,
+        });
+
+        try {
+          const result = await gatewayState.sendService.sendText(
+            sendCtx, message || ' ', keyboard ? { keyboard } : undefined,
+          );
+          return toolResult({
+            channel: 'bitrix24',
+            to,
+            via: 'direct',
+            mediaUrl: null,
+            result: { messageId: String(result.messageId ?? '') },
+          });
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          return toolResult({ ok: false, error: errMsg });
+        }
+      }
+
+      // ─── React ────────────────────────────────────────────────────────────
       if (ctx.action !== 'react') return null;
 
       // Helper: wrap payload as gateway-compatible tool result
@@ -1453,8 +1551,19 @@ export const bitrix24Plugin = {
                     }
                   }
                   if (payload.text) {
-                    const keyboard = extractKeyboardFromPayload(payload);
-                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                    let text = payload.text;
+                    let keyboard = extractKeyboardFromPayload(payload);
+
+                    // Fallback: agent may embed button JSON in text as [[{...}]]
+                    if (!keyboard) {
+                      const extracted = extractInlineButtonsFromText(text);
+                      if (extracted) {
+                        text = extracted.cleanText;
+                        keyboard = extracted.keyboard;
+                      }
+                    }
+
+                    await sendService.sendText(sendCtx, text, keyboard ? { keyboard } : undefined);
                   }
                 },
                 onReplyStart: async () => {

package/tests/channel.test.ts

@@ -97,7 +97,7 @@ describe('convertButtonsToKeyboard', () => {
     }
   });
 
-  it('converts non-slash callback_data to ACTION PUT', () => {
+  it('converts non-slash callback_data to ACTION SEND with text as value', () => {
     const kb = convertButtonsToKeyboard([
       [{ text: 'Click me', callback_data: 'some_value' }],
     ]);
@@ -105,8 +105,8 @@ describe('convertButtonsToKeyboard', () => {
     const btn = kb[0];
     if (isButton(btn)) {
       expect(btn.COMMAND).toBeUndefined();
-      expect(btn.ACTION).toBe('PUT');
-      expect(btn.ACTION_VALUE).toBe('some_value');
+      expect(btn.ACTION).toBe('SEND');
+      expect(btn.ACTION_VALUE).toBe('Click me');
     }
   });