@ihazz/bitrix24 0.2.4 → 1.0.0

package/src/channel.ts

@@ -3,57 +3,515 @@ import { basename } from 'node:path';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { listAccountIds, resolveAccount, getConfig } from './config.js';
 import { Bitrix24Api } from './api.js';
+import type { BotContext } from './api.js';
 import { SendService } from './send-service.js';
+import type { CommandSendContext, SendContext } from './send-service.js';
 import { MediaService } from './media-service.js';
 import type { DownloadedMedia } from './media-service.js';
 import { InboundHandler } from './inbound-handler.js';
-import { normalizeAllowEntry, checkAccessWithPairing } from './access-control.js';
+import type { FetchCommandContext, FetchJoinChatContext } from './inbound-handler.js';
+import { PollingService } from './polling-service.js';
+import {
+  normalizeAllowEntry,
+  normalizeAllowList,
+  checkAccessWithPairing,
+  getWebhookUserId,
+} from './access-control.js';
 import { DEFAULT_AVATAR_BASE64 } from './bot-avatar.js';
-import { defaultLogger } from './utils.js';
+import { Bitrix24ApiError, defaultLogger, CHANNEL_PREFIX_RE } from './utils.js';
 import { getBitrix24Runtime } from './runtime.js';
 import type { ChannelPairingAdapter } from './runtime.js';
-import { OPENCLAW_COMMANDS } from './commands.js';
+import { OPENCLAW_COMMANDS, buildCommandsHelpText, formatModelsCommandReply } from './commands.js';
+import {
+  forwardedMessageUnsupported,
+  mediaDownloadFailed,
+  groupChatUnsupported,
+  onboardingMessage,
+  personalBotOwnerOnly,
+  replyMessageUnsupported,
+} from './i18n.js';
 import type {
   B24MsgContext,
-  B24JoinChatEvent,
-  B24CommandEvent,
+  B24InputActionStatusCode,
+  B24V2FetchEventItem,
+  B24V2DeleteEventData,
+  FetchContext,
   Bitrix24AccountConfig,
   B24Keyboard,
   KeyboardButton,
+  Logger,
 } from './types.js';
 
-interface Logger {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
+const PHASE_STATUS_DURATION_SECONDS = 8;
+const PHASE_STATUS_REFRESH_GRACE_MS = 1000;
+const THINKING_STATUS_DURATION_SECONDS = 30;
+const THINKING_STATUS_REFRESH_GRACE_MS = 6000;
+const DIRECT_TEXT_COALESCE_DEBOUNCE_MS = 200;
+const DIRECT_TEXT_COALESCE_MAX_WAIT_MS = 5000;
+const ACCESS_DENIED_NOTICE_COOLDOWN_MS = 60000;
+const AUTO_BOT_CODE_MAX_CANDIDATES = 100;
+const MEDIA_DOWNLOAD_CONCURRENCY = 2;
+const MAX_WEBHOOK_BODY_BYTES = 1024 * 1024;
+
+// ─── Emoji → B24 reaction code mapping ──────────────────────────────────
+// B24 uses named reaction codes, not Unicode emoji.
+// Map common Unicode emoji to their B24 equivalents.
+const EMOJI_TO_B24_REACTION: Record<string, string> = {
+  '👍': 'like',
+  '👎': 'dislike',
+  '😂': 'faceWithTearsOfJoy',
+  '❤️': 'redHeart',
+  '❤': 'redHeart',
+  '😐': 'neutralFace',
+  '🔥': 'fire',
+  '😢': 'cry',
+  '🙂': 'slightlySmilingFace',
+  '😉': 'winkingFace',
+  '😆': 'laugh',
+  '😘': 'kiss',
+  '😲': 'wonder',
+  '🙁': 'slightlyFrowningFace',
+  '😭': 'loudlyCryingFace',
+  '😛': 'faceWithStuckOutTongue',
+  '😜': 'faceWithStuckOutTongueAndWinkingEye',
+  '😎': 'smilingFaceWithSunglasses',
+  '😕': 'confusedFace',
+  '😳': 'flushedFace',
+  '🤔': 'thinkingFace',
+  '😠': 'angry',
+  '😈': 'smilingFaceWithHorns',
+  '🤒': 'faceWithThermometer',
+  '🤦': 'facepalm',
+  '💩': 'poo',
+  '💪': 'flexedBiceps',
+  '👏': 'clappingHands',
+  '🖐️': 'raisedHand',
+  '🖐': 'raisedHand',
+  '😍': 'smilingFaceWithHeartEyes',
+  '🥰': 'smilingFaceWithHearts',
+  '🥺': 'pleadingFace',
+  '😌': 'relievedFace',
+  '🙏': 'foldedHands',
+  '👌': 'okHand',
+  '🤘': 'signHorns',
+  '🤟': 'loveYouGesture',
+  '🤡': 'clownFace',
+  '🥳': 'partyingFace',
+  '❓': 'questionMark',
+  '❗': 'exclamationMark',
+  '💡': 'lightBulb',
+  '💣': 'bomb',
+  '💤': 'sleepingSymbol',
+  '❌': 'crossMark',
+  '✅': 'whiteHeavyCheckMark',
+  '👀': 'eyes',
+  '🤝': 'handshake',
+  '💯': 'hundredPoints',
+};
+
+// All valid B24 reaction codes (for pass-through when code is used directly)
+const B24_REACTION_CODES = new Set(Object.values(EMOJI_TO_B24_REACTION));
+
+/**
+ * Resolve an emoji or B24 reaction code to a valid B24 reaction code.
+ * Returns null if the emoji/code is not supported.
+ */
+function resolveB24Reaction(emojiOrCode: string): string | null {
+  const trimmed = emojiOrCode.trim();
+  if (B24_REACTION_CODES.has(trimmed)) return trimmed;
+  return EMOJI_TO_B24_REACTION[trimmed] ?? null;
+}
+
+function toMessageId(value: string | number | undefined): number | undefined {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+async function notifyStatus(
+  sendService: SendService,
+  sendCtx: SendContext,
+  config: Bitrix24AccountConfig,
+  statusMessageCode: B24InputActionStatusCode,
+  duration = PHASE_STATUS_DURATION_SECONDS,
+): Promise<void> {
+  if (config.showTyping === false) return;
+  await sendService.sendStatus(sendCtx, statusMessageCode, duration);
+}
+
+function createReplyStatusHeartbeat(params: {
+  sendService: SendService;
+  sendCtx: SendContext;
+  config: Bitrix24AccountConfig;
+}): {
+  start: () => Promise<void>;
+  stop: () => void;
+  stopAndWait: () => Promise<void>;
+  holdFor: (durationSeconds: number, graceMs?: number) => void;
+} {
+  const { sendService, sendCtx, config } = params;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  let inFlight = false;
+  let activeTick: Promise<void> | null = null;
+  let nextHeartbeatAt = Date.now();
+
+  const scheduleNext = (): void => {
+    if (stopped || config.showTyping === false) return;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+
+    const delay = Math.max(0, nextHeartbeatAt - Date.now());
+    timer = setTimeout(() => {
+      void runTick();
+    }, delay);
+  };
+
+  const holdFor = (
+    durationSeconds: number,
+    graceMs = PHASE_STATUS_REFRESH_GRACE_MS,
+  ): void => {
+    const holdMs = Math.max(0, (durationSeconds * 1000) - graceMs);
+    const holdUntil = Date.now() + holdMs;
+    if (holdUntil > nextHeartbeatAt) {
+      nextHeartbeatAt = holdUntil;
+    }
+    if (timer) {
+      scheduleNext();
+    }
+  };
+
+  const runTick = (): Promise<void> => {
+    const tick = (async (): Promise<void> => {
+      if (stopped || inFlight || config.showTyping === false) return;
+      if (Date.now() < nextHeartbeatAt) {
+        scheduleNext();
+        return;
+      }
+
+      inFlight = true;
+      try {
+        await notifyStatus(
+          sendService,
+          sendCtx,
+          config,
+          'IMBOT_AGENT_ACTION_THINKING',
+          THINKING_STATUS_DURATION_SECONDS,
+        );
+      } finally {
+        inFlight = false;
+        nextHeartbeatAt = Date.now() + (
+          (THINKING_STATUS_DURATION_SECONDS * 1000) - THINKING_STATUS_REFRESH_GRACE_MS
+        );
+        scheduleNext();
+      }
+    })();
+
+    activeTick = tick;
+    void tick.finally(() => {
+      if (activeTick === tick) {
+        activeTick = null;
+      }
+    });
+
+    return tick;
+  };
+
+  return {
+    start: async () => {
+      if (stopped || timer || config.showTyping === false) return;
+      if (Date.now() >= nextHeartbeatAt) {
+        await runTick();
+        return;
+      }
+      scheduleNext();
+    },
+    stop: () => {
+      stopped = true;
+      if (!timer) return;
+      clearTimeout(timer);
+      timer = null;
+    },
+    stopAndWait: async () => {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (activeTick) {
+        await activeTick;
+      }
+    },
+    holdFor,
+  };
+}
+
+export function canCoalesceDirectMessage(
+  msgCtx: B24MsgContext,
+  config: Bitrix24AccountConfig,
+): boolean {
+  return msgCtx.isDm
+    && config.dmPolicy !== 'pairing'
+    && msgCtx.media.length === 0
+    && !msgCtx.replyToMessageId
+    && !msgCtx.isForwarded
+    && msgCtx.text.trim().length > 0
+    && !msgCtx.text.trim().startsWith('/');
+}
+
+export function mergeBufferedDirectMessages(messages: B24MsgContext[]): B24MsgContext {
+  const first = messages[0];
+  const last = messages[messages.length - 1];
+
+  return {
+    ...first,
+    text: messages
+      .map((message) => message.text.trim())
+      .filter(Boolean)
+      .join('\n'),
+    messageId: last.messageId,
+    language: last.language ?? first.language,
+    raw: last.raw,
+  };
+}
+
+export function mergeForwardedMessageContext(
+  previousMsgCtx: B24MsgContext,
+  forwardedMsgCtx: B24MsgContext,
+): B24MsgContext {
+  const previousText = previousMsgCtx.text.trim();
+  const forwardedText = forwardedMsgCtx.text.trim();
+  const mergedText = [
+    previousText,
+    forwardedText ? `[Forwarded message]\n${forwardedText}` : '',
+  ].filter(Boolean).join('\n\n');
+
+  return {
+    ...forwardedMsgCtx,
+    text: mergedText,
+    media: [...previousMsgCtx.media, ...forwardedMsgCtx.media],
+    language: forwardedMsgCtx.language ?? previousMsgCtx.language,
+    isForwarded: false,
+  };
+}
+
+export function resolveDirectMessageCoalesceDelay(params: {
+  startedAt: number;
+  now: number;
+  debounceMs?: number;
+  maxWaitMs?: number;
+}): number {
+  const debounceMs = params.debounceMs ?? DIRECT_TEXT_COALESCE_DEBOUNCE_MS;
+  const maxWaitMs = params.maxWaitMs ?? DIRECT_TEXT_COALESCE_MAX_WAIT_MS;
+  const elapsedMs = Math.max(0, params.now - params.startedAt);
+  const remainingMs = Math.max(0, maxWaitMs - elapsedMs);
+
+  return Math.min(debounceMs, remainingMs);
+}
+
+export function shouldSkipJoinChatWelcome(params: {
+  dialogId?: string;
+  chatType?: string;
+  webhookUrl: string;
+  dmPolicy?: Bitrix24AccountConfig['dmPolicy'];
+}): boolean {
+  if (!params.dialogId) {
+    return false;
+  }
+
+  if (params.chatType === 'chat' || params.chatType === 'open') {
+    return false;
+  }
+
+  const policy = params.dmPolicy ?? 'webhookUser';
+  const webhookUserId = getWebhookUserId(params.webhookUrl);
+
+  return policy === 'webhookUser'
+    && Boolean(webhookUserId)
+    && normalizeAllowEntry(params.dialogId) !== webhookUserId;
+}
+
+async function mapWithConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const results = new Array<R>(items.length);
+  let nextIndex = 0;
+  const poolSize = Math.max(1, Math.min(concurrency, items.length));
+
+  const runners = Array.from({ length: poolSize }, async () => {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      results[currentIndex] = await worker(items[currentIndex], currentIndex);
+    }
+  });
+
+  await Promise.all(runners);
+  return results;
+}
+
+function resolveSecurityConfig(params: {
+  cfg?: Record<string, unknown>;
+  accountId?: string;
+  account?: { config?: Record<string, unknown> };
+}): Bitrix24AccountConfig {
+  if (params.account?.config) {
+    return params.account.config as Bitrix24AccountConfig;
+  }
+
+  if (params.cfg) {
+    return resolveAccount(params.cfg, params.accountId).config;
+  }
+
+  return {};
+}
+
+interface BufferedDirectMessageEntry {
+  messages: B24MsgContext[];
+  startedAt: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+class BufferedDirectMessageCoalescer {
+  private readonly entries = new Map<string, BufferedDirectMessageEntry>();
+  private readonly debounceMs: number;
+  private readonly maxWaitMs: number;
+  private readonly onFlush: (msgCtx: B24MsgContext) => Promise<void>;
+  private readonly logger: Logger;
+  private destroyed = false;
+
+  constructor(params: {
+    debounceMs: number;
+    maxWaitMs: number;
+    onFlush: (msgCtx: B24MsgContext) => Promise<void>;
+    logger: Logger;
+  }) {
+    this.debounceMs = params.debounceMs;
+    this.maxWaitMs = params.maxWaitMs;
+    this.onFlush = params.onFlush;
+    this.logger = params.logger;
+  }
+
+  enqueue(accountId: string, msgCtx: B24MsgContext): void {
+    const key = this.getKey(accountId, msgCtx.chatId);
+    const current = this.entries.get(key);
+
+    if (current) {
+      clearTimeout(current.timer);
+      current.messages.push(msgCtx);
+      current.timer = this.createTimer(key, current.startedAt);
+      this.logger.debug('Buffered direct message appended', {
+        chatId: msgCtx.chatId,
+        bufferedCount: current.messages.length,
+      });
+      return;
+    }
+
+    const startedAt = Date.now();
+    this.entries.set(key, {
+      messages: [msgCtx],
+      startedAt,
+      timer: this.createTimer(key, startedAt),
+    });
+    this.logger.debug('Buffered direct message started', { chatId: msgCtx.chatId });
+  }
+
+  async flush(accountId: string, dialogId: string): Promise<void> {
+    await this.flushKey(this.getKey(accountId, dialogId));
+  }
+
+  take(accountId: string, dialogId: string): B24MsgContext | null {
+    const key = this.getKey(accountId, dialogId);
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+
+    clearTimeout(entry.timer);
+    this.entries.delete(key);
+    this.logger.debug('Taking buffered direct messages', {
+      chatId: dialogId,
+      bufferedCount: entry.messages.length,
+    });
+
+    return entry.messages.length === 1
+      ? entry.messages[0]
+      : mergeBufferedDirectMessages(entry.messages);
+  }
+
+  async flushAll(): Promise<void> {
+    for (const key of [...this.entries.keys()]) {
+      await this.flushKey(key);
+    }
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    for (const entry of this.entries.values()) {
+      clearTimeout(entry.timer);
+    }
+    this.entries.clear();
+  }
+
+  private getKey(accountId: string, dialogId: string): string {
+    return `${accountId}:${dialogId}`;
+  }
+
+  private createTimer(key: string, startedAt: number): ReturnType<typeof setTimeout> {
+    const delayMs = resolveDirectMessageCoalesceDelay({
+      startedAt,
+      now: Date.now(),
+      debounceMs: this.debounceMs,
+      maxWaitMs: this.maxWaitMs,
+    });
+    return setTimeout(() => {
+      void this.flushKey(key);
+    }, delayMs);
+  }
+
+  private async flushKey(key: string): Promise<void> {
+    const entry = this.entries.get(key);
+    if (!entry || this.destroyed) return;
+
+    clearTimeout(entry.timer);
+    this.entries.delete(key);
+
+    const msgCtx = entry.messages.length === 1
+      ? entry.messages[0]
+      : mergeBufferedDirectMessages(entry.messages);
+
+    try {
+      this.logger.debug('Flushing buffered direct messages', {
+        chatId: msgCtx.chatId,
+        bufferedCount: entry.messages.length,
+      });
+      await this.onFlush(msgCtx);
+    } catch (err) {
+      this.logger.error('Failed to flush buffered direct messages', err);
+    }
+  }
 }
 
 /** State held per running gateway instance */
 interface GatewayState {
+  accountId: string;
   api: Bitrix24Api;
+  bot: BotContext;
   sendService: SendService;
   mediaService: MediaService;
   inboundHandler: InboundHandler;
+  eventMode: 'fetch' | 'webhook';
 }
 
 let gatewayState: GatewayState | null = null;
 
-// ─── i18n helpers ────────────────────────────────────────────────────────────
-
-const I18N_MEDIA_DOWNLOAD_FAILED: Record<string, (files: string) => string> = {
-  en: (f) => `⚠️ Could not download file(s): ${f}.\n\nFile processing is currently only available for the primary user (webhook owner). This limitation will be removed in a future release.`,
-  ru: (f) => `⚠️ Не удалось загрузить файл(ы): ${f}.\n\nОбработка файлов пока доступна только для основного пользователя (автора вебхука). В будущих версиях это ограничение будет снято.`,
-  de: (f) => `⚠️ Datei(en) konnten nicht heruntergeladen werden: ${f}.\n\nDateiverarbeitung ist derzeit nur für den Hauptbenutzer (Webhook-Besitzer) verfügbar. Diese Einschränkung wird in einer zukünftigen Version behoben.`,
-  es: (f) => `⚠️ No se pudo descargar el/los archivo(s): ${f}.\n\nEl procesamiento de archivos actualmente solo está disponible para el usuario principal (propietario del webhook). Esta limitación se eliminará en una versión futura.`,
-  fr: (f) => `⚠️ Impossible de télécharger le(s) fichier(s) : ${f}.\n\nLe traitement des fichiers est actuellement réservé à l'utilisateur principal (propriétaire du webhook). Cette limitation sera levée dans une prochaine version.`,
-  pt: (f) => `⚠️ Não foi possível baixar o(s) arquivo(s): ${f}.\n\nO processamento de arquivos está disponível apenas para o usuário principal (dono do webhook). Essa limitação será removida em uma versão futura.`,
-};
-
-function mediaDownloadFailedMsg(lang: string | undefined, fileNames: string): string {
-  const code = (lang ?? 'en').toLowerCase().slice(0, 2);
-  const fn = I18N_MEDIA_DOWNLOAD_FAILED[code] ?? I18N_MEDIA_DOWNLOAD_FAILED.en;
-  return fn(fileNames);
+export function __setGatewayStateForTests(state: GatewayState | null): void {
+  gatewayState = state;
 }
 
 // ─── Default command keyboard ────────────────────────────────────────────────
@@ -79,8 +537,6 @@ export interface ChannelButton {
 
 /**
  * Convert OpenClaw button rows to B24 flat KEYBOARD array.
- * Input: Array<Array<{ text, callback_data, style }>>
- * Output: flat array with { TYPE: 'NEWLINE' } separators between rows.
  */
 export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
   const keyboard: B24Keyboard = [];
@@ -90,14 +546,12 @@ export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
       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;
       }
@@ -111,7 +565,6 @@ export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
       keyboard.push(b24Btn);
     }
 
-    // Add NEWLINE separator between rows (not after last row)
     if (i < rows.length - 1) {
       keyboard.push({ TYPE: 'NEWLINE' });
     }
@@ -122,7 +575,6 @@ export function convertButtonsToKeyboard(rows: ChannelButton[][]): B24Keyboard {
 
 /**
  * Extract B24 keyboard from a dispatcher payload's channelData.
- * Checks bitrix24-specific data first, then falls back to OpenClaw generic button format.
  */
 export function extractKeyboardFromPayload(
   payload: { channelData?: Record<string, unknown> },
@@ -130,13 +582,11 @@ export function extractKeyboardFromPayload(
   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 OpenClaw generic button format (channelData.telegram key)
   const tgData = cd.telegram as { buttons?: ChannelButton[][] } | undefined;
   if (tgData?.buttons?.length) {
     return convertButtonsToKeyboard(tgData.buttons);
@@ -145,105 +595,245 @@ export function extractKeyboardFromPayload(
   return undefined;
 }
 
+function normalizeCommandReplyPayload(params: {
+  commandName: string;
+  commandParams: string;
+  text: string;
+  language?: string;
+}): { text: string; convertMarkdown?: boolean } {
+  const { commandName, commandParams, text, language } = params;
+
+  if (commandName === 'models' && commandParams.trim() === '') {
+    const formattedText = formatModelsCommandReply(text, language);
+    if (formattedText) {
+      return { text: formattedText, convertMarkdown: false };
+    }
+  }
+
+  return { text };
+}
+
 /**
- * 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.
+ * Determine effective event mode from config.
+ */
+function resolveEventMode(config: Bitrix24AccountConfig): 'fetch' | 'webhook' {
+  return config.eventMode ?? (config.callbackUrl ? 'webhook' : 'fetch');
+}
+
+/**
+ * Generate a stable botToken from webhookUrl if not configured.
+ */
+function resolveBotToken(config: Bitrix24AccountConfig): string | null {
+  if (config.botToken) return config.botToken;
+  if (!config.webhookUrl) return null;
+  // Derive a stable token from webhookUrl (md5, max 32 chars — platform limit)
+  return createHash('md5').update(config.webhookUrl).digest('hex');
+}
+
+export function buildBotCodeCandidates(
+  config: Pick<Bitrix24AccountConfig, 'webhookUrl' | 'botCode'>,
+  maxCandidates = AUTO_BOT_CODE_MAX_CANDIDATES,
+): string[] {
+  if (config.botCode) {
+    return [config.botCode];
+  }
+
+  const webhookUserId = getWebhookUserId(config.webhookUrl);
+  const baseCode = webhookUserId ? `openclaw_${webhookUserId}` : 'openclaw';
+  const safeMaxCandidates = Math.max(1, maxCandidates);
+
+  return Array.from({ length: safeMaxCandidates }, (_value, index) => {
+    return index === 0 ? baseCode : `${baseCode}_${index + 1}`;
+  });
+}
+
+function isBotCodeAlreadyTakenError(error: unknown): boolean {
+  return error instanceof Bitrix24ApiError && error.code === 'BOT_CODE_ALREADY_TAKEN';
+}
+
+interface BotRegistrationState {
+  botId: number;
+  language?: string;
+  isNew: boolean;
+}
+
+function isFreshBotRegistration(bot: {
+  countMessage?: number;
+  countCommand?: number;
+  countChat?: number;
+  countUser?: number;
+}): boolean {
+  return (
+    (bot.countMessage ?? 0) === 0 &&
+    (bot.countCommand ?? 0) === 0 &&
+    (bot.countChat ?? 0) === 0 &&
+    (bot.countUser ?? 0) === 0
+  );
+}
+
+async function sendInitialWelcomeToWebhookOwner(params: {
+  config: Bitrix24AccountConfig;
+  bot: BotContext;
+  sendService: SendService;
+  language?: string;
+  welcomedDialogs: Set<string>;
+  logger: Logger;
+}): Promise<void> {
+  const { config, bot, sendService, language, welcomedDialogs, logger } = params;
+  const ownerId = getWebhookUserId(config.webhookUrl);
+  if (!ownerId || !config.webhookUrl || welcomedDialogs.has(ownerId)) {
+    return;
+  }
+
+  const sendCtx: SendContext = {
+    webhookUrl: config.webhookUrl,
+    bot,
+    dialogId: ownerId,
+  };
+  const isPairing = config.dmPolicy === 'pairing';
+  const text = onboardingMessage(language, config.botName ?? 'OpenClaw', config.dmPolicy);
+  const options = isPairing ? undefined : { keyboard: DEFAULT_COMMAND_KEYBOARD };
+
+  try {
+    await sendService.sendText(sendCtx, text, options);
+    welcomedDialogs.add(ownerId);
+    logger.info('Initial welcome sent to webhook owner', {
+      dialogId: ownerId,
+      language: language ?? 'en',
+    });
+  } catch (err) {
+    logger.warn('Failed to send initial welcome to webhook owner', err);
+  }
+}
+
+/**
+ * Register or update the bot using imbot.v2.Bot.register / Bot.update.
  */
 async function ensureBotRegistered(
   api: Bitrix24Api,
   config: Bitrix24AccountConfig,
+  botToken: string,
+  eventMode: 'fetch' | 'webhook',
   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)');
-    }
+): Promise<BotRegistrationState | null> {
+  const { webhookUrl, callbackUrl, botName } = config;
+
+  if (!webhookUrl) return null;
+
+  if (eventMode === 'webhook' && !callbackUrl) {
+    logger.warn('callbackUrl not configured for webhook mode — skipping bot registration');
     return null;
   }
 
-  const code = botCode ?? 'openclaw';
   const name = botName ?? 'OpenClaw';
+  const botCodeCandidates = buildBotCodeCandidates(config);
 
-  // Check if bot already exists
+  // Check if bot already exists via imbot.v2.Bot.list
   try {
-    const bots = await api.listBots(webhookUrl);
-    const existing = bots.find((b) => b.CODE === code);
+    const listResult = await api.listBots(webhookUrl, botToken);
+    const existing = botCodeCandidates
+      .map((candidate) => listResult.bots.find((botItem) => botItem.code === candidate))
+      .find(Boolean);
 
     if (existing) {
-      logger.info(`Bot "${code}" already registered (ID=${existing.ID}), updating EVENT_HANDLER`);
-      const updateProps: Record<string, unknown> = {
-        NAME: name,
-        WORK_POSITION: 'AI Assistant',
-        COLOR: 'RED',
+      logger.info(`Bot "${existing.code}" already registered (ID=${existing.id}), updating`);
+
+      const bot: BotContext = { botId: existing.id, botToken };
+      const updateFields: Record<string, unknown> = {
+        properties: {
+          name,
+          workPosition: 'AI Assistant',
+          avatar: config.botAvatar || DEFAULT_AVATAR_BASE64,
+        },
+        eventMode,
       };
-      updateProps.PERSONAL_PHOTO = config.botAvatar || DEFAULT_AVATAR_BASE64;
 
-      await api.updateBot(webhookUrl, existing.ID, {
-        EVENT_HANDLER: callbackUrl,
-        PROPERTIES: updateProps,
-      });
-      return existing.ID;
+      if (eventMode === 'webhook' && callbackUrl) {
+        updateFields.webhookUrl = callbackUrl;
+      }
+
+      await api.updateBot(webhookUrl, bot, updateFields);
+      return {
+        botId: existing.id,
+        language: existing.language,
+        isNew: false,
+      };
     }
   } 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: 'RED',
-        PERSONAL_PHOTO: config.botAvatar || DEFAULT_AVATAR_BASE64,
-      },
-    });
-    logger.info(`Bot "${code}" registered (ID=${botId})`);
-    return botId;
-  } catch (err) {
-    logger.error('Failed to register bot', err);
-    return null;
+  // Register new bot via imbot.v2.Bot.register
+  for (const code of botCodeCandidates) {
+    try {
+      const registerFields: {
+        code: string;
+        properties: { name: string; workPosition: string; avatar?: string };
+        type: string;
+        eventMode: 'fetch' | 'webhook';
+        webhookUrl?: string;
+      } = {
+        code,
+        properties: {
+          name,
+          workPosition: 'AI Assistant',
+          avatar: config.botAvatar || DEFAULT_AVATAR_BASE64,
+        },
+        type: 'personal',
+        eventMode,
+      };
+
+      if (eventMode === 'webhook' && callbackUrl) {
+        registerFields.webhookUrl = callbackUrl;
+      }
+
+      const result = await api.registerBot(webhookUrl, botToken, registerFields);
+      logger.info(`Bot "${code}" registered in ${eventMode} mode (ID=${result.bot.id})`);
+      return {
+        botId: result.bot.id,
+        language: result.bot.language,
+        isNew: isFreshBotRegistration(result.bot),
+      };
+    } catch (err) {
+      if (!config.botCode && isBotCodeAlreadyTakenError(err)) {
+        logger.warn(`Bot code "${code}" already taken, trying next candidate`);
+        continue;
+      }
+
+      logger.error('Failed to register bot', err);
+      return null;
+    }
   }
+
+  logger.error('Failed to register bot: exhausted automatic bot code candidates');
+  return null;
 }
 
 /**
- * Register OpenClaw slash commands with the B24 bot.
- * Runs in the background — errors are logged but don't block startup.
+ * Register OpenClaw slash commands with imbot.v2.Command.register.
+ * V2 Command.register is idempotent and doesn't need EVENT_COMMAND_ADD URL.
  */
 async function ensureCommandsRegistered(
   api: Bitrix24Api,
   config: Bitrix24AccountConfig,
-  botId: number,
+  bot: BotContext,
   logger: Logger,
 ): Promise<void> {
-  const { webhookUrl, callbackUrl } = config;
-  if (!webhookUrl || !callbackUrl) return;
+  const { webhookUrl } = config;
+  if (!webhookUrl) 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,
+      await api.registerCommand(webhookUrl, bot, {
+        command: cmd.command,
+        title: { en: cmd.en, ru: cmd.ru },
+        ...(cmd.params ? { params: { en: cmd.params, ru: cmd.params } } : {}),
       });
       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++;
@@ -257,11 +847,9 @@ async function ensureCommandsRegistered(
 }
 
 /**
- * Handle an incoming HTTP request on the webhook route.
- * Called by the HTTP route registered in index.ts.
+ * Handle an incoming HTTP request on the webhook route (V2 webhook mode).
  */
 export async function handleWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
-  // Always respond 200 quickly — B24 retries if it doesn't get a fast response
   if (req.method !== 'POST') {
     res.statusCode = 405;
     res.end('Method Not Allowed');
@@ -274,30 +862,121 @@ export async function handleWebhookRequest(req: IncomingMessage, res: ServerResp
     return;
   }
 
+  if (gatewayState.eventMode === 'fetch') {
+    res.statusCode = 200;
+    res.end('FETCH mode active');
+    return;
+  }
+
   // Read raw body
   const chunks: Buffer[] = [];
+  let bodySize = 0;
   for await (const chunk of req) {
-    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+    chunks.push(buffer);
+    bodySize += buffer.length;
+    if (bodySize > MAX_WEBHOOK_BODY_BYTES) {
+      res.statusCode = 413;
+      res.end('Payload Too Large');
+      req.destroy();
+      return;
+    }
   }
   const body = Buffer.concat(chunks).toString('utf-8');
 
-  // Respond immediately
-  res.statusCode = 200;
-  res.setHeader('Content-Type', 'text/plain');
-  res.end('ok');
-
-  // Process in background
   try {
-    await gatewayState.inboundHandler.handleWebhook(body);
+    const handled = await gatewayState.inboundHandler.handleWebhook(body);
+    if (!handled) {
+      res.statusCode = 400;
+      res.end('Invalid webhook payload');
+      return;
+    }
+
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ status: 'ok' }));
   } catch (err) {
-    defaultLogger.error('Error handling Bitrix24 webhook', err);
+    defaultLogger.error('Error handling Bitrix24 V2 webhook', err);
+    res.statusCode = 500;
+    res.end('Webhook processing failed');
+  }
+}
+
+// ─── Outbound adapter helpers ────────────────────────────────────────────────
+
+function resolveOutboundSendCtx(params: {
+  cfg: Record<string, unknown>;
+  to: string;
+  accountId?: string;
+}): SendContext | null {
+  const { config } = resolveAccount(params.cfg, params.accountId);
+  if (!config.webhookUrl || !gatewayState) return null;
+  return {
+    webhookUrl: config.webhookUrl,
+    bot: gatewayState.bot,
+    dialogId: params.to,
+  };
+}
+
+function collectOutboundMediaUrls(input: {
+  mediaUrl?: string;
+  payload?: { mediaUrl?: string; mediaUrls?: string[] };
+}): string[] {
+  const mediaUrls: string[] = [];
+
+  if (input.mediaUrl) {
+    mediaUrls.push(input.mediaUrl);
+  }
+
+  if (input.payload?.mediaUrl) {
+    mediaUrls.push(input.payload.mediaUrl);
   }
+
+  if (Array.isArray(input.payload?.mediaUrls)) {
+    mediaUrls.push(...input.payload.mediaUrls.filter((item) => typeof item === 'string'));
+  }
+
+  return [...new Set(mediaUrls)];
+}
+
+async function uploadOutboundMedia(params: {
+  sendCtx: SendContext;
+  mediaUrls: string[];
+  text?: string;
+}): Promise<string> {
+  if (!gatewayState) {
+    throw new Error('Bitrix24 gateway not started');
+  }
+
+  let lastMessageId = '';
+  let message = params.text;
+
+  for (const mediaUrl of params.mediaUrls) {
+    const result = await gatewayState.mediaService.uploadMediaToChat({
+      localPath: mediaUrl,
+      fileName: basename(mediaUrl),
+      webhookUrl: params.sendCtx.webhookUrl,
+      bot: params.sendCtx.bot,
+      dialogId: params.sendCtx.dialogId,
+      message: message || undefined,
+    });
+
+    if (!result.ok) {
+      throw new Error(`Failed to upload media: ${basename(mediaUrl)}`);
+    }
+
+    if (result.messageId) {
+      lastMessageId = String(result.messageId);
+    }
+
+    message = undefined;
+  }
+
+  return lastMessageId;
 }
 
 /**
  * The Bitrix24 channel plugin object.
- *
- * Implements the OpenClaw ChannelPlugin interface.
  */
 export const bitrix24Plugin = {
   id: 'bitrix24',
@@ -308,29 +987,25 @@ export const bitrix24Plugin = {
     selectionLabel: 'Bitrix24 (Messenger)',
     docsPath: '/channels/bitrix24',
     docsLabel: 'bitrix24',
-    blurb: 'Connect to Bitrix24 Messenger via chat bot REST API.',
+    blurb: 'Connect to Bitrix24 Messenger via chat bot REST API (V2).',
     aliases: ['b24', 'bx24'],
   },
 
   capabilities: {
-    chatTypes: ['direct', 'group'] as const,
+    chatTypes: ['direct'] as const,
     media: true,
-    reactions: false,
+    reactions: true,
     threads: false,
     nativeCommands: true,
     inlineButtons: 'all',
   },
 
   messaging: {
+    normalizeTarget: (raw: string) => raw.trim().replace(CHANNEL_PREFIX_RE, ''),
     targetResolver: {
       hint: 'Use a numeric chat/dialog ID, e.g. "1" or "chat42".',
-      /**
-       * Recognize any numeric string as a valid Bitrix24 target ID.
-       * B24 dialog IDs can be short (e.g. "1"), so the default 6+ digit check is too strict.
-       */
       looksLikeId: (raw: string, _normalized: string) => {
-        // raw may include channel prefix like "bitrix24:1" — strip it first
-        const stripped = raw.trim().replace(/^(bitrix24|b24|bx24):/i, '');
+        const stripped = raw.trim().replace(CHANNEL_PREFIX_RE, '');
         return /^\d+$/.test(stripped);
       },
     },
@@ -343,16 +1018,20 @@ export const bitrix24Plugin = {
   },
 
   security: {
-    resolveDmPolicy: (params: { cfg?: Record<string, unknown>; accountId?: string; account?: { config?: Record<string, unknown> } }) => ({
-      policy: (params.account?.config?.dmPolicy as string) ?? 'pairing',
-      allowFrom: (params.account?.config?.allowFrom as string[]) ?? [],
-      policyPath: 'channels.bitrix24.dmPolicy',
-      allowFromPath: 'channels.bitrix24.',
-      approveHint: 'openclaw pairing approve bitrix24 <CODE>',
-      normalizeEntry: (raw: string) => raw.replace(/^(bitrix24|b24|bx24):/i, ''),
-    }),
+    resolveDmPolicy: (params: { cfg?: Record<string, unknown>; accountId?: string; account?: { config?: Record<string, unknown> } }) => {
+      const securityConfig = resolveSecurityConfig(params);
+
+      return {
+        policy: securityConfig.dmPolicy === 'pairing' ? 'pairing' : 'webhookUser',
+        allowFrom: normalizeAllowList(securityConfig.allowFrom),
+        policyPath: 'channels.bitrix24.dmPolicy',
+        allowFromPath: 'channels.bitrix24.allowFrom',
+        approveHint: 'openclaw pairing approve bitrix24 <CODE>',
+        normalizeEntry: (raw: string) => raw.replace(CHANNEL_PREFIX_RE, ''),
+      };
+    },
     normalizeAllowFrom: (entry: string) =>
-      entry.replace(/^(bitrix24|b24|bx24):/i, ''),
+      entry.replace(CHANNEL_PREFIX_RE, ''),
   },
 
   pairing: {
@@ -360,113 +1039,209 @@ export const bitrix24Plugin = {
     normalizeAllowEntry: (entry: string) => normalizeAllowEntry(entry),
     notifyApproval: async (params: { cfg: Record<string, unknown>; id: string; runtime?: unknown }) => {
       const { config: acctCfg } = resolveAccount(params.cfg);
-      if (!acctCfg.webhookUrl) return;
-      const api = new Bitrix24Api();
+      if (!acctCfg.webhookUrl || !gatewayState) return;
+      const sendCtx: SendContext = {
+        webhookUrl: acctCfg.webhookUrl,
+        bot: gatewayState.bot,
+        dialogId: params.id,
+      };
       try {
-        await api.sendMessage(acctCfg.webhookUrl, params.id, '\u2705 OpenClaw access approved.');
-      } finally {
-        api.destroy();
+        await gatewayState.sendService.sendText(sendCtx, '\u2705 OpenClaw access approved.');
+      } catch (err) {
+        defaultLogger.warn('Failed to notify approved Bitrix24 user', err);
       }
     },
   } satisfies ChannelPairingAdapter,
 
   outbound: {
     deliveryMode: 'direct' as const,
+    textChunkLimit: 4000,
 
-    /**
-     * Send a text message to B24 via the bot.
-     * Called by OpenClaw when the agent produces a response.
-     */
-    sendText: async (params: {
+    sendText: async (ctx: {
+      cfg: Record<string, unknown>;
+      to: string;
+      accountId?: string;
       text: string;
-      context: B24MsgContext;
-      account: { config: { webhookUrl?: string; showTyping?: boolean } };
+      [key: string]: unknown;
     }) => {
-      const { text, context, account } = params;
+      const sendCtx = resolveOutboundSendCtx(ctx);
+      if (!sendCtx || !gatewayState) throw new Error('Bitrix24 gateway not started');
+      const result = await gatewayState.sendService.sendText(sendCtx, ctx.text);
+      return { messageId: String(result.messageId ?? '') };
+    },
 
-      if (!gatewayState) {
-        return { ok: false, error: 'Gateway not started', channel: 'bitrix24' };
+    sendMedia: async (ctx: {
+      cfg: Record<string, unknown>;
+      to: string;
+      accountId?: string;
+      text: string;
+      mediaUrl?: string;
+      [key: string]: unknown;
+    }) => {
+      const sendCtx = resolveOutboundSendCtx(ctx);
+      if (!sendCtx || !gatewayState) throw new Error('Bitrix24 gateway not started');
+
+      const mediaUrls = collectOutboundMediaUrls({ mediaUrl: ctx.mediaUrl });
+      if (mediaUrls.length > 0) {
+        const messageId = await uploadOutboundMedia({
+          sendCtx,
+          mediaUrls,
+          text: ctx.text,
+        });
+        return { messageId };
       }
 
-      const { sendService } = gatewayState;
+      if (ctx.text) {
+        const result = await gatewayState.sendService.sendText(sendCtx, ctx.text);
+        return { messageId: String(result.messageId ?? '') };
+      }
+      return { messageId: '' };
+    },
 
-      const sendCtx = {
-        webhookUrl: account.config.webhookUrl,
-        clientEndpoint: context.clientEndpoint,
-        botToken: context.botToken,
-        dialogId: context.chatId,
-      };
+    sendPayload: async (ctx: {
+      cfg: Record<string, unknown>;
+      to: string;
+      accountId?: string;
+      text: string;
+      mediaUrl?: string;
+      payload?: { channelData?: Record<string, unknown>; [key: string]: unknown };
+      [key: string]: unknown;
+    }) => {
+      const sendCtx = resolveOutboundSendCtx(ctx);
+      if (!sendCtx || !gatewayState) throw new Error('Bitrix24 gateway not started');
+
+      const keyboard = ctx.payload?.channelData
+        ? extractKeyboardFromPayload({ channelData: ctx.payload.channelData })
+        : undefined;
+      const mediaUrls = collectOutboundMediaUrls({
+        mediaUrl: ctx.mediaUrl,
+        payload: ctx.payload as { mediaUrl?: string; mediaUrls?: string[] } | undefined,
+      });
+
+      if (mediaUrls.length > 0) {
+        const uploadedMessageId = await uploadOutboundMedia({
+          sendCtx,
+          mediaUrls,
+        });
+
+        if (ctx.text) {
+          const result = await gatewayState.sendService.sendText(
+            sendCtx,
+            ctx.text,
+            keyboard ? { keyboard } : undefined,
+          );
+          return { messageId: String(result.messageId ?? uploadedMessageId) };
+        }
+
+        return { messageId: uploadedMessageId };
+      }
 
-      // Send typing indicator
-      if (account.config.showTyping !== false) {
-        await sendService.sendTyping(sendCtx);
+      if (ctx.text) {
+        const result = await gatewayState.sendService.sendText(
+          sendCtx,
+          ctx.text,
+          keyboard ? { keyboard } : undefined,
+        );
+        return { messageId: String(result.messageId ?? '') };
       }
+      return { messageId: '' };
+    },
+  },
 
-      // Send the response
-      const result = await sendService.sendText(sendCtx, text);
+  // ─── Actions (agent-driven: reactions, etc.) ────────────────────────────
 
-      return {
-        ok: result.ok,
-        messageId: result.messageId,
-        channel: 'bitrix24' as const,
-        error: result.error,
-      };
+  actions: {
+    listActions: (_params: { cfg: Record<string, unknown> }): string[] => {
+      return ['react'];
     },
 
-    /**
-     * 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;
+    supportsAction: (params: { action: string }): boolean => {
+      return params.action === 'react';
+    },
 
-      if (!gatewayState) {
-        return { ok: false, error: 'Gateway not started', channel: 'bitrix24' };
+    handleAction: async (ctx: {
+      action: string;
+      channel: string;
+      cfg: Record<string, unknown>;
+      accountId?: string;
+      params: Record<string, unknown>;
+      [key: string]: unknown;
+    }): Promise<Record<string, unknown> | null> => {
+      if (ctx.action !== 'react') return null;
+
+      // Helper: wrap payload as gateway-compatible tool result
+      const toolResult = (payload: Record<string, unknown>) => ({
+        content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+      });
+
+      const { config } = resolveAccount(ctx.cfg, ctx.accountId);
+      if (!config.webhookUrl || !gatewayState) {
+        return toolResult({ ok: false, reason: 'not_started', hint: 'Bitrix24 gateway not started. Do not retry.' });
       }
 
-      const { sendService } = gatewayState;
+      const bot = gatewayState.bot;
+      const api = gatewayState.api;
+      const params = ctx.params;
 
-      const sendCtx = {
-        webhookUrl: account.config.webhookUrl,
-        clientEndpoint: context.clientEndpoint,
-        botToken: context.botToken,
-        dialogId: context.chatId,
-      };
+      // Resolve messageId: explicit param → toolContext.currentMessageId fallback
+      const toolContext = (ctx as Record<string, unknown>).toolContext as
+        | { currentMessageId?: string | number } | undefined;
+      const rawMessageId = params.messageId ?? params.message_id ?? toolContext?.currentMessageId;
+      const messageId = Number(rawMessageId);
 
-      // Send typing indicator
-      if (account.config.showTyping !== false) {
-        await sendService.sendTyping(sendCtx);
+      if (!Number.isFinite(messageId) || messageId <= 0) {
+        return toolResult({ ok: false, reason: 'missing_message_id', hint: 'Valid messageId is required for Bitrix24 reactions. Do not retry.' });
       }
 
-      // Extract keyboard from channelData
-      const keyboard = channelData
-        ? extractKeyboardFromPayload({ channelData })
-        : undefined;
+      const emoji = String(params.emoji ?? '').trim();
+      const remove = params.remove === true || params.remove === 'true';
+
+      if (remove) {
+        // Remove reaction — need to know which one
+        const reactionCode = emoji ? resolveB24Reaction(emoji) : null;
+        if (!reactionCode) {
+          return toolResult({ ok: false, reason: 'missing_emoji', hint: 'Emoji is required to remove a Bitrix24 reaction.' });
+        }
+        try {
+          await api.deleteReaction(config.webhookUrl, bot, messageId, reactionCode);
+          return toolResult({ ok: true, removed: true });
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          return toolResult({ ok: false, reason: 'error', hint: `Failed to remove reaction: ${errMsg}. Do not retry.` });
+        }
+      }
 
-      const result = await sendService.sendText(
-        sendCtx,
-        text,
-        keyboard ? { keyboard } : undefined,
-      );
+      // Add reaction
+      if (!emoji) {
+        return toolResult({ ok: false, reason: 'missing_emoji', hint: 'Emoji is required for Bitrix24 reactions.' });
+      }
 
-      return {
-        ok: result.ok,
-        messageId: result.messageId,
-        channel: 'bitrix24' as const,
-        error: result.error,
-      };
+      const reactionCode = resolveB24Reaction(emoji);
+      if (!reactionCode) {
+        return toolResult({
+          ok: false,
+          reason: 'REACTION_NOT_FOUND',
+          emoji,
+          hint: `Emoji "${emoji}" is not supported for Bitrix24 reactions. Add it to your reaction disallow list so you do not try it again.`,
+        });
+      }
+
+      try {
+        await api.addReaction(config.webhookUrl, bot, messageId, reactionCode);
+        return toolResult({ ok: true, added: emoji });
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const isAlreadySet = errMsg.includes('REACTION_ALREADY_SET');
+        if (isAlreadySet) {
+          return toolResult({ ok: true, added: emoji, warning: 'Reaction already set.' });
+        }
+        return toolResult({ ok: false, reason: 'error', emoji, hint: `Reaction failed: ${errMsg}. Do not retry.` });
+      }
     },
   },
 
   gateway: {
-    /**
-     * Start a channel account. Called by OpenClaw for each configured account.
-     */
     startAccount: async (ctx: {
       cfg: Record<string, unknown>;
       accountId: string;
@@ -477,117 +1252,142 @@ export const bitrix24Plugin = {
       setStatus?: (status: Record<string, unknown>) => void;
     }) => {
       const logger = ctx.log ?? defaultLogger;
-      const config = getConfig(ctx.cfg);
+
+      // Guard: only one account can run at a time (singleton gateway)
+      if (gatewayState !== null) {
+        throw new Error(
+          `Bitrix24 channel already started for account "${gatewayState.accountId}". ` +
+          `Cannot start account "${ctx.accountId}" concurrently.`,
+        );
+      }
+
+      const config = getConfig(ctx.cfg, ctx.accountId);
 
       if (!config.webhookUrl) {
         logger.warn(`[${ctx.accountId}] no webhookUrl configured, skipping`);
         return;
       }
+      // Safe to use without ! after this point
+      const webhookUrl: string = config.webhookUrl;
 
       logger.info(`[${ctx.accountId}] starting Bitrix24 channel`);
 
-      // 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);
-      const mediaService = new MediaService(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 api = new Bitrix24Api({ logger });
+      const botToken = resolveBotToken(config);
+      if (!botToken) {
+        logger.error(`[${ctx.accountId}] cannot derive botToken — webhookUrl is missing`);
+        api.destroy();
+        return;
+      }
+      const welcomedDialogs = new Set<string>();
+      const deniedDialogs = new Map<string, number>();
+
+      // Cleanup stale denied dialog entries once per day
+      const DENIED_CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+      const deniedCleanupTimer = setInterval(() => {
+        deniedDialogs.clear();
+      }, DENIED_CLEANUP_INTERVAL_MS);
+      if (deniedCleanupTimer && typeof deniedCleanupTimer === 'object' && 'unref' in deniedCleanupTimer) {
+        deniedCleanupTimer.unref();
       }
 
-      const inboundHandler = new InboundHandler({
-        config,
-        logger,
+      // Determine event mode
+      const eventMode = resolveEventMode(config);
+      logger.info(`[${ctx.accountId}] event mode: ${eventMode}`);
 
-        onMessage: async (msgCtx: B24MsgContext) => {
-          logger.info('Inbound message', {
-            senderId: msgCtx.senderId,
-            chatId: msgCtx.chatId,
-            messageId: msgCtx.messageId,
-            textLen: msgCtx.text.length,
-          });
+      // Register or update bot on the B24 portal (V2 API)
+      const botRegistration = await ensureBotRegistered(api, config, botToken, eventMode, logger);
 
-          const runtime = getBitrix24Runtime();
-          const cfg = runtime.config.loadConfig();
+      if (!botRegistration) {
+        logger.error(`[${ctx.accountId}] bot registration failed, cannot start`);
+        clearInterval(deniedCleanupTimer);
+        api.destroy();
+        return;
+      }
 
-          // Pairing-aware access control
-          const accessResult = await checkAccessWithPairing({
-            senderId: msgCtx.senderId,
+      const bot: BotContext = { botId: botRegistration.botId, botToken };
+
+      // Sync user event subscription with agent mode setting
+      if (eventMode === 'fetch') {
+        try {
+          if (config.agentMode) {
+            await api.subscribeUserEvents(webhookUrl);
+            logger.info('User events subscription active (agent mode)');
+          } else {
+            await api.unsubscribeUserEvents(webhookUrl);
+            logger.debug('User events unsubscribed (agent mode off)');
+          }
+        } catch (err) {
+          logger.warn('Failed to sync user events subscription', err);
+        }
+      }
+
+      const sendService = new SendService(api, logger);
+      const mediaService = new MediaService(api, logger);
+      const processAllowedMessage = async (msgCtx: B24MsgContext): Promise<void> => {
+        const runtime = getBitrix24Runtime();
+        const cfg = runtime.config.loadConfig();
+        const sendCtx: SendContext = {
+          webhookUrl,
+          bot,
+          dialogId: msgCtx.chatId,
+        };
+        let downloadedMedia: DownloadedMedia[] = [];
+
+        try {
+          const replyStatusHeartbeat = createReplyStatusHeartbeat({
+            sendService,
+            sendCtx,
             config,
-            runtime,
-            accountId: ctx.accountId,
-            pairingAdapter: bitrix24Plugin.pairing,
-            sendReply: async (text: string) => {
-              const replySendCtx = {
-                webhookUrl: config.webhookUrl,
-                clientEndpoint: msgCtx.clientEndpoint,
-                botToken: msgCtx.botToken,
-                dialogId: msgCtx.chatId,
-              };
-              await sendService.sendText(replySendCtx, text, { convertMarkdown: false });
-            },
-            logger,
           });
 
-          if (accessResult !== 'allow') {
-            logger.debug(`Message blocked (${accessResult})`, { senderId: msgCtx.senderId });
-            return;
-          }
-
           // Download media files if present
           let mediaFields: Record<string, unknown> = {};
           if (msgCtx.media.length > 0) {
-            const downloaded = (await Promise.all(
-              msgCtx.media.map((m) =>
-                mediaService.downloadMedia({
-                  fileId: m.id,
-                  fileName: m.name,
-                  extension: m.extension,
-                  clientEndpoint: msgCtx.clientEndpoint,
-                  userToken: msgCtx.userToken,
-                  webhookUrl: config.webhookUrl,
-                }),
-              ),
+            await notifyStatus(sendService, sendCtx, config, 'IMBOT_AGENT_ACTION_PROCESSING');
+            replyStatusHeartbeat.holdFor(PHASE_STATUS_DURATION_SECONDS);
+
+            downloadedMedia = (await mapWithConcurrency(
+              msgCtx.media,
+              MEDIA_DOWNLOAD_CONCURRENCY,
+              (mediaItem) => mediaService.downloadMedia({
+                fileId: mediaItem.id,
+                fileName: mediaItem.name,
+                extension: mediaItem.extension,
+                webhookUrl,
+                bot,
+                dialogId: msgCtx.chatId,
+              }),
             )).filter(Boolean) as DownloadedMedia[];
 
-            if (downloaded.length > 0) {
+            if (downloadedMedia.length > 0) {
               mediaFields = {
-                MediaPath: downloaded[0].path,
-                MediaType: downloaded[0].contentType,
-                MediaUrl: downloaded[0].path,
-                MediaPaths: downloaded.map((m) => m.path),
-                MediaUrls: downloaded.map((m) => m.path),
-                MediaTypes: downloaded.map((m) => m.contentType),
+                MediaPath: downloadedMedia[0].path,
+                MediaType: downloadedMedia[0].contentType,
+                MediaUrl: downloadedMedia[0].path,
+                MediaPaths: downloadedMedia.map((mediaItem) => mediaItem.path),
+                MediaUrls: downloadedMedia.map((mediaItem) => mediaItem.path),
+                MediaTypes: downloadedMedia.map((mediaItem) => mediaItem.contentType),
               };
             } else {
-              // All file downloads failed — notify the user
-              const fileNames = msgCtx.media.map((m) => m.name).join(', ');
+              const fileNames = msgCtx.media.map((mediaItem) => mediaItem.name).join(', ');
               logger.warn('All media downloads failed, notifying user', { fileNames });
-              const errSendCtx = {
-                webhookUrl: config.webhookUrl,
-                clientEndpoint: msgCtx.clientEndpoint,
-                botToken: msgCtx.botToken,
-                dialogId: msgCtx.chatId,
-              };
               await sendService.sendText(
-                errSendCtx,
-                mediaDownloadFailedMsg(msgCtx.language, fileNames),
+                sendCtx,
+                mediaDownloadFailed(msgCtx.language, fileNames),
               );
               return;
             }
+          } else {
+            await notifyStatus(sendService, sendCtx, config, 'IMBOT_AGENT_ACTION_ANALYZING');
+            replyStatusHeartbeat.holdFor(PHASE_STATUS_DURATION_SECONDS);
           }
 
           // Use placeholder body for media-only messages
           let body = msgCtx.text;
           if (!body && msgCtx.media.length > 0) {
-            const hasImage = msgCtx.media.some((m) => m.type === 'image');
+            const hasImage = downloadedMedia.some((mediaItem) => mediaItem.contentType.startsWith('image/'))
+              || msgCtx.media.some((mediaItem) => mediaItem.type === 'image');
             body = hasImage ? '<media:image>' : '<media:document>';
           }
 
@@ -608,7 +1408,6 @@ export const bitrix24Plugin = {
             matchedBy: route.matchedBy,
           });
 
-          // Build and finalize inbound context for OpenClaw agent
           const inboundCtx = runtime.channel.reply.finalizeInboundContext({
             Body: body,
             BodyForAgent: body,
@@ -632,41 +1431,34 @@ export const bitrix24Plugin = {
             ...mediaFields,
           });
 
-          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) => {
-                  // Send media if present in reply
+                  await replyStatusHeartbeat.stopAndWait();
                   const mediaUrls = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
                   for (const mediaUrl of mediaUrls) {
-                    await mediaService.uploadMediaToChat({
+                    const uploadResult = await mediaService.uploadMediaToChat({
                       localPath: mediaUrl,
                       fileName: basename(mediaUrl),
-                      chatId: Number(msgCtx.chatInternalId),
-                      clientEndpoint: msgCtx.clientEndpoint,
-                      botToken: msgCtx.botToken,
+                      webhookUrl,
+                      bot,
+                      dialogId: msgCtx.chatId,
                     });
+
+                    if (!uploadResult.ok) {
+                      throw new Error(`Failed to upload media: ${basename(mediaUrl)}`);
+                    }
                   }
-                  // Send text if present
                   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);
-                  }
+                  await replyStatusHeartbeat.start();
                 },
                 onError: (err) => {
                   logger.error('Error delivering reply to B24', err);
@@ -674,29 +1466,205 @@ export const bitrix24Plugin = {
               },
             });
           } catch (err) {
-            logger.error('Error dispatching message to agent', err);
+            logger.error('Error dispatching message to agent', { senderId: msgCtx.senderId, chatId: msgCtx.chatId, error: err });
+          } finally {
+            replyStatusHeartbeat.stop();
           }
-        },
+        } finally {
+          await mediaService.cleanupDownloadedMedia(downloadedMedia.map((mediaItem) => mediaItem.path));
+        }
+      };
+      const directTextCoalescer = new BufferedDirectMessageCoalescer({
+        debounceMs: DIRECT_TEXT_COALESCE_DEBOUNCE_MS,
+        maxWaitMs: DIRECT_TEXT_COALESCE_MAX_WAIT_MS,
+        onFlush: processAllowedMessage,
+        logger,
+      });
+      const maybeNotifyDeniedDialog = async (
+        dialogId: string,
+        language: string | undefined,
+        sendCtx: SendContext,
+      ): Promise<void> => {
+        const now = Date.now();
+        const lastSentAt = deniedDialogs.get(dialogId) ?? 0;
+        if ((now - lastSentAt) < ACCESS_DENIED_NOTICE_COOLDOWN_MS) {
+          return;
+        }
+
+        deniedDialogs.set(dialogId, now);
+        try {
+          await sendService.sendText(
+            sendCtx,
+            personalBotOwnerOnly(language),
+            { convertMarkdown: false },
+          );
+        } catch (err) {
+          logger.warn('Failed to send access denied notice', err);
+        }
+      };
+
+      // Register slash commands (runs in background)
+      ensureCommandsRegistered(api, config, bot, logger).catch((err) => {
+        logger.warn('Command registration failed', err);
+      });
+
+      if (botRegistration.isNew) {
+        await sendInitialWelcomeToWebhookOwner({
+          config,
+          bot,
+          sendService,
+          language: botRegistration.language,
+          welcomedDialogs,
+          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 pendingForwardContext = msgCtx.isForwarded
+            ? directTextCoalescer.take(ctx.accountId, msgCtx.chatId)
+            : null;
 
-        onCommand: async (event: B24CommandEvent) => {
-          const cmdEntry = Object.values(event.data.COMMAND)[0];
-          if (!cmdEntry) {
-            logger.warn('No command entry in ONIMCOMMANDADD event');
+          if (msgCtx.isGroup) {
+            logger.warn('Group chat is not supported, leaving chat', {
+              chatId: msgCtx.chatId,
+              senderId: msgCtx.senderId,
+            });
+
+            try {
+              await api.leaveChat(webhookUrl, bot, msgCtx.chatId);
+            } catch (err) {
+              logger.error('Failed to leave group chat after message', err);
+            }
             return;
           }
 
-          const commandName = cmdEntry.COMMAND;
-          const commandParams = cmdEntry.COMMAND_PARAMS?.trim() ?? '';
-          const commandText = commandParams
-            ? `/${commandName} ${commandParams}`
-            : `/${commandName}`;
+          const runtime = getBitrix24Runtime();
+
+          // Pairing-aware access control
+          const sendCtx: SendContext = {
+            webhookUrl,
+            bot,
+            dialogId: msgCtx.chatId,
+          };
+
+          const accessResult = await checkAccessWithPairing({
+            senderId: msgCtx.senderId,
+            dialogId: msgCtx.chatId,
+            isDirect: msgCtx.isDm,
+            config,
+            runtime,
+            accountId: ctx.accountId,
+            pairingAdapter: bitrix24Plugin.pairing,
+            sendReply: async (text: string) => {
+              await sendService.sendText(sendCtx, text, { convertMarkdown: false });
+            },
+            logger,
+          });
 
-          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;
+          if (accessResult === 'deny') {
+            await sendService.markRead(sendCtx, toMessageId(msgCtx.messageId));
+            await maybeNotifyDeniedDialog(msgCtx.chatId, msgCtx.language, sendCtx);
+            logger.debug('Message blocked (deny)', { senderId: msgCtx.senderId, chatId: msgCtx.chatId });
+            return;
+          }
 
-          logger.info('Inbound command', { commandName, commandParams, senderId, dialogId });
+          await sendService.markRead(sendCtx, toMessageId(msgCtx.messageId));
+          await sendService.sendTyping(sendCtx);
+
+          if (accessResult !== 'allow') {
+            logger.debug(`Message blocked (${accessResult})`, { senderId: msgCtx.senderId });
+            return;
+          }
+
+          if (msgCtx.isForwarded) {
+            if (pendingForwardContext) {
+              logger.info('Merging forwarded message with buffered context', {
+                senderId: msgCtx.senderId,
+                chatId: msgCtx.chatId,
+                previousMessageId: pendingForwardContext.messageId,
+                forwardedMessageId: msgCtx.messageId,
+              });
+              await processAllowedMessage(mergeForwardedMessageContext(pendingForwardContext, msgCtx));
+              return;
+            }
+
+            logger.info('Forwarded message is not supported yet', {
+              senderId: msgCtx.senderId,
+              chatId: msgCtx.chatId,
+              messageId: msgCtx.messageId,
+            });
+            await sendService.sendText(
+              sendCtx,
+              forwardedMessageUnsupported(msgCtx.language),
+              { convertMarkdown: false },
+            );
+            return;
+          }
+
+          if (msgCtx.replyToMessageId) {
+            logger.info('Reply-to-message is not supported yet', {
+              senderId: msgCtx.senderId,
+              chatId: msgCtx.chatId,
+              messageId: msgCtx.messageId,
+              replyToMessageId: msgCtx.replyToMessageId,
+            });
+            await sendService.sendText(
+              sendCtx,
+              replyMessageUnsupported(msgCtx.language),
+              { convertMarkdown: false },
+            );
+            return;
+          }
+
+          if (canCoalesceDirectMessage(msgCtx, config)) {
+            directTextCoalescer.enqueue(ctx.accountId, msgCtx);
+            return;
+          }
+
+          await directTextCoalescer.flush(ctx.accountId, msgCtx.chatId);
+          await processAllowedMessage(msgCtx);
+        },
+
+        onCommand: async (cmdCtx: FetchCommandContext) => {
+          const {
+            commandId,
+            commandName,
+            commandParams,
+            commandText,
+            senderId,
+            dialogId,
+            chatType,
+            messageId,
+          } = cmdCtx;
+          const isDm = chatType === 'P';
+          const peerId = isDm ? senderId : dialogId;
+
+          logger.info('Inbound command', {
+            commandId,
+            commandName,
+            commandParams,
+            commandText,
+            senderId,
+            dialogId,
+            peerId,
+          });
+
+          const sendCtx: SendContext = {
+            webhookUrl,
+            bot,
+            dialogId: peerId,
+          };
 
           let runtime;
           let cfg;
@@ -708,16 +1676,35 @@ export const bitrix24Plugin = {
             return;
           }
 
-          // Pairing-aware access control (commands don't send pairing replies)
+          const commandMessageId = toMessageId(messageId);
+          const commandSendCtx: CommandSendContext | null = commandMessageId
+            ? {
+              ...sendCtx,
+              commandId,
+              messageId: commandMessageId,
+              commandDialogId: dialogId,
+            }
+            : null;
+
+          // Access control
           let accessResult;
           try {
             accessResult = await checkAccessWithPairing({
               senderId,
+              dialogId,
+              isDirect: isDm,
               config,
               runtime,
               accountId: ctx.accountId,
               pairingAdapter: bitrix24Plugin.pairing,
-              sendReply: async () => {},
+              sendReply: async (text: string) => {
+                if (commandSendCtx) {
+                  await sendService.answerCommandText(commandSendCtx, text, { convertMarkdown: false });
+                  return;
+                }
+
+                await sendService.sendText(sendCtx, text, { convertMarkdown: false });
+              },
               logger,
             });
           } catch (err) {
@@ -725,24 +1712,54 @@ export const bitrix24Plugin = {
             return;
           }
 
+          if (!commandMessageId || !commandSendCtx) {
+            logger.warn('Command event has invalid messageId, skipping response', { commandId, messageId, dialogId });
+            return;
+          }
+          const canMarkRead = dialogId === peerId;
+
+          await sendService.sendStatus(sendCtx, 'IMBOT_AGENT_ACTION_THINKING', 8);
+
+          if (accessResult === 'deny') {
+            if (canMarkRead) {
+              await sendService.markRead(sendCtx, commandMessageId);
+            }
+            await sendService.answerCommandText(
+              commandSendCtx,
+              personalBotOwnerOnly(cmdCtx.language),
+              { convertMarkdown: false },
+            );
+            logger.debug('Command blocked (deny)', { senderId, dialogId });
+            return;
+          }
+
+          if (canMarkRead) {
+            await sendService.markRead(sendCtx, commandMessageId);
+          }
+
           if (accessResult !== 'allow') {
             logger.debug(`Command blocked (${accessResult})`, { senderId });
             return;
           }
 
-          logger.debug('Command access allowed, resolving route', { commandText });
+          await directTextCoalescer.flush(ctx.accountId, peerId);
+
+          if (commandName === 'help' || commandName === 'commands') {
+            await sendService.sendText(
+              sendCtx,
+              buildCommandsHelpText(cmdCtx.language, { concise: commandName === 'help' }),
+              { keyboard: DEFAULT_COMMAND_KEYBOARD, convertMarkdown: false },
+            );
+            return;
+          }
 
           const route = runtime.channel.routing.resolveAgentRoute({
             cfg,
             channel: 'bitrix24',
             accountId: ctx.accountId,
-            peer: { kind: isDm ? 'direct' : 'group', id: dialogId },
+            peer: { kind: isDm ? 'direct' : 'group', id: peerId },
           });
 
-          logger.debug('Command route resolved', { sessionKey: route.sessionKey });
-
-          // Each command invocation gets a unique ephemeral session
-          // so the gateway doesn't treat it as "already handled".
           const slashSessionKey = `bitrix24:slash:${senderId}:${Date.now()}`;
 
           const inboundCtx = runtime.channel.reply.finalizeInboundContext({
@@ -752,130 +1769,206 @@ export const bitrix24Plugin = {
             CommandBody: commandText,
             CommandAuthorized: true,
             CommandSource: 'native',
-            CommandTargetSessionKey: `${route.sessionKey}:bitrix24:${dialogId}`,
-            From: `bitrix24:${dialogId}`,
+            CommandTargetSessionKey: `${route.sessionKey}:bitrix24:${peerId}`,
+            From: `bitrix24:${peerId}`,
             To: `slash:${senderId}`,
             SessionKey: slashSessionKey,
             AccountId: route.accountId,
             ChatType: isDm ? 'direct' : 'group',
-            ConversationLabel: user.NAME,
-            SenderName: user.NAME,
+            ConversationLabel: senderId,
+            SenderName: senderId,
             SenderId: senderId,
             Provider: 'bitrix24',
             Surface: 'bitrix24',
-            MessageSid: String(event.data.PARAMS.MESSAGE_ID),
+            MessageSid: messageId,
             Timestamp: Date.now(),
             WasMentioned: true,
             OriginatingChannel: 'bitrix24',
-            OriginatingTo: `bitrix24:${dialogId}`,
+            OriginatingTo: `bitrix24:${peerId}`,
           });
 
-          const sendCtx = {
-            webhookUrl: config.webhookUrl,
-            clientEndpoint: (cmdEntry.client_endpoint as string | undefined) ?? event.auth.client_endpoint,
-            botToken: cmdEntry.access_token,
-            dialogId,
-          };
-
-          logger.debug('Dispatching command to agent', { commandText, slashSessionKey });
+          const replyStatusHeartbeat = createReplyStatusHeartbeat({
+            sendService,
+            sendCtx,
+            config,
+          });
+          let commandReplyDelivered = false;
 
           try {
+            await replyStatusHeartbeat.start();
             await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
               ctx: inboundCtx,
               cfg,
               dispatcherOptions: {
                 deliver: async (payload) => {
-                  logger.debug('Command deliver callback', {
-                    hasText: !!payload.text,
-                    textLen: payload.text?.length ?? 0,
-                    hasMedia: !!(payload.mediaUrl || payload.mediaUrls?.length),
-                  });
+                  await replyStatusHeartbeat.stopAndWait();
                   if (payload.text) {
-                    // Use agent-provided keyboard if any, otherwise re-attach default command keyboard
                     const keyboard = extractKeyboardFromPayload(payload) ?? DEFAULT_COMMAND_KEYBOARD;
-                    await sendService.sendText(sendCtx, payload.text, { keyboard });
+                    const formattedPayload = normalizeCommandReplyPayload({
+                      commandName,
+                      commandParams,
+                      text: payload.text,
+                      language: cmdCtx.language,
+                    });
+                    if (!commandReplyDelivered) {
+                      commandReplyDelivered = true;
+                      if (isDm) {
+                        await sendService.sendText(sendCtx, formattedPayload.text, {
+                          keyboard,
+                          convertMarkdown: formattedPayload.convertMarkdown,
+                        });
+                        return;
+                      }
+
+                      await sendService.answerCommandText(commandSendCtx, formattedPayload.text, {
+                        keyboard,
+                        convertMarkdown: formattedPayload.convertMarkdown,
+                      });
+                      return;
+                    }
+
+                    await sendService.sendText(sendCtx, formattedPayload.text, {
+                      keyboard,
+                      convertMarkdown: formattedPayload.convertMarkdown,
+                    });
                   }
                 },
                 onReplyStart: async () => {
-                  if (config.showTyping !== false) {
-                    await sendService.sendTyping(sendCtx);
-                  }
+                  await replyStatusHeartbeat.start();
                 },
                 onError: (err) => {
                   logger.error('Error delivering command reply to B24', err);
                 },
               },
             });
-            logger.debug('Command dispatch completed', { commandText });
           } catch (err) {
-            logger.error('Error dispatching command to agent', err);
+            logger.error('Error dispatching command to agent', { commandName, senderId, dialogId, error: err });
+          } finally {
+            replyStatusHeartbeat.stop();
           }
         },
 
-        onJoinChat: async (event: B24JoinChatEvent) => {
-          const dialogId = event.data.PARAMS.DIALOG_ID;
-          const botEntry = Object.values(event.data.BOT)[0];
-          logger.info('Bot joined chat', {
-            dialogId,
-            userId: event.data.PARAMS.USER_ID,
-            hasBotEntry: !!botEntry,
-            botId: botEntry?.BOT_ID,
-            hasEndpoint: !!botEntry?.client_endpoint,
-            hasToken: !!botEntry?.access_token,
-          });
+        onJoinChat: async (joinCtx: FetchJoinChatContext) => {
+          const { dialogId, chatType, language } = joinCtx;
+          logger.info('Bot joined chat', { dialogId, chatType });
+
           if (!dialogId) return;
 
-          const welcomeText = `${config.botName ?? 'OpenClaw'} ready. Send me a message or pick a command below.`;
-          const welcomeOpts = { KEYBOARD: DEFAULT_COMMAND_KEYBOARD };
+          if (shouldSkipJoinChatWelcome({
+            dialogId,
+            chatType,
+            webhookUrl,
+            dmPolicy: config.dmPolicy,
+          })) {
+            logger.info('Skipping welcome for non-owner dialog in webhookUser mode', { dialogId });
+            return;
+          }
 
-          try {
-            // Prefer token-based call; fall back to webhook URL
-            if (botEntry?.client_endpoint && botEntry?.access_token) {
-              await api.sendMessageWithToken(
-                botEntry.client_endpoint,
-                botEntry.access_token,
-                dialogId,
-                welcomeText,
-                welcomeOpts,
-              );
-            } else if (config.webhookUrl) {
-              await api.sendMessage(config.webhookUrl, dialogId, welcomeText, welcomeOpts);
-            } else {
-              logger.warn('No way to send welcome message — no token and no webhookUrl');
-              return;
+          const sendCtx: SendContext = {
+            webhookUrl,
+            bot,
+            dialogId,
+          };
+
+          // Reject group chats
+          if (chatType === 'chat' || chatType === 'open') {
+            logger.info('Group chat not supported, leaving', { dialogId });
+            try {
+              await sendService.sendText(sendCtx, groupChatUnsupported(language));
+              await api.leaveChat(webhookUrl, bot, dialogId);
+            } catch (err) {
+              logger.error('Failed to leave group chat', err);
             }
+            return;
+          }
+
+          if (welcomedDialogs.has(dialogId)) {
+            logger.info('Skipping duplicate welcome for already welcomed dialog', { dialogId });
+            return;
+          }
+
+          // Send welcome message
+          const isPairing = config.dmPolicy === 'pairing';
+          const text = onboardingMessage(language, config.botName ?? 'OpenClaw', config.dmPolicy);
+          try {
+            await sendService.sendText(
+              sendCtx,
+              text,
+              isPairing ? undefined : { keyboard: DEFAULT_COMMAND_KEYBOARD },
+            );
+            welcomedDialogs.add(dialogId);
             logger.info('Welcome message sent', { dialogId });
-          } catch (err: unknown) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            logger.error('Failed to send welcome message', { error: errMsg, dialogId });
-            // Retry via webhook if token-based call failed
-            if (botEntry?.client_endpoint && config.webhookUrl) {
-              try {
-                await api.sendMessage(config.webhookUrl, dialogId, welcomeText, welcomeOpts);
-                logger.info('Welcome message sent via webhook fallback', { dialogId });
-              } catch (err2: unknown) {
-                const errMsg2 = err2 instanceof Error ? err2.message : String(err2);
-                logger.error('Welcome message webhook fallback also failed', { error: errMsg2, dialogId });
-              }
-            }
+          } catch (err) {
+            logger.error('Failed to send welcome message', err);
           }
         },
-      });
 
-      gatewayState = { api, sendService, mediaService, inboundHandler };
+        onBotDelete: async (_data: B24V2DeleteEventData) => {
+          logger.info('Bot deleted from portal');
+        },
+      });
 
-      logger.info(`[${ctx.accountId}] Bitrix24 channel started`);
+      gatewayState = { accountId: ctx.accountId, api, bot, sendService, mediaService, inboundHandler, eventMode };
+
+      logger.info(`[${ctx.accountId}] Bitrix24 channel started (${eventMode} mode)`);
+
+      // ─── Mode-specific lifecycle ──────────────────────────────────
+
+      if (eventMode === 'fetch') {
+        // FETCH mode: start polling loop (blocks until abort)
+        const pollingService = new PollingService({
+          api,
+          webhookUrl,
+          bot,
+          accountId: ctx.accountId,
+          pollingIntervalMs: config.pollingIntervalMs ?? 3000,
+          pollingFastIntervalMs: config.pollingFastIntervalMs ?? 100,
+          onEvent: async (event: B24V2FetchEventItem) => {
+            const fetchCtx: FetchContext = {
+              webhookUrl,
+              botId: bot.botId,
+              botToken: bot.botToken,
+            };
+            await inboundHandler.handleFetchEvent(event, fetchCtx);
+          },
+          abortSignal: ctx.abortSignal,
+          logger,
+        });
 
-      // Keep alive until abort signal
-      return new Promise<void>((resolve) => {
-        ctx.abortSignal.addEventListener('abort', () => {
-          logger.info(`[${ctx.accountId}] Bitrix24 channel stopping`);
+        try {
+          await pollingService.start();
+        } finally {
+          logger.info(`[${ctx.accountId}] Bitrix24 channel stopping (fetch)`);
+          clearInterval(deniedCleanupTimer);
+          await directTextCoalescer.flushAll();
+          directTextCoalescer.destroy();
           inboundHandler.destroy();
           api.destroy();
           gatewayState = null;
-          resolve();
+        }
+      } else {
+        // WEBHOOK mode: keep alive until abort signal
+        return new Promise<void>((resolve) => {
+          ctx.abortSignal.addEventListener('abort', () => {
+            const cleanup = async (): Promise<void> => {
+              logger.info(`[${ctx.accountId}] Bitrix24 channel stopping (webhook)`);
+              clearInterval(deniedCleanupTimer);
+              // Flush with timeout to prevent hanging
+              await Promise.race([
+                directTextCoalescer.flushAll(),
+                new Promise<void>((r) => setTimeout(r, 5000)),
+              ]);
+              directTextCoalescer.destroy();
+              inboundHandler.destroy();
+              api.destroy();
+              gatewayState = null;
+            };
+            cleanup().catch((err) => {
+              logger.error('Webhook cleanup error', err);
+            }).finally(() => resolve());
+          });
         });
-      });
+      }
     },
   },
 };