@ihazz/bitrix24 0.1.3 → 0.1.5

package/README.md

@@ -47,14 +47,25 @@ Add to your `openclaw.json`:
       "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
       "botName": "OpenClaw",
       "botCode": "openclaw",
-      "callbackPath": "/hooks/bitrix24",
+      "callbackUrl": "https://your-server.com/hooks/bitrix24",
       "dmPolicy": "open",
+      "allowFrom": ["*"],
       "showTyping": true
     }
   }
 }
 ```
 
+Set allow in plugin section:
+```json
+{
+  "plugins": {
+    "allow": [
+      "bitrix24"
+    ],
+  }
+}
+```
 Only `webhookUrl` is required. The gateway will not start without it.
 
 ### Configuration Options
@@ -64,7 +75,7 @@ Only `webhookUrl` is required. The gateway will not start without it.
 | `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 |
+| `callbackUrl` | — | Full public URL for bot EVENT_HANDLER (e.g. `https://your-server.com/hooks/bitrix24`). Path is auto-extracted for route registration. |
 | `dmPolicy` | `"open"` | Access policy: `"open"` / `"allowlist"` / `"pairing"` |
 | `allowFrom` | — | Allowed B24 user IDs (when `dmPolicy: "allowlist"`) |
 | `showTyping` | `true` | Send typing indicator before responding |

package/index.ts

@@ -1,10 +1,10 @@
 import { bitrix24Plugin, handleWebhookRequest } from './src/channel.js';
-import { setBitrix24Runtime } from './src/runtime.js';
+import { setBitrix24Runtime, type PluginRuntime } from './src/runtime.js';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 
 interface OpenClawPluginApi {
   config: Record<string, unknown>;
-  runtime: unknown;
+  runtime: PluginRuntime;
   registerChannel: (opts: { plugin: typeof bitrix24Plugin }) => void;
   registerHttpRoute: (params: {
     path: string;
@@ -24,13 +24,14 @@ export default {
   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 });
+    setBitrix24Runtime(api.runtime);
 
     api.registerChannel({ plugin: bitrix24Plugin });
 
-    // Register HTTP webhook route on the OpenClaw gateway
+    // Register HTTP webhook route — derive path from callbackUrl
     const channels = api.config?.channels as Record<string, Record<string, unknown>> | undefined;
-    const callbackPath = (channels?.bitrix24?.callbackPath as string) ?? '/hooks/bitrix24';
+    const callbackUrl = channels?.bitrix24?.callbackUrl as string | undefined;
+    const callbackPath = callbackUrl ? new URL(callbackUrl).pathname : '/hooks/bitrix24';
 
     api.registerHttpRoute({
       path: callbackPath,

package/package.json

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

package/src/api.ts

@@ -12,10 +12,12 @@ interface Logger {
 export class Bitrix24Api {
   private rateLimiter: RateLimiter;
   private logger: Logger;
+  private clientId?: string;
 
-  constructor(opts: { maxPerSecond?: number; logger?: Logger } = {}) {
+  constructor(opts: { maxPerSecond?: number; logger?: Logger; clientId?: string } = {}) {
     this.rateLimiter = new RateLimiter({ maxPerSecond: opts.maxPerSecond ?? 2 });
     this.logger = opts.logger ?? defaultLogger;
+    this.clientId = opts.clientId;
   }
 
   /**
@@ -33,12 +35,18 @@ export class Bitrix24Api {
     const url = `${webhookUrl.replace(/\/+$/, '')}/${method}.json`;
     this.logger.debug(`API call: ${method}`, { url });
 
+    // In webhook mode, CLIENT_ID identifies the "app" that owns the bot
+    const payload = { ...(params ?? {}) };
+    if (this.clientId && !payload.CLIENT_ID) {
+      payload.CLIENT_ID = this.clientId;
+    }
+
     const result = await withRetry(
       async () => {
         const response = await fetch(url, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(params ?? {}),
+          body: JSON.stringify(payload),
         });
 
         if (!response.ok) {
@@ -215,6 +223,16 @@ export class Bitrix24Api {
     return result.result;
   }
 
+  async listBots(
+    webhookUrl: string,
+  ): Promise<Array<{ ID: number; NAME: string; CODE: string; OPENLINE: string }>> {
+    // B24 returns an object keyed by bot ID, not an array
+    const result = await this.callWebhook<
+      Record<string, { ID: number; NAME: string; CODE: string; OPENLINE: string }>
+    >(webhookUrl, 'imbot.bot.list', {});
+    return Object.values(result.result ?? {});
+  }
+
   async registerBot(
     webhookUrl: string,
     params: Record<string, unknown>,
@@ -223,6 +241,45 @@ export class Bitrix24Api {
     return result.result;
   }
 
+  async updateBot(
+    webhookUrl: string,
+    botId: number,
+    fields: Record<string, unknown>,
+  ): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.update', {
+      BOT_ID: botId,
+      FIELDS: fields,
+    });
+    return result.result;
+  }
+
+  async registerCommand(
+    webhookUrl: string,
+    params: {
+      BOT_ID: number;
+      COMMAND: string;
+      COMMON?: 'Y' | 'N';
+      HIDDEN?: 'Y' | 'N';
+      EXTRANET_SUPPORT?: 'Y' | 'N';
+      LANG: Array<{ LANGUAGE_ID: string; TITLE: string; PARAMS?: string }>;
+      EVENT_COMMAND_ADD: string;
+    },
+  ): Promise<number> {
+    const result = await this.callWebhook<number>(
+      webhookUrl,
+      'imbot.command.register',
+      params,
+    );
+    return result.result;
+  }
+
+  async unregisterCommand(webhookUrl: string, commandId: number): Promise<boolean> {
+    const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.command.unregister', {
+      COMMAND_ID: commandId,
+    });
+    return result.result;
+  }
+
   async unregisterBot(webhookUrl: string, botId: number): Promise<boolean> {
     const result = await this.callWebhook<boolean>(webhookUrl, 'imbot.unregister', {
       BOT_ID: botId,

package/src/channel.ts

@@ -1,10 +1,21 @@
+import { createHash } from 'node:crypto';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { listAccountIds, resolveAccount, getConfig } from './config.js';
 import { Bitrix24Api } from './api.js';
 import { SendService } from './send-service.js';
 import { InboundHandler } from './inbound-handler.js';
+import { checkAccess } from './access-control.js';
 import { defaultLogger } from './utils.js';
-import type { B24MsgContext, B24JoinChatEvent } from './types.js';
+import { getBitrix24Runtime } from './runtime.js';
+import { OPENCLAW_COMMANDS } from './commands.js';
+import type {
+  B24MsgContext,
+  B24JoinChatEvent,
+  B24CommandEvent,
+  Bitrix24AccountConfig,
+  B24Keyboard,
+  KeyboardButton,
+} from './types.js';
 
 interface Logger {
   info: (...args: unknown[]) => void;
@@ -22,6 +33,185 @@ interface GatewayState {
 
 let gatewayState: GatewayState | null = null;
 
+// ─── Keyboard / Button conversion ────────────────────────────────────────────
+
+interface TelegramButton {
+  text: string;
+  callback_data?: string;
+  style?: string;
+}
+
+/**
+ * Convert Telegram-style button rows to B24 flat KEYBOARD array.
+ * Telegram format: Array<Array<{ text, callback_data, style }>>
+ * B24 format: flat array with { TYPE: 'NEWLINE' } separators between rows.
+ */
+function convertButtonsToKeyboard(rows: TelegramButton[][]): B24Keyboard {
+  const keyboard: B24Keyboard = [];
+
+  for (let i = 0; i < rows.length; i++) {
+    for (const btn of rows[i]) {
+      const b24Btn: KeyboardButton = { TEXT: btn.text, DISPLAY: 'LINE' };
+
+      if (btn.callback_data?.startsWith('/')) {
+        // Slash command — use COMMAND + COMMAND_PARAMS
+        const parts = btn.callback_data.substring(1).split(' ');
+        b24Btn.COMMAND = parts[0];
+        if (parts.length > 1) {
+          b24Btn.COMMAND_PARAMS = parts.slice(1).join(' ');
+        }
+      } else if (btn.callback_data) {
+        // Non-slash data — insert text into input via PUT action
+        b24Btn.ACTION = 'PUT';
+        b24Btn.ACTION_VALUE = btn.callback_data;
+      }
+
+      if (btn.style === 'primary') {
+        b24Btn.BG_COLOR_TOKEN = 'primary';
+      } else if (btn.style === 'attention' || btn.style === 'danger') {
+        b24Btn.BG_COLOR_TOKEN = 'alert';
+      }
+
+      keyboard.push(b24Btn);
+    }
+
+    // Add NEWLINE separator between rows (not after last row)
+    if (i < rows.length - 1) {
+      keyboard.push({ TYPE: 'NEWLINE' });
+    }
+  }
+
+  return keyboard;
+}
+
+/**
+ * Extract B24 keyboard from a dispatcher payload's channelData.
+ * Checks bitrix24-specific data first, then falls back to Telegram button format.
+ */
+function extractKeyboardFromPayload(
+  payload: { channelData?: Record<string, unknown> },
+): B24Keyboard | undefined {
+  const cd = payload.channelData;
+  if (!cd) return undefined;
+
+  // Direct B24 keyboard (future-proof: channelData.bitrix24.keyboard)
+  const b24Data = cd.bitrix24 as { keyboard?: B24Keyboard } | undefined;
+  if (b24Data?.keyboard?.length) {
+    return b24Data.keyboard;
+  }
+
+  // Translate from Telegram button format
+  const tgData = cd.telegram as { buttons?: TelegramButton[][] } | undefined;
+  if (tgData?.buttons?.length) {
+    return convertButtonsToKeyboard(tgData.buttons);
+  }
+
+  return undefined;
+}
+
+/**
+ * Register or update the bot on the Bitrix24 portal.
+ * Checks imbot.bot.list first; if a bot with the same CODE exists, updates it.
+ * Otherwise registers a new one.
+ */
+async function ensureBotRegistered(
+  api: Bitrix24Api,
+  config: Bitrix24AccountConfig,
+  logger: Logger,
+): Promise<number | null> {
+  const { webhookUrl, callbackUrl, botCode, botName } = config;
+  if (!webhookUrl || !callbackUrl) {
+    if (!callbackUrl) {
+      logger.warn('callbackUrl not configured — skipping bot registration (bot must be registered manually)');
+    }
+    return null;
+  }
+
+  const code = botCode ?? 'openclaw';
+  const name = botName ?? 'OpenClaw';
+
+  // Check if bot already exists
+  try {
+    const bots = await api.listBots(webhookUrl);
+    const existing = bots.find((b) => b.CODE === code);
+
+    if (existing) {
+      logger.info(`Bot "${code}" already registered (ID=${existing.ID}), updating EVENT_HANDLER`);
+      await api.updateBot(webhookUrl, existing.ID, {
+        EVENT_HANDLER: callbackUrl,
+        PROPERTIES: { NAME: name },
+      });
+      return existing.ID;
+    }
+  } catch (err) {
+    logger.warn('Failed to list existing bots, will try to register', err);
+  }
+
+  // Register new bot
+  try {
+    const botId = await api.registerBot(webhookUrl, {
+      CODE: code,
+      TYPE: 'B',
+      EVENT_HANDLER: callbackUrl,
+      PROPERTIES: {
+        NAME: name,
+        WORK_POSITION: 'AI Assistant',
+        COLOR: 'AZURE',
+      },
+    });
+    logger.info(`Bot "${code}" registered (ID=${botId})`);
+    return botId;
+  } catch (err) {
+    logger.error('Failed to register bot', err);
+    return null;
+  }
+}
+
+/**
+ * Register OpenClaw slash commands with the B24 bot.
+ * Runs in the background — errors are logged but don't block startup.
+ */
+async function ensureCommandsRegistered(
+  api: Bitrix24Api,
+  config: Bitrix24AccountConfig,
+  botId: number,
+  logger: Logger,
+): Promise<void> {
+  const { webhookUrl, callbackUrl } = config;
+  if (!webhookUrl || !callbackUrl) return;
+
+  let registered = 0;
+  let skipped = 0;
+
+  for (const cmd of OPENCLAW_COMMANDS) {
+    try {
+      await api.registerCommand(webhookUrl, {
+        BOT_ID: botId,
+        COMMAND: cmd.command,
+        COMMON: 'N',
+        HIDDEN: 'N',
+        EXTRANET_SUPPORT: 'N',
+        LANG: [
+          { LANGUAGE_ID: 'en', TITLE: cmd.en, ...(cmd.params ? { PARAMS: cmd.params } : {}) },
+          { LANGUAGE_ID: 'ru', TITLE: cmd.ru, ...(cmd.params ? { PARAMS: cmd.params } : {}) },
+        ],
+        EVENT_COMMAND_ADD: callbackUrl,
+      });
+      registered++;
+    } catch (err: unknown) {
+      // "WRONG_REQUEST" typically means command already exists
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('WRONG_REQUEST') || msg.includes('already')) {
+        skipped++;
+      } else {
+        logger.warn(`Failed to register command /${cmd.command}`, err);
+      }
+    }
+  }
+
+  logger.info(`Commands sync: ${registered} registered, ${skipped} already existed (total ${OPENCLAW_COMMANDS.length})`);
+}
+
 /**
  * Handle an incoming HTTP request on the webhook route.
  * Called by the HTTP route registered in index.ts.
@@ -141,6 +331,55 @@ export const bitrix24Plugin = {
         error: result.error,
       };
     },
+
+    /**
+     * Send a payload with optional channelData (keyboards, etc.) to B24.
+     * Called by OpenClaw when the response includes channelData.
+     */
+    sendPayload: async (params: {
+      text: string;
+      channelData?: Record<string, unknown>;
+      context: B24MsgContext;
+      account: { config: { webhookUrl?: string; showTyping?: boolean } };
+    }) => {
+      const { text, channelData, context, account } = params;
+
+      if (!gatewayState) {
+        return { ok: false, error: 'Gateway not started', channel: 'bitrix24' };
+      }
+
+      const { sendService } = gatewayState;
+
+      const sendCtx = {
+        webhookUrl: account.config.webhookUrl,
+        clientEndpoint: context.clientEndpoint,
+        botToken: context.botToken,
+        dialogId: context.chatId,
+      };
+
+      // Send typing indicator
+      if (account.config.showTyping !== false) {
+        await sendService.sendTyping(sendCtx);
+      }
+
+      // Extract keyboard from channelData
+      const keyboard = channelData
+        ? extractKeyboardFromPayload({ channelData })
+        : undefined;
+
+      const result = await sendService.sendText(
+        sendCtx,
+        text,
+        keyboard ? { keyboard } : undefined,
+      );
+
+      return {
+        ok: result.ok,
+        messageId: result.messageId,
+        channel: 'bitrix24' as const,
+        error: result.error,
+      };
+    },
   },
 
   gateway: {
@@ -166,12 +405,207 @@ export const bitrix24Plugin = {
 
       logger.info(`[${ctx.accountId}] starting Bitrix24 channel`);
 
-      const api = new Bitrix24Api({ logger });
+      // Derive CLIENT_ID from webhookUrl (md5) — stable and unique per portal
+      const clientId = createHash('md5').update(config.webhookUrl).digest('hex');
+      const api = new Bitrix24Api({ logger, clientId });
       const sendService = new SendService(api, logger);
 
+      // Register or update bot on the B24 portal
+      const botId = await ensureBotRegistered(api, config, logger);
+
+      // Register slash commands (runs in background, doesn't block startup)
+      if (botId) {
+        ensureCommandsRegistered(api, config, botId, logger).catch((err) => {
+          logger.warn('Command registration failed', err);
+        });
+      }
+
       const inboundHandler = new InboundHandler({
         config,
         logger,
+
+        onMessage: async (msgCtx: B24MsgContext) => {
+          logger.info('Inbound message', {
+            senderId: msgCtx.senderId,
+            chatId: msgCtx.chatId,
+            messageId: msgCtx.messageId,
+            textLen: msgCtx.text.length,
+          });
+
+          const runtime = getBitrix24Runtime();
+          const cfg = runtime.config.loadConfig();
+
+          // Resolve which agent handles this conversation
+          const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: 'bitrix24',
+            accountId: ctx.accountId,
+            peer: {
+              kind: msgCtx.isDm ? 'direct' : 'group',
+              id: msgCtx.chatId,
+            },
+          });
+
+          logger.debug('Resolved route', {
+            sessionKey: route.sessionKey,
+            agentId: route.agentId,
+            matchedBy: route.matchedBy,
+          });
+
+          // Build and finalize inbound context for OpenClaw agent
+          const inboundCtx = runtime.channel.reply.finalizeInboundContext({
+            Body: msgCtx.text,
+            BodyForAgent: msgCtx.text,
+            RawBody: msgCtx.text,
+            From: `bitrix24:${msgCtx.chatId}`,
+            To: `bitrix24:${msgCtx.chatId}`,
+            SessionKey: route.sessionKey,
+            AccountId: route.accountId,
+            ChatType: msgCtx.isDm ? 'direct' : 'group',
+            ConversationLabel: msgCtx.senderName,
+            SenderName: msgCtx.senderName,
+            SenderId: msgCtx.senderId,
+            Provider: 'bitrix24',
+            Surface: 'bitrix24',
+            MessageSid: msgCtx.messageId,
+            Timestamp: Date.now(),
+            WasMentioned: false,
+            CommandAuthorized: true,
+            OriginatingChannel: 'bitrix24',
+            OriginatingTo: `bitrix24:${msgCtx.chatId}`,
+          });
+
+          const sendCtx = {
+            webhookUrl: config.webhookUrl,
+            clientEndpoint: msgCtx.clientEndpoint,
+            botToken: msgCtx.botToken,
+            dialogId: msgCtx.chatId,
+          };
+
+          // Dispatch to AI agent; deliver callback sends reply back to B24
+          try {
+            await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+              ctx: inboundCtx,
+              cfg,
+              dispatcherOptions: {
+                deliver: async (payload) => {
+                  if (payload.text) {
+                    const keyboard = extractKeyboardFromPayload(payload);
+                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                  }
+                },
+                onReplyStart: async () => {
+                  if (config.showTyping !== false) {
+                    await sendService.sendTyping(sendCtx);
+                  }
+                },
+                onError: (err) => {
+                  logger.error('Error delivering reply to B24', err);
+                },
+              },
+            });
+          } catch (err) {
+            logger.error('Error dispatching message to agent', err);
+          }
+        },
+
+        onCommand: async (event: B24CommandEvent) => {
+          const cmdEntry = Object.values(event.data.COMMAND)[0];
+          if (!cmdEntry) {
+            logger.warn('No command entry in ONIMCOMMANDADD event');
+            return;
+          }
+
+          const commandName = cmdEntry.COMMAND;
+          const commandParams = cmdEntry.COMMAND_PARAMS?.trim() ?? '';
+          const commandText = commandParams
+            ? `/${commandName} ${commandParams}`
+            : `/${commandName}`;
+
+          const senderId = String(event.data.PARAMS.FROM_USER_ID);
+          const dialogId = event.data.PARAMS.DIALOG_ID;
+          const isDm = event.data.PARAMS.CHAT_TYPE === 'P';
+          const user = event.data.USER;
+
+          logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
+
+          // Access control
+          if (!checkAccess(senderId, config)) {
+            logger.debug(`Access denied for command from user ${senderId}`);
+            return;
+          }
+
+          const runtime = getBitrix24Runtime();
+          const cfg = runtime.config.loadConfig();
+
+          const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: 'bitrix24',
+            accountId: ctx.accountId,
+            peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
+          });
+
+          // Native commands use a separate slash-command session (like Telegram)
+          const slashSessionKey = `bitrix24:slash:${senderId}`;
+
+          const inboundCtx = runtime.channel.reply.finalizeInboundContext({
+            Body: commandText,
+            BodyForAgent: commandText,
+            RawBody: commandText,
+            CommandBody: commandText,
+            CommandAuthorized: true,
+            CommandSource: 'native',
+            CommandTargetSessionKey: route.sessionKey,
+            From: `bitrix24:${dialogId}`,
+            To: `slash:${senderId}`,
+            SessionKey: slashSessionKey,
+            AccountId: route.accountId,
+            ChatType: isDm ? 'direct' : 'group',
+            ConversationLabel: user.NAME,
+            SenderName: user.NAME,
+            SenderId: senderId,
+            Provider: 'bitrix24',
+            Surface: 'bitrix24',
+            MessageSid: String(event.data.PARAMS.MESSAGE_ID),
+            Timestamp: Date.now(),
+            WasMentioned: true,
+            OriginatingChannel: 'bitrix24',
+            OriginatingTo: `bitrix24:${dialogId}`,
+          });
+
+          const sendCtx = {
+            webhookUrl: config.webhookUrl,
+            clientEndpoint: (cmdEntry.client_endpoint as string | undefined) ?? event.auth.client_endpoint,
+            botToken: cmdEntry.access_token,
+            dialogId,
+          };
+
+          try {
+            await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+              ctx: inboundCtx,
+              cfg,
+              dispatcherOptions: {
+                deliver: async (payload) => {
+                  if (payload.text) {
+                    const keyboard = extractKeyboardFromPayload(payload);
+                    await sendService.sendText(sendCtx, payload.text, keyboard ? { keyboard } : undefined);
+                  }
+                },
+                onReplyStart: async () => {
+                  if (config.showTyping !== false) {
+                    await sendService.sendTyping(sendCtx);
+                  }
+                },
+                onError: (err) => {
+                  logger.error('Error delivering command reply to B24', err);
+                },
+              },
+            });
+          } catch (err) {
+            logger.error('Error dispatching command to agent', err);
+          }
+        },
+
         onJoinChat: async (event: B24JoinChatEvent) => {
           logger.info('Bot joined chat', {
             dialogId: event.data.PARAMS.DIALOG_ID,

package/src/commands.ts

@@ -0,0 +1,60 @@
+/**
+ * OpenClaw bot commands to register with Bitrix24.
+ *
+ * Mirrors the native commands registered by the Telegram plugin via setMyCommands.
+ */
+
+export interface BotCommandDef {
+  command: string;
+  en: string;
+  ru: string;
+  params?: string;
+}
+
+/**
+ * Standard OpenClaw commands.
+ * Excludes: focus/unfocus/agents (Discord-specific), allowlist/bash (text-only scope).
+ */
+export const OPENCLAW_COMMANDS: BotCommandDef[] = [
+  // ── Status ──
+  { command: 'help', en: 'Show available commands', ru: 'Показать доступные команды' },
+  { command: 'commands', en: 'List all slash commands', ru: 'Список всех команд' },
+  { command: 'status', en: 'Show current status', ru: 'Показать текущий статус' },
+  { command: 'context', en: 'Explain how context is built', ru: 'Объяснить построение контекста' },
+  { command: 'whoami', en: 'Show your sender ID', ru: 'Показать ваш ID' },
+  { command: 'usage', en: 'Usage and cost summary', ru: 'Использование и стоимость', params: 'off|tokens|full|cost' },
+
+  // ── Session ──
+  { command: 'new', en: 'Start a new session', ru: 'Начать новую сессию' },
+  { command: 'reset', en: 'Reset the current session', ru: 'Сбросить текущую сессию' },
+  { command: 'stop', en: 'Stop the current run', ru: 'Остановить текущий запуск' },
+  { command: 'compact', en: 'Compact the session context', ru: 'Сжать контекст сессии', params: 'instructions' },
+  { command: 'session', en: 'Manage session settings', ru: 'Настройки сессии', params: 'ttl|...' },
+
+  // ── Options ──
+  { command: 'model', en: 'Show or set the model', ru: 'Показать/сменить модель', params: 'model name' },
+  { command: 'models', en: 'List available models', ru: 'Список моделей', params: 'provider' },
+  { command: 'think', en: 'Set thinking level', ru: 'Уровень размышлений', params: 'off|low|medium|high' },
+  { command: 'verbose', en: 'Toggle verbose mode', ru: 'Подробный режим', params: 'on|off' },
+  { command: 'reasoning', en: 'Toggle reasoning visibility', ru: 'Видимость рассуждений', params: 'on|off|stream' },
+  { command: 'elevated', en: 'Toggle elevated mode', ru: 'Режим с расширенными правами', params: 'on|off|ask|full' },
+  { command: 'exec', en: 'Set exec defaults', ru: 'Настройки выполнения', params: 'host|security|ask|node' },
+  { command: 'queue', en: 'Adjust queue settings', ru: 'Настройки очереди', params: 'mode|debounce|cap|drop' },
+
+  // ── Management ──
+  { command: 'config', en: 'Show or set config values', ru: 'Показать/задать конфигурацию', params: 'show|get|set|unset' },
+  { command: 'debug', en: 'Set runtime debug overrides', ru: 'Отладочные настройки', params: 'show|reset|set|unset' },
+  { command: 'approve', en: 'Approve or deny exec requests', ru: 'Одобрить/отклонить запросы' },
+  { command: 'activation', en: 'Set group activation mode', ru: 'Режим активации в группах', params: 'mention|always' },
+  { command: 'send', en: 'Set send policy', ru: 'Политика отправки', params: 'on|off|inherit' },
+  { command: 'subagents', en: 'Manage subagent runs', ru: 'Управление субагентами' },
+  { command: 'kill', en: 'Kill a running subagent', ru: 'Остановить субагента', params: 'id|all' },
+  { command: 'steer', en: 'Send guidance to a subagent', ru: 'Направить субагента', params: 'message' },
+
+  // ── Tools ──
+  { command: 'skill', en: 'Run a skill by name', ru: 'Запустить навык', params: 'name' },
+  { command: 'restart', en: 'Restart OpenClaw', ru: 'Перезапустить OpenClaw' },
+
+  // ── Export ──
+  { command: 'export-session', en: 'Export session to HTML', ru: 'Экспорт сессии в HTML' },
+];

package/src/config-schema.ts

@@ -6,7 +6,7 @@ const AccountSchema = z.object({
   botName: z.string().optional().default('OpenClaw'),
   botCode: z.string().optional().default('openclaw'),
   botAvatar: z.string().optional(),
-  callbackPath: z.string().optional().default('/hooks/bitrix24'),
+  callbackUrl: z.string().url().optional(),
   dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('open'),
   allowFrom: z.array(z.string()).optional(),
   showTyping: z.boolean().optional().default(true),

package/src/message-utils.ts

@@ -90,15 +90,25 @@ export function buildKeyboard(
     }>
   >,
 ): B24Keyboard {
-  return rows.map((row) =>
-    row.map((btn): KeyboardButton => ({
-      TEXT: btn.text,
-      ...(btn.command ? { COMMAND: btn.command, COMMAND_PARAMS: btn.commandParams ?? '' } : {}),
-      ...(btn.link ? { LINK: btn.link } : {}),
-      BG_COLOR: btn.bgColor ?? '#29619b',
-      TEXT_COLOR: btn.textColor ?? '#fff',
-      DISPLAY: btn.fullWidth ? 'LINE' : 'BLOCK',
-      BLOCK: btn.disableAfterClick ? 'Y' : 'N',
-    })),
-  );
+  const keyboard: B24Keyboard = [];
+
+  for (let i = 0; i < rows.length; i++) {
+    for (const btn of rows[i]) {
+      keyboard.push({
+        TEXT: btn.text,
+        ...(btn.command ? { COMMAND: btn.command, COMMAND_PARAMS: btn.commandParams ?? '' } : {}),
+        ...(btn.link ? { LINK: btn.link } : {}),
+        BG_COLOR: btn.bgColor ?? '#29619b',
+        TEXT_COLOR: btn.textColor ?? '#fff',
+        DISPLAY: btn.fullWidth ? 'LINE' : 'BLOCK',
+        BLOCK: btn.disableAfterClick ? 'Y' : 'N',
+      });
+    }
+
+    if (i < rows.length - 1) {
+      keyboard.push({ TYPE: 'NEWLINE' });
+    }
+  }
+
+  return keyboard;
 }

package/src/runtime.ts

@@ -1,9 +1,65 @@
+interface ReplyPayload {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  isError?: boolean;
+  channelData?: Record<string, unknown>;
+}
+
 export interface PluginRuntime {
-  logger: {
-    info: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-    debug: (...args: unknown[]) => void;
+  config: {
+    loadConfig: () => Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  channel: {
+    routing: {
+      resolveAgentRoute: (input: {
+        cfg: Record<string, unknown>;
+        channel: string;
+        accountId?: string | null;
+        peer?: { kind: string; id: string } | null;
+      }) => {
+        agentId: string;
+        channel: string;
+        accountId: string;
+        sessionKey: string;
+        mainSessionKey: string;
+        matchedBy: string;
+      };
+    };
+    reply: {
+      finalizeInboundContext: <T extends Record<string, unknown>>(
+        ctx: T,
+        opts?: Record<string, boolean>,
+      ) => T;
+      dispatchReplyWithBufferedBlockDispatcher: (params: {
+        ctx: Record<string, unknown>;
+        cfg: Record<string, unknown>;
+        dispatcherOptions: {
+          deliver: (payload: ReplyPayload, info: { kind: string }) => Promise<void>;
+          onReplyStart?: () => Promise<void> | void;
+          onIdle?: () => void;
+          onCleanup?: () => void;
+          onError?: (err: unknown, info: { kind: string }) => void;
+        };
+        replyOptions?: Record<string, unknown>;
+      }) => Promise<{ queuedFinal: boolean; counts: Record<string, number> }>;
+      [key: string]: unknown;
+    };
+    session: {
+      recordInboundSession: (params: Record<string, unknown>) => Promise<void>;
+      [key: string]: unknown;
+    };
+    [key: string]: unknown;
+  };
+  logging: {
+    getChildLogger: (bindings?: Record<string, unknown>) => {
+      info: (...args: unknown[]) => void;
+      warn: (...args: unknown[]) => void;
+      error: (...args: unknown[]) => void;
+      debug: (...args: unknown[]) => void;
+    };
+    [key: string]: unknown;
   };
   [key: string]: unknown;
 }

package/src/types.ts

@@ -211,14 +211,23 @@ export interface KeyboardButton {
   COMMAND?: string;
   COMMAND_PARAMS?: string;
   BG_COLOR?: string;
+  BG_COLOR_TOKEN?: 'primary' | 'secondary' | 'alert' | 'base';
   TEXT_COLOR?: string;
   DISPLAY?: 'LINE' | 'BLOCK';
   DISABLED?: 'Y' | 'N';
   BLOCK?: 'Y' | 'N';
   LINK?: string;
+  WIDTH?: number;
+  ACTION?: 'PUT' | 'SEND' | 'COPY' | 'CALL' | 'DIALOG';
+  ACTION_VALUE?: string;
 }
 
-export type B24Keyboard = KeyboardButton[][];
+export interface KeyboardNewline {
+  TYPE: 'NEWLINE';
+}
+
+/** B24 keyboard: flat array with NEWLINE separators between rows */
+export type B24Keyboard = (KeyboardButton | KeyboardNewline)[];
 
 export interface SendMessageOptions {
   ATTACH?: unknown;
@@ -242,7 +251,7 @@ export interface Bitrix24AccountConfig {
   botName?: string;
   botCode?: string;
   botAvatar?: string;
-  callbackPath?: string;
+  callbackUrl?: string;
   dmPolicy?: 'open' | 'allowlist' | 'pairing';
   allowFrom?: string[];
   showTyping?: boolean;

package/tests/message-utils.test.ts

@@ -78,18 +78,16 @@ describe('splitMessage', () => {
 });
 
 describe('buildKeyboard', () => {
-  it('builds a single row keyboard', () => {
+  it('builds a single row keyboard (flat array)', () => {
     const kb = buildKeyboard([
       [{ text: 'Yes', command: 'answer', commandParams: 'yes' }],
     ]);
+    // Flat array: 1 button, no NEWLINE
     expect(kb).toHaveLength(1);
-    expect(kb[0]).toHaveLength(1);
-    expect(kb[0][0].TEXT).toBe('Yes');
-    expect(kb[0][0].COMMAND).toBe('answer');
-    expect(kb[0][0].COMMAND_PARAMS).toBe('yes');
+    expect(kb[0]).toMatchObject({ TEXT: 'Yes', COMMAND: 'answer', COMMAND_PARAMS: 'yes' });
   });
 
-  it('builds multi-row keyboard', () => {
+  it('builds multi-row keyboard with NEWLINE separators', () => {
     const kb = buildKeyboard([
       [
         { text: 'Yes', command: 'answer', commandParams: 'yes' },
@@ -97,27 +95,26 @@ describe('buildKeyboard', () => {
       ],
       [{ text: 'More info', link: 'https://example.com', fullWidth: true }],
     ]);
-    expect(kb).toHaveLength(2);
-    expect(kb[0]).toHaveLength(2);
-    expect(kb[1]).toHaveLength(1);
-    expect(kb[1][0].LINK).toBe('https://example.com');
-    expect(kb[1][0].DISPLAY).toBe('LINE');
+    // Flat: [btn, btn, NEWLINE, btn] = 4 items
+    expect(kb).toHaveLength(4);
+    expect(kb[0]).toMatchObject({ TEXT: 'Yes' });
+    expect(kb[1]).toMatchObject({ TEXT: 'No' });
+    expect(kb[2]).toMatchObject({ TYPE: 'NEWLINE' });
+    expect(kb[3]).toMatchObject({ TEXT: 'More info', LINK: 'https://example.com', DISPLAY: 'LINE' });
   });
 
   it('applies default colors', () => {
     const kb = buildKeyboard([[{ text: 'Click' }]]);
-    expect(kb[0][0].BG_COLOR).toBe('#29619b');
-    expect(kb[0][0].TEXT_COLOR).toBe('#fff');
+    expect(kb[0]).toMatchObject({ BG_COLOR: '#29619b', TEXT_COLOR: '#fff' });
   });
 
   it('applies custom colors', () => {
     const kb = buildKeyboard([[{ text: 'Click', bgColor: '#333', textColor: '#eee' }]]);
-    expect(kb[0][0].BG_COLOR).toBe('#333');
-    expect(kb[0][0].TEXT_COLOR).toBe('#eee');
+    expect(kb[0]).toMatchObject({ BG_COLOR: '#333', TEXT_COLOR: '#eee' });
   });
 
   it('sets BLOCK=Y when disableAfterClick is true', () => {
     const kb = buildKeyboard([[{ text: 'Once', command: 'once', disableAfterClick: true }]]);
-    expect(kb[0][0].BLOCK).toBe('Y');
+    expect(kb[0]).toMatchObject({ BLOCK: 'Y' });
   });
 });