@ihazz/bitrix24 0.1.3 → 0.1.4

package/README.md

@@ -48,6 +48,7 @@ Add to your `openclaw.json`:
       "botName": "OpenClaw",
       "botCode": "openclaw",
       "callbackPath": "/hooks/bitrix24",
+      "callbackUrl": "https://your-server.com/hooks/bitrix24",
       "dmPolicy": "open",
       "showTyping": true
     }
@@ -65,6 +66,7 @@ Only `webhookUrl` is required. The gateway will not start without it.
 | `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 registration (e.g. `https://your-server.com/hooks/bitrix24`).|
 | `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,7 +24,7 @@ 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 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihazz/bitrix24",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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,18 @@ 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 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,12 @@
+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 { defaultLogger } from './utils.js';
-import type { B24MsgContext, B24JoinChatEvent } from './types.js';
+import { getBitrix24Runtime } from './runtime.js';
+import type { B24MsgContext, B24JoinChatEvent, Bitrix24AccountConfig } from './types.js';
 
 interface Logger {
   info: (...args: unknown[]) => void;
@@ -22,6 +24,64 @@ interface GatewayState {
 
 let gatewayState: GatewayState | null = null;
 
+/**
+ * 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;
+  }
+}
+
 /**
  * Handle an incoming HTTP request on the webhook route.
  * Called by the HTTP route registered in index.ts.
@@ -166,12 +226,102 @@ 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
+      await ensureBotRegistered(api, config, logger);
+
       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: false,
+            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) {
+                    await sendService.sendText(sendCtx, payload.text);
+                  }
+                },
+                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);
+          }
+        },
+
         onJoinChat: async (event: B24JoinChatEvent) => {
           logger.info('Bot joined chat', {
             dialogId: event.data.PARAMS.DIALOG_ID,

package/src/config-schema.ts

@@ -7,6 +7,7 @@ const AccountSchema = z.object({
   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/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

@@ -243,6 +243,7 @@ export interface Bitrix24AccountConfig {
   botCode?: string;
   botAvatar?: string;
   callbackPath?: string;
+  callbackUrl?: string;
   dmPolicy?: 'open' | 'allowlist' | 'pairing';
   allowFrom?: string[];
   showTyping?: boolean;