@ihazz/bitrix24 1.0.0 → 1.0.1

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.1",
   "description": "Bitrix24 Messenger channel for OpenClaw",
   "type": "module",
   "main": "./dist/index.js",

package/skills/bitrix24/SKILL.md

@@ -63,8 +63,34 @@ When you see a message from a Bitrix24 user, you can react to acknowledge it bef
 
 **Important:** Do NOT invent or guess messageId values. Either omit `messageId` to react to the current message, or use a messageId that was explicitly provided to you.
 
+## Inline Keyboard Buttons
+
+You can attach inline buttons to a message. The `callback_data` value is sent back when the user taps the button.
+
+```json
+{
+  "action": "send",
+  "channel": "bitrix24",
+  "message": "Выберите вариант:",
+  "buttons": [
+    [
+      { "text": "Да", "callback_data": "Да" },
+      { "text": "Нет", "callback_data": "Нет" }
+    ]
+  ]
+}
+```
+
+**Important rules for buttons:**
+
+- `callback_data` **must match** the button `text` exactly — when the user taps a button, `callback_data` is sent as a message in the chat. If they differ, the user sees confusing text.
+- Write button labels in the **same language as the conversation** (e.g. Russian if the user writes in Russian).
+- Use `"style": "primary"` for the recommended option, `"style": "danger"` for destructive actions.
+- Each inner array is one row of buttons.
+
 ## 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,7 +552,7 @@ export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
           b24Btn.COMMAND_PARAMS = parts.slice(1).join(' ');
         }
       } else if (btn.callback_data) {
-        b24Btn.ACTION = 'PUT';
+        b24Btn.ACTION = 'SEND';
         b24Btn.ACTION_VALUE = btn.callback_data;
       }
 
@@ -1152,11 +1152,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 +1167,56 @@ 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 ?? '').trim();
+        if (!to) 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

package/tests/channel.test.ts

@@ -105,7 +105,7 @@ describe('convertButtonsToKeyboard', () => {
     const btn = kb[0];
     if (isButton(btn)) {
       expect(btn.COMMAND).toBeUndefined();
-      expect(btn.ACTION).toBe('PUT');
+      expect(btn.ACTION).toBe('SEND');
       expect(btn.ACTION_VALUE).toBe('some_value');
     }
   });