@ihazz/bitrix24 0.2.5 → 1.0.1

package/README.md

@@ -1,18 +1,17 @@
 # @ihazz/bitrix24
 
-OpenClaw channel plugin for Bitrix24 Messenger. Allows using a Bitrix24 chatbot as a communication interface for OpenClaw AI agents.
+OpenClaw channel plugin for Bitrix24 Messenger based on Bot Platform 2.0 (`imbot.v2.*` / `im.v2.*`).
 
-## Features
+## Current Status
 
-- Receive messages from Bitrix24 users via webhook
-- Send responses through the Bitrix24 REST API (`imbot.message.add`)
-- Typing indicator (`imbot.chat.sendTyping`)
-- Markdown to BB-code conversion
-- Interactive keyboard buttons
-- Rate limiting (2 req/sec token-bucket)
-- Webhook deduplication (MESSAGE_ID, 5 min TTL)
-- Access control: open, allowlist, pairing modes
-- Multi-account support (multiple portals)
+- Works with Bitrix24 Bot Platform 2.0
+- Supports direct messages only
+- Supports inbound and outbound media
+- Uses secure default access policy: `webhookUser`
+- Supports optional pairing flow for controlled approval
+- Production recommendation today: one portal per plugin instance
+
+Group chats are intentionally not supported. If the bot is added to a group chat, it sends a short notice and leaves the chat.
 
 ## Installation
 
@@ -20,230 +19,213 @@ OpenClaw channel plugin for Bitrix24 Messenger. Allows using a Bitrix24 chatbot
 openclaw plugins install @ihazz/bitrix24
 ```
 
+Allow the plugin in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["bitrix24"]
+  }
+}
+```
+
 ## Bitrix24 Setup
 
-1. Go to your Bitrix24 portal: **Apps** > **Developer resources** > **Other** > **Inbound webhook**
-2. Name it, e.g. "OpenClaw Bot"
-3. Under **Access permissions**, select scopes:
-   - **`imbot`** — chatbot management (register, send/update messages)
-   - **`im`** — messenger (chats, typing indicator)
-   - **`disk`** — file operations (optional, for future support)
-4. Click **Save**
-5. Copy the **Webhook URL** — it will look like:
-   ```
-   https://your-portal.bitrix24.com/rest/1/abc123xyz456/
-   ```
+Create an inbound webhook in Bitrix24:
+
+1. Open **Apps** > **Developer resources** > **Other** > **Inbound webhook**
+2. Create a webhook for your OpenClaw bot
+3. Grant scopes:
+   - `imbot` — the minimum scope required for full bot operation
+   - `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
 
-> The webhook URL contains authentication (user_id + token) — do not publish or commit it to a repository.
+Example webhook URL:
+
+```text
+https://your-portal.bitrix24.com/rest/1/abc123xyz456/
+```
+
+The webhook URL contains credentials. Do not publish it or commit it to a repository.
 
 ## Configuration
 
-Add to your `openclaw.json`:
+Minimal configuration:
 
 ```json
 {
   "channels": {
     "bitrix24": {
       "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
-      "callbackUrl": "https://your-server.com/hooks/bitrix24",
       "botName": "OpenClaw",
-      "botCode": "openclaw",
-      "dmPolicy": "open",
-      "allowFrom": ["*"],
-      "showTyping": true,
-      "capabilities": ["inlineButtons"]
+      "dmPolicy": "webhookUser",
+      "showTyping": true
     }
   }
 }
 ```
 
-Set allow in plugin section:
+Webhook delivery mode:
+
 ```json
 {
-  "plugins": {
-    "allow": [
-      "bitrix24"
-    ],
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
+      "callbackUrl": "https://your-server.com/hooks/bitrix24",
+      "eventMode": "webhook"
+    }
   }
 }
 ```
-Only `webhookUrl` is required. The gateway will not start without it.
 
-### Configuration Options
+If `eventMode` is omitted, the plugin uses:
+
+- `webhook` when `callbackUrl` is set
+- `fetch` when `callbackUrl` is not set
+
+## Configuration Options
 
 | Parameter | Default | Description |
 |---|---|---|
-| `webhookUrl` | — | Bitrix24 REST webhook URL (**required**) |
-| `callbackUrl` | — | Full public URL for bot EVENT_HANDLER (e.g. `https://your-server.com/hooks/bitrix24`). Path is auto-extracted for route registration. (**required**) |
-| `botName` | `"OpenClaw"` | Bot display name (shown in welcome message) |
-| `botCode` | `"openclaw"` | Unique bot code for `imbot.register` |
-| `dmPolicy` | `"open"` | Access policy: `"open"` / `"allowlist"` / `"pairing"` |
-| `allowFrom` | — | Allowed B24 user IDs (when `dmPolicy: "allowlist"`) |
-| `showTyping` | `true` | Send typing indicator before responding |
-| `streamUpdates` | `false` | Stream response via message updates |
-| `updateIntervalMs` | `10000` | Throttle interval for streaming updates (ms, min 500) |
-| `enabled` | `true` | Whether this account is enabled |
-| `capabilities` | `[]` | Runtime capabilities to enable (see below) |
-
-### Capabilities
-
-The `capabilities` array activates additional runtime features for the AI agent. Add them to the channel config in `openclaw.json`:
+| `webhookUrl` | — | Bitrix24 REST webhook URL. Required. |
+| `callbackUrl` | — | Public HTTPS URL for webhook delivery mode. Required only for `eventMode: "webhook"`. |
+| `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` | `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` | 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
 {
   "channels": {
     "bitrix24": {
-      ...
-      "capabilities": ["inlineButtons"]
+      "webhookUrl": "...",
+      "capabilities": ["reactions"]
     }
   }
 }
 ```
 
-| Capability | Description |
-|---|---|
-| `inlineButtons` | Enables inline keyboard buttons in bot messages. The AI agent will be able to send interactive buttons using `action=send` with `buttons=[[{text, callback_data, style?}]]`. Without this capability the agent will not attempt to generate buttons. |
+The plugin maps standard Unicode emoji (👍, 🔥, 👀, etc.) to Bitrix24 reaction codes automatically. B24 reaction codes (like `like`, `fire`, `eyes`) can also be used directly.
 
-### Access Policies
+### Inline Buttons
 
-- **`"open"`** — any Bitrix24 portal user can message the bot
-- **`"allowlist"`** — only users listed in `allowFrom`:
-  ```json
-  {
-    "dmPolicy": "allowlist",
-    "allowFrom": ["42", "b24:108", "bitrix24:256"]
-  }
-  ```
-  Prefixes `b24:`, `bx24:`, `bitrix24:` are stripped automatically.
-- **`"pairing"`** — pairing mode (work in progress)
-
-### Multi-Account (Multiple Portals)
-
-Connect multiple Bitrix24 portals to a single OpenClaw server:
+To enable agent-driven inline buttons, add `inlineButtons` to the channel capabilities in your OpenClaw config:
 
 ```json
 {
   "channels": {
     "bitrix24": {
-      "webhookUrl": "https://main-portal.bitrix24.com/rest/1/token1/",
-      "botName": "Main Bot",
-      "accounts": {
-        "sales": {
-          "webhookUrl": "https://sales.bitrix24.com/rest/1/token2/",
-          "botName": "Sales Bot",
-          "dmPolicy": "allowlist",
-          "allowFrom": ["10", "20", "30"]
-        },
-        "support": {
-          "webhookUrl": "https://support.bitrix24.com/rest/1/token3/",
-          "botName": "Support Bot"
-        }
-      }
+      "webhookUrl": "...",
+      "capabilities": ["inlineButtons"]
     }
   }
 }
 ```
 
-The root config acts as the `"default"` account. Each entry in `accounts` inherits all root settings and can override any of them.
+The plugin supports two button input forms:
 
-## Network Access
+- native Bitrix24 keyboard payload via `channelData.bitrix24.keyboard`
+- generic OpenClaw button rows via `channelData.telegram.buttons`, which the plugin converts to Bitrix24 `KEYBOARD`
 
-The OpenClaw gateway must be reachable over HTTPS for POST requests from Bitrix24 servers.
+For converted generic buttons:
 
-Default callback URL: `https://your-server.com/hooks/bitrix24`
+- `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
 
-For local development, use ngrok or a similar tool:
+## Access Policies
 
-```bash
-ngrok http 3000
-```
+### `webhookUser`
 
-Use the HTTPS URL from ngrok as the event handler URL in Bitrix24 bot settings.
+Default and recommended mode for production.
 
-## Running (restarting)
+Only the Bitrix24 user whose ID is embedded in the webhook URL may talk to the bot. For a URL like:
 
-```bash
-systemctl restart openclaw
+```text
+https://your-portal.bitrix24.com/rest/42/secret/
 ```
 
-On successful start, logs will show: `Bitrix24 gateway started, webhook at /hooks/bitrix24`
+only user `42` is allowed to use the bot in direct messages.
 
-### Verification
+### `pairing`
 
-1. Open a chat with the bot on your Bitrix24 portal
-2. Send any message
-3. The bot should show a typing indicator and respond
+Pairing mode allows a user to request access and wait for approval through the OpenClaw pairing flow.
 
-### Troubleshooting
+Approval hint:
 
-- Webhook URL is correct and accessible (`webhookUrl`)
-- OpenClaw server is reachable from the internet over HTTPS
-- Scopes `imbot`, `im`, `disk` are enabled in the B24 webhook settings
-- No `QUERY_LIMIT_EXCEEDED` errors in logs (rate limit)
+```bash
+openclaw pairing approve bitrix24 <CODE>
+```
 
-## How It Works
+## Delivery Modes
 
-```
-B24 user sends a message to the bot
-    |
-B24 POSTs to /hooks/bitrix24 (application/x-www-form-urlencoded)
-    |
-InboundHandler parses the request body
-    |
-Event routing:
-  ONIMBOTMESSAGEADD  ->  message processing
-  ONIMBOTJOINCHAT    ->  welcome message
-  ONIMCOMMANDADD     ->  slash command (WIP)
-  ONIMBOTDELETE      ->  cleanup
-    |
-Deduplication (MESSAGE_ID, 5 min TTL)
-    |
-Access control (senderId vs. dmPolicy + allowFrom)
-    |
-Normalize to MsgContext -> pass to OpenClaw AI agent
-    |
-OpenClaw processes -> calls outbound.sendText()
-    |
-SendService:
-  imbot.chat.sendTyping  ->  typing indicator
-  imbot.message.add      ->  response (Markdown -> BB-code)
-```
+### `fetch`
+
+- No public callback endpoint required
+- Events are polled with `imbot.v2.Event.get`
+- Best default for private or internal deployments
+
+### `webhook`
+
+- Requires public HTTPS `callbackUrl`
+- Bitrix24 sends events directly to OpenClaw
+- The plugin accepts both JSON and form-encoded webhook bodies
 
-### Handled Events
+## Supported Behavior
 
-| Event | Plugin Action |
-|---|---|
-| `ONIMBOTMESSAGEADD` | Incoming message -> normalize -> AI agent |
-| `ONIMBOTJOINCHAT` | Bot added to chat -> welcome message |
-| `ONIMCOMMANDADD` | Slash command (stub) |
-| `ONAPPINSTALL` | App installed (stub) |
-| `ONIMBOTDELETE` | Bot removed -> cleanup |
+- Direct messages
+- Typing indicators
+- Text replies with BBCode conversion
+- 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`
+- Slash command registration via `imbot.v2.Command.*`
+- Deduplication for repeated deliveries
+- Rate limiting for Bitrix24 API calls
 
-### Built-in Safeguards
+## Not Supported
 
-- **Rate limiter**: token-bucket, 2 requests/sec (B24 webhook limit)
-- **Deduplication**: B24 retries webhooks if it doesn't get a 200 in time — the plugin stores MESSAGE_IDs for 5 minutes
-- **Text conversion**: B24 uses BB-code, not Markdown — automatic conversion (`**bold**` -> `[B]bold[/B]`, etc.)
+- Group chat conversations
+- Production-ready multi-account operation in one process
 
-## Customization
+There is already account-config scaffolding in the plugin, but the current production recommendation is still one active Bitrix24 portal per instance.
 
-### Bot Avatar
+## Verification
 
-The default bot avatar is stored in `src/bot-avatar.ts` as a base64-encoded JPEG string. To change the avatar:
+1. Start OpenClaw with the plugin enabled.
+2. Open a direct chat with the bot in Bitrix24.
+3. Send a message.
+4. Verify that the bot shows typing and returns a response.
+5. If `dmPolicy` is `webhookUser`, verify that only the webhook owner can talk to the bot.
 
-1. Prepare a JPEG or PNG image (recommended: 200×200 px, ≤ 50 KB)
-2. Convert it to base64
-3. Replace the `DEFAULT_AVATAR_BASE64` value in `src/bot-avatar.ts`
-4. Rebuild and redeploy
+## Troubleshooting
 
-The avatar can also be overridden per-account via the `botAvatar` config option (base64 string).
+- Verify `webhookUrl` is valid and active.
+- If you use `eventMode: "webhook"`, verify `callbackUrl` is reachable from the internet over HTTPS.
+- 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.
 
 ## Development
 
 ```bash
 npm install
-npm test          # run tests
-npm run build     # compile TypeScript
+npm test
+npm run build
 ```
 
 ## License

package/index.ts

@@ -8,10 +8,47 @@ interface OpenClawPluginApi {
   registerChannel: (opts: { plugin: typeof bitrix24Plugin }) => void;
   registerHttpRoute: (params: {
     path: string;
+    auth?: 'plugin';
     handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
   }) => void;
 }
 
+export function collectBitrix24CallbackPaths(config: Record<string, unknown>): string[] {
+  const channels = config?.channels as Record<string, Record<string, unknown>> | undefined;
+  const bitrix24 = channels?.bitrix24 as {
+    callbackUrl?: string;
+    accounts?: Record<string, { callbackUrl?: string }>;
+  } | undefined;
+
+  const callbackUrls: string[] = [];
+  if (typeof bitrix24?.callbackUrl === 'string') {
+    callbackUrls.push(bitrix24.callbackUrl);
+  }
+
+  for (const account of Object.values(bitrix24?.accounts ?? {})) {
+    if (typeof account?.callbackUrl === 'string') {
+      callbackUrls.push(account.callbackUrl);
+    }
+  }
+
+  const paths: string[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const callbackUrl of callbackUrls) {
+    try {
+      const path = new URL(callbackUrl).pathname;
+      if (!seenPaths.has(path)) {
+        seenPaths.add(path);
+        paths.push(path);
+      }
+    } catch {
+      console.warn(`[bitrix24] Invalid callbackUrl "${callbackUrl}", skipping HTTP route`);
+    }
+  }
+
+  return paths;
+}
+
 /**
  * OpenClaw Bitrix24 Channel Plugin
  *
@@ -28,16 +65,14 @@ export default {
 
     api.registerChannel({ plugin: bitrix24Plugin });
 
-    // Register HTTP webhook route — derive path from callbackUrl
-    const channels = api.config?.channels as Record<string, Record<string, unknown>> | undefined;
-    const callbackUrl = channels?.bitrix24?.callbackUrl as string | undefined;
-    const callbackPath = callbackUrl ? new URL(callbackUrl).pathname : '/hooks/bitrix24';
-
-    api.registerHttpRoute({
-      path: callbackPath,
-      handler: async (req: IncomingMessage, res: ServerResponse) => {
-        await handleWebhookRequest(req, res);
-      },
-    });
+    for (const callbackPath of collectBitrix24CallbackPaths(api.config)) {
+      api.registerHttpRoute({
+        path: callbackPath,
+        auth: 'plugin',
+        handler: async (req: IncomingMessage, res: ServerResponse) => {
+          await handleWebhookRequest(req, res);
+        },
+      });
+    }
   },
 };

package/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "bitrix24",
   "channels": ["bitrix24"],
+  "skills": ["skills/bitrix24"],
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

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

package/skills/bitrix24/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: bitrix24
+description: "Bitrix24 Messenger ops via the message tool (channel=bitrix24)."
+metadata: { "openclaw": { "emoji": "💬", "requires": { "config": ["channels.bitrix24.webhookUrl"] } } }
+allowed-tools: ["message"]
+---
+
+# Bitrix24 (Via `message`)
+
+Use the `message` tool. No provider-specific `bitrix24` tool exposed to the agent.
+
+## Musts
+
+- Always: `channel: "bitrix24"`.
+- The bot works in direct messages only (no group chats).
+
+## Common Actions (Examples)
+
+Send message:
+
+```json
+{
+  "action": "send",
+  "channel": "bitrix24",
+  "message": "Hello!"
+}
+```
+
+React to the current (last received) message:
+
+```json
+{
+  "action": "react",
+  "channel": "bitrix24",
+  "emoji": "👍"
+}
+```
+
+- When `messageId` is **omitted**, the reaction is applied to the current inbound message automatically.
+- `emoji` can be a standard Unicode emoji (👍, 🔥, ❤️, 😂, 😢, 😮, 👀, 🎉, 🤔, 👎, etc.) or a Bitrix24 reaction code (`like`, `fire`, `heart`, `laugh`, `cry`, `wonder`, `eyes`, `hooray`, `think`, `dislike`).
+- To react to a **specific** message, pass `"messageId": "<numeric id>"`.
+- To remove a reaction, add `"remove": true`.
+
+Remove a reaction:
+
+```json
+{
+  "action": "react",
+  "channel": "bitrix24",
+  "emoji": "👍",
+  "remove": true
+}
+```
+
+## Reactions Guidance
+
+When you see a message from a Bitrix24 user, you can react to acknowledge it before (or instead of) sending a text reply. Common patterns:
+
+- React with 👍 to acknowledge a request.
+- React with 👀 to indicate you're looking into something.
+- React with ✅ or 🎉 when a task is completed.
+- React with 🤔 if you need to think about the request.
+
+**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.