@ihazz/bitrix24 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shelenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# @ihazz/bitrix24
+
+OpenClaw channel plugin for Bitrix24 Messenger. Allows using a Bitrix24 chatbot as a communication interface for OpenClaw AI agents.
+
+## Features
+
+- 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)
+
+## Installation
+
+```bash
+openclaw plugins install @ihazz/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/
+   ```
+
+> The webhook URL contains authentication (user_id + token) — do not publish or commit it to a repository.
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
+      "botName": "OpenClaw",
+      "botCode": "openclaw",
+      "callbackPath": "/hooks/bitrix24",
+      "dmPolicy": "open",
+      "showTyping": true
+    }
+  }
+}
+```
+
+Only `webhookUrl` is required. The gateway will not start without it.
+
+### Configuration Options
+
+| Parameter | Default | Description |
+|---|---|---|
+| `webhookUrl` | — | Bitrix24 REST webhook URL (**required**) |
+| `botName` | `"OpenClaw"` | Bot display name (shown in welcome message) |
+| `botCode` | `"openclaw"` | Unique bot code for `imbot.register` |
+| `callbackPath` | `"/hooks/bitrix24"` | Webhook endpoint path for incoming B24 events |
+| `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 |
+
+### Access Policies
+
+- **`"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:
+
+```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"
+        }
+      }
+    }
+  }
+}
+```
+
+The root config acts as the `"default"` account. Each entry in `accounts` inherits all root settings and can override any of them.
+
+## Network Access
+
+The OpenClaw gateway must be reachable over HTTPS for POST requests from Bitrix24 servers.
+
+Default callback URL: `https://your-server.com/hooks/bitrix24`
+
+For local development, use ngrok or a similar tool:
+
+```bash
+ngrok http 3000
+```
+
+Use the HTTPS URL from ngrok as the event handler URL in Bitrix24 bot settings.
+
+## Running
+
+```bash
+openclaw start
+```
+
+On successful start, logs will show: `Bitrix24 gateway started, webhook at /hooks/bitrix24`
+
+### Verification
+
+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
+
+### Troubleshooting
+
+- 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)
+
+## How It Works
+
+```
+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)
+```
+
+### Handled Events
+
+| 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 |
+
+### Built-in Safeguards
+
+- **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.)
+
+## Development
+
+```bash
+npm install
+npm test          # run tests
+npm run build     # compile TypeScript
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,42 @@
+import { bitrix24Plugin, handleWebhookRequest } from './src/channel.js';
+import { setBitrix24Runtime } from './src/runtime.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+interface OpenClawPluginApi {
+  config: Record<string, unknown>;
+  runtime: unknown;
+  registerChannel: (opts: { plugin: typeof bitrix24Plugin }) => void;
+  registerHttpRoute: (params: {
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+  }) => void;
+}
+
+/**
+ * OpenClaw Bitrix24 Channel Plugin
+ *
+ * Connects Bitrix24 Messenger as a communication channel for OpenClaw agents.
+ * Users can chat with the AI assistant through Bitrix24's built-in messenger.
+ */
+export default {
+  id: 'bitrix24',
+  name: 'Bitrix24 Channel',
+  description: 'Bitrix24 Messenger channel for OpenClaw',
+
+  register(api: OpenClawPluginApi) {
+    setBitrix24Runtime(api.runtime as { logger: { info: (...args: unknown[]) => void; warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void; debug: (...args: unknown[]) => void }; [key: string]: unknown });
+
+    api.registerChannel({ plugin: bitrix24Plugin });
+
+    // Register HTTP webhook route on the OpenClaw gateway
+    const channels = api.config?.channels as Record<string, Record<string, unknown>> | undefined;
+    const callbackPath = (channels?.bitrix24?.callbackPath as string) ?? '/hooks/bitrix24';
+
+    api.registerHttpRoute({
+      path: callbackPath,
+      handler: async (req: IncomingMessage, res: ServerResponse) => {
+        await handleWebhookRequest(req, res);
+      },
+    });
+  },
+};

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "bitrix24",
+  "channels": ["bitrix24"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ihazz/bitrix24",
+  "version": "0.1.3",
+  "description": "Bitrix24 Messenger channel for OpenClaw",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "bitrix24",
+      "label": "Bitrix24",
+      "selectionLabel": "Bitrix24 (Messenger)",
+      "docsPath": "/channels/bitrix24",
+      "docsLabel": "bitrix24",
+      "blurb": "Connect to Bitrix24 Messenger via chat bot REST API.",
+      "order": 70,
+      "aliases": [
+        "b24",
+        "bx24"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "qs": "^6.13.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/qs": "^6.9.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}

package/src/access-control.ts

@@ -0,0 +1,40 @@
+import type { Bitrix24AccountConfig } from './types.js';
+
+/**
+ * Normalize an allowFrom entry — strip platform prefixes.
+ * "bitrix24:42" → "42", "b24:42" → "42", "bx24:42" → "42", "42" → "42"
+ */
+export function normalizeAllowEntry(entry: string): string {
+  return entry.trim().replace(/^(bitrix24|b24|bx24):/, '');
+}
+
+/**
+ * Check whether a sender is allowed to communicate with the bot.
+ *
+ * @returns `true` if the sender is allowed, `false` otherwise.
+ */
+export function checkAccess(
+  senderId: string,
+  config: Bitrix24AccountConfig,
+): boolean {
+  const policy = config.dmPolicy ?? 'open';
+
+  switch (policy) {
+    case 'open':
+      return true;
+
+    case 'allowlist': {
+      const allowList = config.allowFrom;
+      if (!allowList || allowList.length === 0) return false;
+      const normalized = allowList.map(normalizeAllowEntry);
+      return normalized.includes(String(senderId));
+    }
+
+    case 'pairing':
+      // Pairing mode is post-MVP — for now, treat as open
+      return true;
+
+    default:
+      return false;
+  }
+}

package/src/api.ts

@@ -0,0 +1,236 @@
+import type { B24ApiResult, SendMessageOptions } from './types.js';
+import { RateLimiter } from './rate-limiter.js';
+import { Bitrix24ApiError, withRetry, isRateLimitError, defaultLogger } from './utils.js';
+
+interface Logger {
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}
+
+export class Bitrix24Api {
+  private rateLimiter: RateLimiter;
+  private logger: Logger;
+
+  constructor(opts: { maxPerSecond?: number; logger?: Logger } = {}) {
+    this.rateLimiter = new RateLimiter({ maxPerSecond: opts.maxPerSecond ?? 2 });
+    this.logger = opts.logger ?? defaultLogger;
+  }
+
+  /**
+   * Call B24 REST API via webhook URL.
+   * Webhook URL format: https://domain.bitrix24.com/rest/{user_id}/{token}/
+   * The URL itself contains authentication.
+   */
+  async callWebhook<T = unknown>(
+    webhookUrl: string,
+    method: string,
+    params?: Record<string, unknown>,
+  ): Promise<B24ApiResult<T>> {
+    await this.rateLimiter.acquire();
+
+    const url = `${webhookUrl.replace(/\/+$/, '')}/${method}.json`;
+    this.logger.debug(`API call: ${method}`, { url });
+
+    const result = await withRetry(
+      async () => {
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(params ?? {}),
+        });
+
+        if (!response.ok) {
+          throw new Bitrix24ApiError(
+            `HTTP_${response.status}`,
+            `HTTP ${response.status}: ${response.statusText}`,
+          );
+        }
+
+        const data = (await response.json()) as B24ApiResult<T>;
+
+        if (data.error) {
+          throw new Bitrix24ApiError(
+            data.error,
+            data.error_description ?? 'Unknown error',
+          );
+        }
+
+        return data;
+      },
+      {
+        maxRetries: 2,
+        shouldRetry: isRateLimitError,
+        initialDelayMs: 1000,
+      },
+    );
+
+    return result;
+  }
+
+  /**
+   * Call B24 REST API via OAuth/event access token.
+   * Used when processing webhook events that include access_token.
+   *
+   * @param clientEndpoint - e.g. "https://up.bitrix24.com/rest/"
+   * @param method - e.g. "imbot.message.add"
+   * @param accessToken - from event auth block
+   * @param params - method parameters
+   */
+  async callWithToken<T = unknown>(
+    clientEndpoint: string,
+    method: string,
+    accessToken: string,
+    params?: Record<string, unknown>,
+  ): Promise<B24ApiResult<T>> {
+    await this.rateLimiter.acquire();
+
+    const url = `${clientEndpoint.replace(/\/+$/, '')}/${method}.json`;
+    this.logger.debug(`API call (token): ${method}`, { url });
+
+    const result = await withRetry(
+      async () => {
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${accessToken}`,
+          },
+          body: JSON.stringify(params ?? {}),
+        });
+
+        if (!response.ok) {
+          throw new Bitrix24ApiError(
+            `HTTP_${response.status}`,
+            `HTTP ${response.status}: ${response.statusText}`,
+          );
+        }
+
+        const data = (await response.json()) as B24ApiResult<T>;
+
+        if (data.error) {
+          throw new Bitrix24ApiError(
+            data.error,
+            data.error_description ?? 'Unknown error',
+          );
+        }
+
+        return data;
+      },
+      {
+        maxRetries: 2,
+        shouldRetry: isRateLimitError,
+        initialDelayMs: 1000,
+      },
+    );
+
+    return result;
+  }
+
+  // ─── Convenience methods ──────────────────────────────────────────────
+
+  async sendMessage(
+    webhookUrl: string,
+    dialogId: string,
+    message: string,
+    options?: SendMessageOptions,
+  ): Promise<number> {
+    const result = await this.callWebhook<number>(webhookUrl, 'imbot.message.add', {
+      DIALOG_ID: dialogId,
+      MESSAGE: message,
+      ...options,
+    });
+    return result.result;
+  }
+
+  async sendMessageWithToken(
+    clientEndpoint: string,
+    accessToken: string,
+    dialogId: string,
+    message: string,
+    options?: SendMessageOptions,
+  ): Promise<number> {
+    const result = await this.callWithToken<number>(
+      clientEndpoint,
+      'imbot.message.add',
+      accessToken,
+      {
+        DIALOG_ID: dialogId,
+        MESSAGE: message,
+        ...options,
+      },
+    );
+    return result.result;
+  }
+
+  async updateMessage(
+    webhookUrl: string,
+    messageId: number,
+    message: string,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.message.update', {
+      MESSAGE_ID: messageId,
+      MESSAGE: message,
+    });
+    return result.result;
+  }
+
+  async updateMessageWithToken(
+    clientEndpoint: string,
+    accessToken: string,
+    messageId: number,
+    message: string,
+  ): Promise<boolean> {
+    const result = await this.callWithToken<boolean>(
+      clientEndpoint,
+      'imbot.message.update',
+      accessToken,
+      {
+        MESSAGE_ID: messageId,
+        MESSAGE: message,
+      },
+    );
+    return result.result;
+  }
+
+  async sendTyping(webhookUrl: string, dialogId: string): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.chat.sendTyping', {
+      DIALOG_ID: dialogId,
+    });
+    return result.result;
+  }
+
+  async sendTypingWithToken(
+    clientEndpoint: string,
+    accessToken: string,
+    dialogId: string,
+  ): Promise<boolean> {
+    const result = await this.callWithToken<boolean>(
+      clientEndpoint,
+      'imbot.chat.sendTyping',
+      accessToken,
+      { DIALOG_ID: dialogId },
+    );
+    return result.result;
+  }
+
+  async registerBot(
+    webhookUrl: string,
+    params: Record<string, unknown>,
+  ): Promise<number> {
+    const result = await this.callWebhook<number>(webhookUrl, 'imbot.register', params);
+    return result.result;
+  }
+
+  async unregisterBot(webhookUrl: string, botId: number): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.unregister', {
+      BOT_ID: botId,
+    });
+    return result.result;
+  }
+
+  destroy(): void {
+    this.rateLimiter.destroy();
+  }
+}