@ihazz/bitrix24 0.2.5 → 1.0.0

package/src/commands.ts

@@ -1,7 +1,7 @@
 /**
  * OpenClaw bot commands to register with Bitrix24.
  *
- * Standard OpenClaw bot commands registered via imbot.command.register.
+ * Standard OpenClaw bot commands registered via imbot.v2.Command.register.
  */
 
 export interface BotCommandDef {
@@ -9,52 +9,190 @@ export interface BotCommandDef {
   en: string;
   ru: string;
   params?: string;
+  group: 'status' | 'session' | 'options' | 'management' | 'tools' | 'export';
 }
 
+const SHORT_HELP_COMMANDS = new Set(['help', 'status', 'commands', 'new', 'models']);
+const COMMAND_META_COLOR = '#6C788A';
+const COMMAND_GROUP_ORDER = ['status', 'session', 'options', 'management', 'tools', 'export'] as const;
+const MODELS_PROVIDER_LINE_RE = /^[•*-]\s+([^()\s]+)\s+\((\d+)\)$/i;
+
+const COMMAND_GROUP_LABELS = {
+  ru: {
+    status: 'Справка и статус',
+    session: 'Сессия',
+    options: 'Параметры',
+    management: 'Управление',
+    tools: 'Инструменты',
+    export: 'Экспорт',
+  },
+  en: {
+    status: 'Help and status',
+    session: 'Session',
+    options: 'Options',
+    management: 'Management',
+    tools: 'Tools',
+    export: 'Export',
+  },
+} as const;
+
 /**
  * Standard OpenClaw commands.
  * Excludes: focus/unfocus/agents (Discord-specific), allowlist/bash (text-only scope).
  */
 export const OPENCLAW_COMMANDS: BotCommandDef[] = [
   // ── Status ──
-  { command: 'help', en: 'Show available commands', ru: 'Показать доступные команды' },
-  { command: 'commands', en: 'List all slash commands', ru: 'Список всех команд' },
-  { command: 'status', en: 'Show current status', ru: 'Показать текущий статус' },
-  { command: 'context', en: 'Explain how context is built', ru: 'Объяснить построение контекста' },
-  { command: 'whoami', en: 'Show your sender ID', ru: 'Показать ваш ID' },
-  { command: 'usage', en: 'Usage and cost summary', ru: 'Использование и стоимость', params: 'off|tokens|full|cost' },
+  { command: 'help', en: 'Show available commands', ru: 'Показать доступные команды', group: 'status' },
+  { command: 'commands', en: 'List all slash commands', ru: 'Список всех команд', group: 'status' },
+  { command: 'status', en: 'Show current status', ru: 'Показать текущий статус', group: 'status' },
+  { command: 'context', en: 'Explain how context is built', ru: 'Объяснить построение контекста', group: 'status' },
+  { command: 'whoami', en: 'Show your sender ID', ru: 'Показать ваш ID', group: 'status' },
+  { command: 'usage', en: 'Usage and cost summary', ru: 'Использование и стоимость', params: 'off | tokens | full | cost', group: 'status' },
 
   // ── Session ──
-  { command: 'new', en: 'Start a new session', ru: 'Начать новую сессию' },
-  { command: 'reset', en: 'Reset the current session', ru: 'Сбросить текущую сессию' },
-  { command: 'stop', en: 'Stop the current run', ru: 'Остановить текущий запуск' },
-  { command: 'compact', en: 'Compact the session context', ru: 'Сжать контекст сессии', params: 'instructions' },
-  { command: 'session', en: 'Manage session settings', ru: 'Настройки сессии', params: 'ttl|...' },
+  { command: 'new', en: 'Start a new session', ru: 'Начать новую сессию', group: 'session' },
+  { command: 'reset', en: 'Reset the current session', ru: 'Сбросить текущую сессию', group: 'session' },
+  { command: 'stop', en: 'Stop the current run', ru: 'Остановить текущий запуск', group: 'session' },
+  { command: 'compact', en: 'Compact the session context', ru: 'Сжать контекст сессии', params: 'instructions', group: 'session' },
+  { command: 'session', en: 'Manage session settings', ru: 'Настройки сессии', params: 'ttl | ...', group: 'session' },
 
   // ── Options ──
-  { command: 'model', en: 'Show or set the model', ru: 'Показать/сменить модель', params: 'model name' },
-  { command: 'models', en: 'List available models', ru: 'Список моделей', params: 'provider' },
-  { command: 'think', en: 'Set thinking level', ru: 'Уровень размышлений', params: 'off|low|medium|high' },
-  { command: 'verbose', en: 'Toggle verbose mode', ru: 'Подробный режим', params: 'on|off' },
-  { command: 'reasoning', en: 'Toggle reasoning visibility', ru: 'Видимость рассуждений', params: 'on|off|stream' },
-  { command: 'elevated', en: 'Toggle elevated mode', ru: 'Режим с расширенными правами', params: 'on|off|ask|full' },
-  { command: 'exec', en: 'Set exec defaults', ru: 'Настройки выполнения', params: 'host|security|ask|node' },
-  { command: 'queue', en: 'Adjust queue settings', ru: 'Настройки очереди', params: 'mode|debounce|cap|drop' },
+  { command: 'model', en: 'Show or set the model', ru: 'Показать/сменить модель', params: 'model name', group: 'options' },
+  { command: 'models', en: 'List available models', ru: 'Список моделей', params: 'provider', group: 'options' },
+  { command: 'think', en: 'Set thinking level', ru: 'Уровень размышлений', params: 'off | low | medium | high', group: 'options' },
+  { command: 'verbose', en: 'Toggle verbose mode', ru: 'Подробный режим', params: 'on | off', group: 'options' },
+  { command: 'reasoning', en: 'Toggle reasoning visibility', ru: 'Видимость рассуждений', params: 'on | off | stream', group: 'options' },
+  { command: 'elevated', en: 'Toggle elevated mode', ru: 'Режим с расширенными правами', params: 'on | off | ask | full', group: 'options' },
+  { command: 'exec', en: 'Set exec defaults', ru: 'Настройки выполнения', params: 'host | security | ask | node', group: 'options' },
+  { command: 'queue', en: 'Adjust queue settings', ru: 'Настройки очереди', params: 'mode | debounce | cap | drop', group: 'options' },
 
   // ── Management ──
-  { command: 'config', en: 'Show or set config values', ru: 'Показать/задать конфигурацию', params: 'show|get|set|unset' },
-  { command: 'debug', en: 'Set runtime debug overrides', ru: 'Отладочные настройки', params: 'show|reset|set|unset' },
-  { command: 'approve', en: 'Approve or deny exec requests', ru: 'Одобрить/отклонить запросы' },
-  { command: 'activation', en: 'Set group activation mode', ru: 'Режим активации в группах', params: 'mention|always' },
-  { command: 'send', en: 'Set send policy', ru: 'Политика отправки', params: 'on|off|inherit' },
-  { command: 'subagents', en: 'Manage subagent runs', ru: 'Управление субагентами' },
-  { command: 'kill', en: 'Kill a running subagent', ru: 'Остановить субагента', params: 'id|all' },
-  { command: 'steer', en: 'Send guidance to a subagent', ru: 'Направить субагента', params: 'message' },
+  { command: 'config', en: 'Show or set config values', ru: 'Показать/задать конфигурацию', params: 'show | get | set | unset', group: 'management' },
+  { command: 'debug', en: 'Set runtime debug overrides', ru: 'Отладочные настройки', params: 'show | reset | set | unset', group: 'management' },
+  { command: 'approve', en: 'Approve or deny exec requests', ru: 'Одобрить/отклонить запросы', group: 'management' },
+  { command: 'activation', en: 'Set group activation mode', ru: 'Режим активации в группах', params: 'mention | always', group: 'management' },
+  { command: 'send', en: 'Set send policy', ru: 'Политика отправки', params: 'on | off | inherit', group: 'management' },
+  { command: 'subagents', en: 'Manage subagent runs', ru: 'Управление субагентами', group: 'management' },
+  { command: 'kill', en: 'Kill a running subagent', ru: 'Остановить субагента', params: 'id | all', group: 'management' },
+  { command: 'steer', en: 'Send guidance to a subagent', ru: 'Направить субагента', params: 'message', group: 'management' },
 
   // ── Tools ──
-  { command: 'skill', en: 'Run a skill by name', ru: 'Запустить навык', params: 'name' },
-  { command: 'restart', en: 'Restart OpenClaw', ru: 'Перезапустить OpenClaw' },
+  { command: 'skill', en: 'Run a skill by name', ru: 'Запустить навык', params: 'name', group: 'tools' },
+  { command: 'restart', en: 'Restart OpenClaw', ru: 'Перезапустить OpenClaw', group: 'tools' },
 
   // ── Export ──
-  { command: 'export-session', en: 'Export session to HTML', ru: 'Экспорт сессии в HTML' },
+  { command: 'export-session', en: 'Export session to HTML', ru: 'Экспорт сессии в HTML', group: 'export' },
 ];
+
+export function buildCommandsHelpText(
+  lang: string | undefined,
+  options?: { concise?: boolean },
+): string {
+  const isRu = lang?.toLowerCase().startsWith('ru') ?? false;
+  const concise = options?.concise === true;
+  const defs = concise
+    ? OPENCLAW_COMMANDS.filter((def) => SHORT_HELP_COMMANDS.has(def.command))
+    : OPENCLAW_COMMANDS;
+  const labels = isRu ? COMMAND_GROUP_LABELS.ru : COMMAND_GROUP_LABELS.en;
+  const header = concise
+    ? (isRu ? '[B]Основные команды[/B]' : '[B]Key commands[/B]')
+    : (isRu ? '[B]Доступные команды[/B]' : '[B]Available commands[/B]');
+  const footer = concise
+    ? (isRu
+      ? `[COLOR=${COMMAND_META_COLOR}]Полный список:[/COLOR] ${formatCommandTrigger({
+        command: 'commands',
+      })}`
+      : `[COLOR=${COMMAND_META_COLOR}]Full list:[/COLOR] ${formatCommandTrigger({
+        command: 'commands',
+      })}`)
+    : '';
+
+  const sections = COMMAND_GROUP_ORDER
+    .map((group) => {
+      const groupDefs = defs.filter((def) => def.group === group);
+      if (groupDefs.length === 0) {
+        return '';
+      }
+
+      const lines = groupDefs.map((def) => formatCommandEntry(def, isRu));
+      if (concise) {
+        return lines.join('\n');
+      }
+
+      return [`[B]${labels[group]}[/B]`, ...lines].join('\n');
+    })
+    .filter(Boolean);
+
+  return [header, ...sections, footer]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+export function formatModelsCommandReply(
+  text: string,
+  lang?: string,
+): string | null {
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const providers: Array<{ name: string; count: string }> = [];
+
+  for (const line of lines) {
+    const match = line.match(MODELS_PROVIDER_LINE_RE);
+    if (!match) {
+      continue;
+    }
+    providers.push({ name: match[1], count: match[2] });
+  }
+
+  if (providers.length === 0) {
+    return null;
+  }
+
+  const isRu = lang?.toLowerCase().startsWith('ru') ?? false;
+  const header = isRu ? '[B]Провайдеры[/B]' : '[B]Providers[/B]';
+  const showModelsLabel = isRu
+    ? `[COLOR=${COMMAND_META_COLOR}]Посмотреть модели провайдера:[/COLOR]`
+    : `[COLOR=${COMMAND_META_COLOR}]Show provider models:[/COLOR]`;
+  const switchModelLabel = isRu
+    ? `[COLOR=${COMMAND_META_COLOR}]Сменить модель:[/COLOR]`
+    : `[COLOR=${COMMAND_META_COLOR}]Switch model:[/COLOR]`;
+
+  const providerLines = providers.map((provider) => {
+    return `• [send=/models ${provider.name}]${provider.name}[/send] [COLOR=${COMMAND_META_COLOR}](${provider.count})[/COLOR]`;
+  });
+
+  return [
+    header,
+    ...providerLines,
+    '',
+    `${showModelsLabel} [put=/models ]/models <provider>[/put]`,
+    `${switchModelLabel} [put=/model ]/model <provider/model>[/put]`,
+  ].join('\n');
+}
+
+function formatCommandEntry(def: BotCommandDef, isRu: boolean): string {
+  const description = isRu ? def.ru : def.en;
+  const paramsLabel = isRu ? 'Параметры' : 'Params';
+  const command = formatCommandTrigger(def);
+
+  if (!def.params) {
+    return `${command} — ${description}`;
+  }
+
+  return [
+    `${command} — ${description}`,
+    `[COLOR=${COMMAND_META_COLOR}]${paramsLabel}: ${def.params}[/COLOR]`,
+  ].join('\n');
+}
+
+function formatCommandTrigger(def: Pick<BotCommandDef, 'command' | 'params'>): string {
+  const visibleCommand = `/${def.command}`;
+
+  if (!def.params) {
+    return `[send=/${def.command}]${visibleCommand}[/send]`;
+  }
+
+  return `[put=/${def.command} ]${visibleCommand}[/put]`;
+}

package/src/config-schema.ts

@@ -3,12 +3,17 @@ import { z } from 'zod';
 const AccountSchema = z.object({
   enabled: z.boolean().optional().default(true),
   webhookUrl: z.string().url().optional(),
+  botToken: z.string().optional(),
   botName: z.string().optional().default('OpenClaw'),
-  botCode: z.string().optional().default('openclaw'),
+  botCode: z.string().optional(),
   botAvatar: z.string().optional(),
-  callbackUrl: z.string().url().optional(),
-  dmPolicy: z.enum(['open', 'allowlist', 'pairing']).optional().default('pairing'),
   allowFrom: z.array(z.string()).optional(),
+  callbackUrl: z.string().url().optional(),
+  eventMode: z.enum(['fetch', 'webhook']).optional(),
+  agentMode: z.boolean().optional().default(false),
+  pollingIntervalMs: z.number().int().min(500).optional().default(3000),
+  pollingFastIntervalMs: z.number().int().min(50).optional().default(100),
+  dmPolicy: z.enum(['pairing', 'webhookUser']).optional().default('webhookUser'),
   showTyping: z.boolean().optional().default(true),
   streamUpdates: z.boolean().optional().default(false),
   updateIntervalMs: z.number().int().min(500).optional().default(10000),

package/src/config.ts

@@ -1,4 +1,5 @@
 import type { Bitrix24PluginConfig, Bitrix24AccountConfig } from './types.js';
+import { Bitrix24ConfigSchema } from './config-schema.js';
 
 const DEFAULT_ACCOUNT_ID = 'default';
 
@@ -51,6 +52,16 @@ export function resolveAccount(
 } {
   const id = accountId || DEFAULT_ACCOUNT_ID;
   const config = getConfig(cfg, id);
+
+  // Validate config against Zod schema (validation only, no transform)
+  if (config.webhookUrl) {
+    const result = Bitrix24ConfigSchema.safeParse(config);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+      throw new Error(`[bitrix24] Invalid config for account "${id}": ${issues}`);
+    }
+  }
+
   return {
     accountId: id,
     config,

package/src/dedup.ts

@@ -10,6 +10,10 @@ export class Dedup {
   constructor(opts: { ttlMs?: number } = {}) {
     this.ttlMs = opts.ttlMs ?? 5 * 60 * 1000; // 5 minutes default
     this.cleanupTimer = setInterval(() => this.cleanup(), this.ttlMs);
+    // Don't prevent process exit if destroy() isn't called
+    if (this.cleanupTimer && typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+      this.cleanupTimer.unref();
+    }
   }
 
   /**

package/src/i18n.ts

@@ -0,0 +1,127 @@
+/**
+ * Internationalization module for user-facing strings.
+ * Supported languages: en, ru, de, es, fr, pt.
+ * Language code is resolved from B24 LANGUAGE field in event PARAMS.
+ */
+
+// ─── Locale resolver ─────────────────────────────────────────────────────────
+
+export function resolveLocale(lang: string | undefined): string {
+  return (lang ?? 'en').toLowerCase().slice(0, 2);
+}
+
+function resolve<T>(dict: Record<string, T>, lang: string | undefined): T {
+  const code = resolveLocale(lang);
+  return dict[code] ?? dict.en;
+}
+
+// ─── Media download failed ───────────────────────────────────────────────────
+
+const I18N_MEDIA_DOWNLOAD_FAILED: Record<string, (files: string) => string> = {
+  en: (f) => `\u26a0\ufe0f 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) => `\u26a0\ufe0f \u041d\u0435 \u0443\u0434\u0430\u043b\u043e\u0441\u044c \u0437\u0430\u0433\u0440\u0443\u0437\u0438\u0442\u044c \u0444\u0430\u0439\u043b(\u044b): ${f}.\n\n\u041f\u0440\u043e\u0432\u0435\u0440\u044c\u0442\u0435, \u0447\u0442\u043e \u0431\u043e\u0442 \u0441\u043e\u0441\u0442\u043e\u0438\u0442 \u0432 \u043d\u0443\u0436\u043d\u043e\u043c \u0434\u0438\u0430\u043b\u043e\u0433\u0435 \u0438 \u0443 \u043d\u0435\u0433\u043e \u0435\u0441\u0442\u044c \u0434\u043e\u0441\u0442\u0443\u043f \u043a \u044d\u0442\u043e\u043c\u0443 \u0444\u0430\u0439\u043b\u0443.`,
+  de: (f) => `\u26a0\ufe0f Datei(en) konnten nicht heruntergeladen werden: ${f}.\n\nDateiverarbeitung ist derzeit nur f\u00fcr den Hauptbenutzer (Webhook-Besitzer) verf\u00fcgbar. Diese Einschr\u00e4nkung wird in einer zuk\u00fcnftigen Version behoben.`,
+  es: (f) => `\u26a0\ufe0f No se pudo descargar el/los archivo(s): ${f}.\n\nEl procesamiento de archivos actualmente solo est\u00e1 disponible para el usuario principal (propietario del webhook). Esta limitaci\u00f3n se eliminar\u00e1 en una versi\u00f3n futura.`,
+  fr: (f) => `\u26a0\ufe0f Impossible de t\u00e9l\u00e9charger le(s) fichier(s) : ${f}.\n\nLe traitement des fichiers est actuellement r\u00e9serv\u00e9 \u00e0 l'utilisateur principal (propri\u00e9taire du webhook). Cette limitation sera lev\u00e9e dans une prochaine version.`,
+  pt: (f) => `\u26a0\ufe0f N\u00e3o foi poss\u00edvel baixar o(s) arquivo(s): ${f}.\n\nO processamento de arquivos est\u00e1 dispon\u00edvel apenas para o usu\u00e1rio principal (dono do webhook). Essa limita\u00e7\u00e3o ser\u00e1 removida em uma vers\u00e3o futura.`,
+};
+
+export function mediaDownloadFailed(lang: string | undefined, fileNames: string): string {
+  return resolve(I18N_MEDIA_DOWNLOAD_FAILED, lang)(fileNames);
+}
+
+// ─── Group chat unsupported ──────────────────────────────────────────────────
+
+const I18N_GROUP_CHAT_UNSUPPORTED: Record<string, string> = {
+  en: 'Sorry, I can only work in private messages. Please message me directly.',
+  ru: '\u0418\u0437\u0432\u0438\u043d\u0438\u0442\u0435, \u044f \u0440\u0430\u0431\u043e\u0442\u0430\u044e \u0442\u043e\u043b\u044c\u043a\u043e \u0432 \u043b\u0438\u0447\u043d\u044b\u0445 \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u044f\u0445. \u041d\u0430\u043f\u0438\u0448\u0438\u0442\u0435 \u043c\u043d\u0435 \u043d\u0430\u043f\u0440\u044f\u043c\u0443\u044e.',
+  de: 'Entschuldigung, ich arbeite nur in privaten Nachrichten. Bitte schreiben Sie mir direkt.',
+  es: 'Lo siento, solo funciono en mensajes privados. Por favor, escr\u00edbeme directamente.',
+  fr: 'D\u00e9sol\u00e9, je ne fonctionne qu\'en messages priv\u00e9s. Veuillez m\'\u00e9crire directement.',
+  pt: 'Desculpe, s\u00f3 funciono em mensagens privadas. Por favor, escreva-me diretamente.',
+};
+
+export function groupChatUnsupported(lang: string | undefined): string {
+  return resolve(I18N_GROUP_CHAT_UNSUPPORTED, lang);
+}
+
+// ─── Personal bot access denied ──────────────────────────────────────────────
+
+const I18N_PERSONAL_BOT_OWNER_ONLY: Record<string, string> = {
+  en: 'This bot is personal and accepts messages only from the bot owner.',
+  ru: 'Этот бот персональный и принимает сообщения только от владельца бота.',
+  de: 'Dieser Bot ist persoenlich und akzeptiert Nachrichten nur vom Bot-Besitzer.',
+  es: 'Este bot es personal y solo acepta mensajes del propietario del bot.',
+  fr: 'Ce bot est personnel et accepte uniquement les messages du proprietaire du bot.',
+  pt: 'Este bot e pessoal e aceita mensagens apenas do proprietario do bot.',
+};
+
+export function personalBotOwnerOnly(lang: string | undefined): string {
+  return resolve(I18N_PERSONAL_BOT_OWNER_ONLY, lang);
+}
+
+// ─── Reply-to-message unsupported ───────────────────────────────────────────
+
+const I18N_REPLY_MESSAGE_UNSUPPORTED: Record<string, string> = {
+  en: 'Replies to specific messages are not supported in the Bitrix24 integration yet. Please send your request as a new message for now. Support will appear in a future version.',
+  ru: 'Ответы на конкретные сообщения в интеграции Bitrix24 пока не поддерживаются. Пока что отправьте запрос отдельным новым сообщением. Поддержка появится в будущих версиях.',
+  de: 'Antworten auf bestimmte Nachrichten werden in der Bitrix24-Integration derzeit noch nicht unterstuetzt. Bitte senden Sie Ihre Anfrage vorerst als neue Nachricht. Die Unterstuetzung kommt in einer zukuenftigen Version.',
+  es: 'Las respuestas a mensajes concretos todavia no son compatibles en la integracion con Bitrix24. Por ahora, envia tu solicitud como un mensaje nuevo. Esta compatibilidad llegara en una version futura.',
+  fr: 'Les reponses a des messages precis ne sont pas encore prises en charge dans l integration Bitrix24. Pour le moment, envoyez votre demande comme un nouveau message. Cette prise en charge arrivera dans une prochaine version.',
+  pt: 'Respostas a mensagens especificas ainda nao sao suportadas na integracao com o Bitrix24. Por enquanto, envie sua solicitacao como uma nova mensagem. Esse suporte chegara em uma versao futura.',
+};
+
+export function replyMessageUnsupported(lang: string | undefined): string {
+  return resolve(I18N_REPLY_MESSAGE_UNSUPPORTED, lang);
+}
+
+const I18N_FORWARDED_MESSAGE_UNSUPPORTED: Record<string, string> = {
+  en: 'Forwarded messages are not supported in the Bitrix24 integration yet. Please send the text directly or upload the file/image as a regular message. Support will appear in a future version.',
+  ru: 'Пересланные сообщения в интеграции Bitrix24 пока не поддерживаются. Пока что отправьте текст напрямую или загрузите файл либо изображение обычным сообщением. Поддержка появится в будущих версиях.',
+  de: 'Weitergeleitete Nachrichten werden in der Bitrix24-Integration derzeit noch nicht unterstuetzt. Bitte senden Sie den Text direkt oder laden Sie die Datei bzw. das Bild als normale Nachricht hoch. Die Unterstuetzung kommt in einer zukuenftigen Version.',
+  es: 'Los mensajes reenviados todavia no son compatibles en la integracion con Bitrix24. Por ahora, envia el texto directamente o sube el archivo o la imagen como un mensaje normal. Esta compatibilidad llegara en una version futura.',
+  fr: 'Les messages transferes ne sont pas encore pris en charge dans l integration Bitrix24. Pour le moment, envoyez le texte directement ou telechargez le fichier ou l image comme un message normal. Cette prise en charge arrivera dans une prochaine version.',
+  pt: 'Mensagens encaminhadas ainda nao sao suportadas na integracao com o Bitrix24. Por enquanto, envie o texto diretamente ou carregue o arquivo ou a imagem como uma mensagem normal. Esse suporte chegara em uma versao futura.',
+};
+
+export function forwardedMessageUnsupported(lang: string | undefined): string {
+  return resolve(I18N_FORWARDED_MESSAGE_UNSUPPORTED, lang);
+}
+
+// ─── Onboarding messages ─────────────────────────────────────────────────────
+
+const I18N_WELCOME: Record<string, (botName: string) => string> = {
+  en: (n) => `${n} ready. Send me a message or pick a command below.`,
+  ru: (n) => `${n} \u0433\u043e\u0442\u043e\u0432. \u041d\u0430\u043f\u0438\u0448\u0438\u0442\u0435 \u043c\u043d\u0435 \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0435 \u0438\u043b\u0438 \u0432\u044b\u0431\u0435\u0440\u0438\u0442\u0435 \u043a\u043e\u043c\u0430\u043d\u0434\u0443 \u043d\u0438\u0436\u0435.`,
+  de: (n) => `${n} bereit. Senden Sie mir eine Nachricht oder w\u00e4hlen Sie einen Befehl unten.`,
+  es: (n) => `${n} listo. Env\u00edame un mensaje o elige un comando abajo.`,
+  fr: (n) => `${n} pr\u00eat. Envoyez-moi un message ou choisissez une commande ci-dessous.`,
+  pt: (n) => `${n} pronto. Envie-me uma mensagem ou escolha um comando abaixo.`,
+};
+
+export function welcomeMessage(lang: string | undefined, botName: string): string {
+  return resolve(I18N_WELCOME, lang)(botName);
+}
+
+const I18N_PAIRING_WELCOME: Record<string, (botName: string) => string> = {
+  en: (n) => `${n} ready. To start, send me any message and I will return a pairing code. Then approve it in OpenClaw with: openclaw pairing approve bitrix24 <CODE>`,
+  ru: (n) => `${n} \u0433\u043e\u0442\u043e\u0432. \u0427\u0442\u043e\u0431\u044b \u043d\u0430\u0447\u0430\u0442\u044c, \u043e\u0442\u043f\u0440\u0430\u0432\u044c\u0442\u0435 \u043c\u043d\u0435 \u043b\u044e\u0431\u043e\u0435 \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0435, \u0438 \u044f \u0432\u0435\u0440\u043d\u0443 \u043a\u043e\u0434 \u043f\u0440\u0438\u0432\u044f\u0437\u043a\u0438. \u0417\u0430\u0442\u0435\u043c \u043f\u043e\u0434\u0442\u0432\u0435\u0440\u0434\u0438\u0442\u0435 \u0435\u0433\u043e \u0432 OpenClaw \u043a\u043e\u043c\u0430\u043d\u0434\u043e\u0439: openclaw pairing approve bitrix24 <CODE>`,
+  de: (n) => `${n} ist bereit. Senden Sie mir eine beliebige Nachricht, dann gebe ich einen Pairing-Code zurueck. Bestaetigen Sie ihn danach in OpenClaw mit: openclaw pairing approve bitrix24 <CODE>`,
+  es: (n) => `${n} esta listo. Enviame cualquier mensaje y te devolvere un codigo de vinculacion. Luego apruebalo en OpenClaw con: openclaw pairing approve bitrix24 <CODE>`,
+  fr: (n) => `${n} est pret. Envoyez-moi n'importe quel message et je vous renverrai un code d'association. Ensuite, validez-le dans OpenClaw avec : openclaw pairing approve bitrix24 <CODE>`,
+  pt: (n) => `${n} esta pronto. Envie-me qualquer mensagem e eu retornarei um codigo de pareamento. Depois, aprove-o no OpenClaw com: openclaw pairing approve bitrix24 <CODE>`,
+};
+
+export function pairingWelcomeMessage(lang: string | undefined, botName: string): string {
+  return resolve(I18N_PAIRING_WELCOME, lang)(botName);
+}
+
+export function onboardingMessage(
+  lang: string | undefined,
+  botName: string,
+  dmPolicy: 'pairing' | 'webhookUser' | undefined,
+): string {
+  return dmPolicy === 'pairing'
+    ? pairingWelcomeMessage(lang, botName)
+    : welcomeMessage(lang, botName);
+}