@ihazz/bitrix24 1.0.3 → 1.1.0

package/README.md

@@ -5,13 +5,15 @@ OpenClaw channel plugin for Bitrix24 Messenger based on Bot Platform 2.0 (`imbot
 ## Current Status
 
 - Works with Bitrix24 Bot Platform 2.0
-- Supports direct messages only
+- Supports direct messages and group chats
+- Uses secure defaults: `dmPolicy: "webhookUser"` and `groupPolicy: "webhookUser"`
+- Supports optional pairing, allowlist and open access modes
+- Uses mention gating in groups by default with `requireMention: true`
+- Stores all delivered messages from chats where the bot is present in fast RAM history and relies on normal OpenClaw session files for long-term transcripts
 - Supports inbound and outbound media
-- Uses secure default access policy: `webhookUser`
-- Supports optional pairing flow for controlled approval
 - Production recommendation today: one portal per plugin instance
 
-Group chats are intentionally not supported. If the bot is added to a group chat, it sends a short notice and leaves the chat.
+If a group is disabled by policy or blocked by `groupAllowFrom`, the bot sends a short notice and leaves the chat.
 
 ## Installation
 
@@ -36,9 +38,9 @@ Create an inbound webhook in Bitrix24:
 1. Open **Apps** > **Developer resources** > **Other** > **Inbound webhook**
 2. Create a webhook for your OpenClaw bot
 3. Grant scopes:
-   - `imbot` — the minimum scope required for full bot operation
-   - `im` — reserved for future `agentMode` support; `agentMode` is not production-ready yet and will be available in future versions
-   - you may also grant any extra scopes beyond this set if they are needed for your Bitrix24 scenarios
+   - `imbot` for normal bot operation
+   - `im` if you enable `agentMode` to ingest user-visible events and agent-side watches
+   - add any extra scopes required by your Bitrix24 scenario
 4. Save the webhook and copy the URL
 
 Example webhook URL:
@@ -60,7 +62,49 @@ Minimal configuration:
       "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
       "botName": "OpenClaw",
       "dmPolicy": "webhookUser",
-      "showTyping": true
+      "groupPolicy": "webhookUser",
+      "requireMention": true,
+      "historyLimit": 100,
+      "showTyping": true, 
+      "capabilities": [
+        "inlineButtons",
+        "reactions"
+      ]
+    }
+  }
+}
+```
+
+Example with group overrides:
+
+```json
+{
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
+      "botName": "OpenClaw",
+      "dmPolicy": "webhookUser",
+      "groupPolicy": "webhookUser",
+      "groupAllowFrom": ["chat208", "615"],
+      "requireMention": true,
+      "historyLimit": 100,
+      "groups": {
+        "*": {
+          "requireMention": true
+        },
+        "chat208": {
+          "groupPolicy": "open",
+          "requireMention": false
+        },
+        "615": {
+          "groupPolicy": "allowlist",
+          "requireMention": true,
+          "allowFrom": ["20", "42"],
+          "watch": [
+            { "userId": "77", "topics": ["secret", "contract"] }
+          ]
+        }
+      }
     }
   }
 }
@@ -90,20 +134,93 @@ If `eventMode` is omitted, the plugin uses:
 | Parameter | Default | Description |
 |---|---|---|
 | `webhookUrl` | — | Bitrix24 REST webhook URL. Required. |
-| `callbackUrl` | — | Public HTTPS URL for webhook delivery mode. Required only for `eventMode: "webhook"`. |
 | `eventMode` | auto | `fetch` or `webhook`. Auto-selects from `callbackUrl` when omitted. |
+| `callbackUrl` | — | Public HTTPS URL for webhook delivery mode. Required only for `eventMode: "webhook"`. |
 | `botName` | `"OpenClaw"` | Bot display name. |
-| `botCode` | auto | Optional explicit bot code. If omitted, the plugin registers the bot as `openclaw_<webhookUserId>`, and if that code is occupied it tries `openclaw_<webhookUserId>_2`, `_3`, and so on. |
-| `botToken` | `md5(webhookUrl)` | Bot token for `imbot.v2` authentication (32-char hex string). If omitted, derived as `md5(webhookUrl)`. **Strongly recommended to set explicitly** if your `webhookUrl` may change (e.g. ngrok, dynamic DNS) — otherwise the plugin loses control of the previously registered bot. You can find the token in the Bitrix24 admin panel or compute it as `md5` of the original webhook URL. |
+| `botCode` | auto | Optional explicit bot code. If omitted, the plugin registers the bot as `openclaw_<webhookUserId>` and falls back to `_2`, `_3`, and so on if needed. |
+| `botToken` | `md5(webhookUrl)` | Bot token for `imbot.v2` authentication. Strongly recommended to set explicitly if your `webhookUrl` may change. |
 | `botAvatar` | — | Optional base64 avatar override. |
-| `dmPolicy` | `"webhookUser"` | Access policy: `webhookUser` or `pairing`. |
+| `allowFrom` | — | Sender allowlist for `dmPolicy: "allowlist"` and as an approved-sender source for pairing/group overrides. |
+| `dmPolicy` | `"webhookUser"` | Direct-message access policy: `webhookUser`, `pairing`, `allowlist`, `open`. |
+| `groupPolicy` | `"webhookUser"` | Group-chat access policy: `disabled`, `webhookUser`, `pairing`, `allowlist`, `open`. |
+| `groupAllowFrom` | — | Allowlist for group chats themselves. Values may be `dialogId` like `"chat208"` or numeric `chatId` like `"208"`. |
+| `requireMention` | `true` | When `true`, the bot answers in groups only when mentioned. Group messages are still added to RAM history. |
+| `historyLimit` | `100` | Maximum number of RAM history entries kept per conversation. |
+| `groups` | — | Per-group overrides keyed by `dialogId`, numeric `chatId`, or `"*"`. Each override may set `groupPolicy`, `requireMention`, `allowFrom`, and `watch`. |
 | `showTyping` | `true` | Sends typing indicator before response. |
 | `enabled` | `true` | Enables or disables the account. |
-| `agentMode` | `false` | Reserved for future user-event integration. Not working yet; planned for future versions. |
+| `agentMode` | `false` | Enables combined polling with `imbot.v2.Event.get(withUserEvents=true)`, subscribes the webhook owner to `im.v2` event recording in fetch mode, and stores delivered user-visible messages in RAM history without answering them directly. |
+| `agentWatch` | — | Watch rules for user-visible events captured through `agentMode`. Keys follow the same matching pattern as chats: direct dialog like `"77"`, group dialog like `"chat520"`, numeric chat id like `"520"`, or wildcard `"*"`. Only `mode: "notifyOwnerDm"` is supported. |
 | `pollingIntervalMs` | `3000` | Base poll interval for `fetch` mode. |
 | `pollingFastIntervalMs` | `100` | Fast follow-up poll interval when more events are pending. |
 
-### Agent-Driven Reactions
+Group override matching order:
+
+1. Exact `dialogId`, for example `"chat208"`
+2. Exact numeric `chatId`, for example `"208"`
+3. Fallback wildcard `"*"`
+
+## Scenario Presets
+
+The direct-message scenario is configured independently through `dmPolicy`. Group scenarios are controlled by `groupPolicy`, `requireMention`, optional `allowFrom`, and optional per-group `watch`.
+
+| Scenario | Behavior | Minimal settings |
+|---|---|---|
+| `1. One-on-one chat with the bot.` | The bot answers in a direct chat according to the selected DM access policy. | `dmPolicy: "webhookUser" \| "pairing" \| "allowlist" \| "open"` |
+| `2. Add the bot to a group chat where it responds to any message from any participant.` | The bot stores all delivered group messages in RAM history and answers every participant without mention. | `groupPolicy: "open"`, `requireMention: false` |
+| `3. Add the bot to a group chat where it responds only to mentions from any participant.` | The bot stores all delivered group messages in RAM history, but answers only when mentioned. | `groupPolicy: "open"`, `requireMention: true` |
+| `4. Add the bot to a group chat where it responds to all of my messages in that chat.` | The bot stores all delivered group messages in RAM history, but answers only the webhook owner and does not require mention. | `groupPolicy: "webhookUser"`, `requireMention: false` |
+| `5. Add the bot to a group chat where it responds only to my mentions in that chat.` | The bot stores all delivered group messages in RAM history, but answers only the webhook owner and only on mention. | `groupPolicy: "webhookUser"`, `requireMention: true` |
+| `6. Add the bot to a group chat where scenarios 2 through 5 apply only to users from my allowlist.` | The bot stores all delivered group messages in RAM history, but group replies are limited to the merged allowlist. | `groupPolicy: "allowlist"`, `allowFrom: ["77", "42"]`, plus `requireMention: false` or `true` |
+| `7. The bot can summarize or search messages from any direct or group chat it participates in.` | This is baseline behavior. All delivered messages are recorded in RAM history and can later be used for in-chat context or explicit cross-chat lookup. | No extra flag. Usually `historyLimit: 100`. Use explicit Bitrix24 chat mention like `[CHAT=520]Green Chat 15[/CHAT]` for cross-chat lookup. |
+| `8. In a group chat, the bot can watch a specific user and answer only on selected topics.` | The bot records all delivered messages and may answer watched users without mention when a watch rule matches. | `groups.<chat>.watch: [{ "userId": "77", "topics": ["secret", "contract"] }]` |
+| `9. In a group chat, the bot can watch a specific user or all users and notify the bot owner in DM with a forwarded copy of the matched message.` | The bot records all delivered messages. When a watch rule matches, it does not answer in the group and instead sends the webhook owner a DM notice with a context URL, plus a native forwarded message copy. | `groups.<chat>.watch: [{ "userId": "*", "topics": ["incident"], "mode": "notifyOwnerDm" }]` |
+| `10. The bot can watch all accessible group chats for a phrase and notify the bot owner in DM with a forwarded copy of the matched message.` | The bot records all delivered group messages. A wildcard group watch applies across every allowed group chat, even when a specific chat also has its own overrides. | `groups["*"].watch: [{ "userId": "*", "topics": ["incident"], "mode": "notifyOwnerDm" }]` |
+
+Default profile:
+
+- `dmPolicy: "webhookUser"`
+- `groupPolicy: "webhookUser"`
+- `requireMention: true`
+- `historyLimit: 100`
+
+## Agent Mode
+
+When `agentMode: true` is enabled in `fetch` mode, the plugin:
+
+- subscribes the webhook owner to `im.v2` event recording
+- polls `imbot.v2.Event.get` with `withUserEvents: true`
+- receives both normal bot events and additional user-visible message events
+- stores those additional user-visible messages in RAM history
+- never answers user-visible events directly as the bot
+
+This is mainly useful for owner-side watch rules and future agent-style retrieval scenarios.
+
+Example:
+
+```json
+{
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
+      "agentMode": true,
+      "agentWatch": {
+        "*": [
+          { "userId": "*", "topics": ["incident"], "mode": "notifyOwnerDm" }
+        ],
+        "77": [
+          { "userId": "*", "topics": ["urgent"], "mode": "notifyOwnerDm" }
+        ],
+        "chat520": [
+          { "userId": "*", "topics": ["release"], "mode": "notifyOwnerDm" }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Agent-Driven Reactions
 
 To enable agent-driven reactions, add `reactions` to the channel capabilities in your OpenClaw config:
 
@@ -118,9 +235,9 @@ To enable agent-driven reactions, add `reactions` to the channel capabilities in
 }
 ```
 
-The plugin maps standard Unicode emoji (👍, 🔥, 👀, etc.) to Bitrix24 reaction codes automatically. B24 reaction codes (like `like`, `fire`, `eyes`) can also be used directly.
+The plugin maps standard Unicode emoji to Bitrix24 reaction codes automatically. Native Bitrix24 reaction codes like `like`, `fire` and `eyes` also work.
 
-### Inline Buttons
+## Inline Buttons
 
 To enable agent-driven inline buttons, add `inlineButtons` to the channel capabilities in your OpenClaw config:
 
@@ -143,33 +260,74 @@ The plugin supports two button input forms:
 For converted generic buttons:
 
 - `callback_data` starting with `/` becomes a native Bitrix24 slash command button
-- any other `callback_data` becomes `ACTION=PUT`
-- `primary`, `attention`, and `danger` button styles are mapped to Bitrix24 color tokens
+- any other `callback_data` becomes `ACTION=SEND`
+- `primary`, `attention` and `danger` button styles are mapped to Bitrix24 color tokens
 
 ## Access Policies
 
-### `webhookUser`
+### Direct Messages
 
-Default and recommended mode for production.
+- `webhookUser`: only the Bitrix24 user from the webhook URL may talk to the bot
+- `pairing`: user must be approved through the OpenClaw pairing flow
+- `allowlist`: user must be present in `allowFrom`
+- `open`: any direct-message sender is allowed
 
-Only the Bitrix24 user whose ID is embedded in the webhook URL may talk to the bot. For a URL like:
+### Group Chats
 
-```text
-https://your-portal.bitrix24.com/rest/42/secret/
-```
+- `disabled`: bot sends a short notice and leaves the chat
+- `webhookUser`: only the webhook owner may use the bot in that group
+- `pairing`: sender must be approved; the public group receives only a short notice and never a pairing code
+- `allowlist`: sender must be allowed by merged `allowFrom` and per-group `groups.<key>.allowFrom`
+- `open`: any sender in the allowed group may use the bot
 
-only user `42` is allowed to use the bot in direct messages.
+`groupAllowFrom` controls whether the group itself is allowed at all. A matching explicit entry in `groups` also enables that group even if the top-level `groupAllowFrom` is set to a different list.
 
-### `pairing`
+### Group Message Memory
 
-Pairing mode allows a user to request access and wait for approval through the OpenClaw pairing flow.
+All delivered group messages are added to RAM history, even when the sender is not allowed to use the bot or when `requireMention: true` prevents an answer.
 
-Approval hint:
+This means:
 
-```bash
-openclaw pairing approve bitrix24 <CODE>
+- `groupPolicy` controls who may receive a reply in the group
+- `requireMention` controls whether an explicit Bitrix24 mention is required for that reply
+- RAM-backed context and cross-chat lookup still see the delivered group history regardless of those reply rules
+
+When `agentMode: true` is enabled, delivered user-visible messages are also written to RAM history. They are stored for context and watches only; the bot does not answer those user events directly.
+
+### Group Watches
+
+Per-group `watch` rules let the bot react to a specific user and only on selected topics:
+
+```json
+{
+  "channels": {
+    "bitrix24": {
+      "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/",
+      "groupPolicy": "webhookUser",
+      "requireMention": true,
+      "groups": {
+        "chat615": {
+          "watch": [
+            { "userId": "77", "topics": ["secret", "contract"], "mode": "reply" }
+          ]
+        }
+      }
+    }
+  }
+}
 ```
 
+For a matching `watch` rule:
+
+- the sender is matched by Bitrix24 user ID; use `"*"` to match any sender
+- `topics` are matched by normalized text inclusion / token prefix matching
+- `mode: "reply"` answers in the group even if the normal group policy would otherwise require a mention
+- `mode: "notifyOwnerDm"` sends the webhook owner a DM notice with a user mention and a deep link back to the original chat context, plus a native forwarded copy of the matched message instead of replying in the group
+- `groups["*"].watch` applies the same rule set to every allowed group chat
+- if a specific group also defines `watch`, those chat-specific rules are checked first and the wildcard rules remain available as a fallback
+
+If `mode` is omitted, `reply` is used.
+
 ## Delivery Modes
 
 ### `fetch`
@@ -187,19 +345,37 @@ openclaw pairing approve bitrix24 <CODE>
 ## Supported Behavior
 
 - Direct messages
+- Group chats with policy-driven access control
+- Mention gating in groups with `requireMention`
+- Group-specific overrides through `groups`
 - Typing indicators
 - Text replies with BBCode conversion
-- Inline keyboard buttons (`channelData.bitrix24.keyboard` and converted generic button rows)
-- Reactions (agent can add/remove reactions on messages via `imbot.v2.Chat.Message.Reaction.*`)
-- File upload to chat via `imbot.v2.File.upload`
+- Inline keyboard buttons
+- Reactions via `imbot.v2.Chat.Message.Reaction.*`
+- File upload via `imbot.v2.File.upload`
 - File download via `imbot.v2.File.download`
 - Slash command registration via `imbot.v2.Command.*`
 - Deduplication for repeated deliveries
 - Rate limiting for Bitrix24 API calls
+- RAM history cache for recent chat context
+- RAM history capture for all delivered group messages
+- Reply-to-message lookup from RAM cache with Bitrix24 API fallback
+- Forwarded-message hydration from Bitrix24 message context, including merge with buffered neighboring context when related events arrive close together
+- Cross-chat lookup from RAM memory by explicit Bitrix24 chat mention like `[CHAT=520]Green Chat 15[/CHAT]`
+- Topic watches for specific group users
+- Owner-DM watch notifications with native forwarded messages
+- Agent-mode ingestion of user-visible messages through combined polling
+- Agent-mode owner-DM watch notifications through `agentWatch`
+
+The RAM cache keeps up to `historyLimit` entries per conversation and uses an LRU cap of `1000` conversation keys per process.
 
 ## Not Supported
 
-- Group chat conversations
+- Persistent SQLite or search-based history layer
+- Persistent reply or forward search across chats beyond what Bitrix24 `Chat.Message.get` / `getContext` can return
+- “Reply to me in DM because this started in a group” behavior
+- Sending replies as the user through `im.v2.Chat.Message.*`
+- Agent-triggered user auto-replies or one-shot autoresponder flows
 - Production-ready multi-account operation in one process
 
 There is already account-config scaffolding in the plugin, but the current production recommendation is still one active Bitrix24 portal per instance.
@@ -207,18 +383,36 @@ There is already account-config scaffolding in the plugin, but the current produ
 ## Verification
 
 1. Start OpenClaw with the plugin enabled.
-2. Open a direct chat with the bot in Bitrix24.
-3. Send a message.
-4. Verify that the bot shows typing and returns a response.
-5. If `dmPolicy` is `webhookUser`, verify that only the webhook owner can talk to the bot.
+2. Open a direct chat with the bot in Bitrix24 and send a message.
+3. Verify the bot shows typing and returns a response.
+4. If `dmPolicy` is `webhookUser`, verify that only the webhook owner can use direct messages.
+5. Add the bot to an allowed group and mention it with the Bitrix24 format `[USER=<botId>]BotName[/USER]`.
+6. Verify the bot answers when mentioned and stays silent when `requireMention: true` and no mention is present.
+7. Verify that non-mentioned group messages still appear later in RAM-backed context.
+8. Reply to a recently seen message in the same chat and verify the bot keeps reply context.
+9. Forward a recent message and verify the plugin merges context when the forwarded event pair arrives together.
+10. In DM or another group, reference a visible chat as `[CHAT=<chatId>]ChatName[/CHAT]` and verify the bot can use RAM history from that chat.
+
+Local development checks:
+
+```bash
+npm test
+npm run build
+```
 
 ## Troubleshooting
 
-- Verify `webhookUrl` is valid and active.
-- If you use `eventMode: "webhook"`, verify `callbackUrl` is reachable from the internet over HTTPS.
-- Do not rely on `agentMode` yet. It is not working in the current release and is planned for future versions.
-- Do not expect the bot to work in group chats.
+- If the bot leaves a group immediately, check `groupPolicy`, `groupAllowFrom` and `groups`. A disabled or disallowed group is expected to receive a short notice and then be left.
+- If the bot stays in the group but does not answer, check `requireMention`. In live Bitrix24 payloads, mention markup arrives inside `message.text` as `[USER=<botId>]Name[/USER]`.
+- If the bot does not answer a user in group chat, check `groupPolicy`, `allowFrom`, and per-group overrides in `groups`.
+- If a group message seems to vanish from later context, verify that the message was actually delivered to the bot process and that it has not been evicted by `historyLimit` or the global RAM LRU.
+- If a per-group override does not apply, verify the key matching order: exact `dialogId`, then exact numeric `chatId`, then `"*"`.
+- If reply context is missing, the referenced message may be unavailable to the current bot type, no longer accessible through Bitrix24 `Chat.Message.get`, or absent from local RAM history.
+- If cross-chat lookup does not work, verify the query contains an explicit Bitrix24 chat mention like `[CHAT=520]Green Chat 15[/CHAT]` and that this chat has already appeared in RAM history during the current process lifetime.
+- If `eventMode: "webhook"` is used, verify `callbackUrl` is reachable from the internet over HTTPS.
+- If `agentMode` is enabled but user-visible events never appear, verify the webhook has the `im` scope and that `im.v2.Event.subscribe` succeeds for the webhook owner.
 - If file transfer fails, verify the file size and Bitrix24-side availability of the attachment.
+- If the bot still leaves every group after you changed config, make sure the deployed plugin code is current. Older builds contained unconditional “group chat is not supported, leaving” logic.
 
 ## Development
 

package/package.json

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

package/src/access-control.ts

@@ -1,4 +1,4 @@
-import type { Bitrix24AccountConfig } from './types.js';
+import type { Bitrix24AccountConfig, Bitrix24DmPolicy } from './types.js';
 import type { PluginRuntime, ChannelPairingAdapter } from './runtime.js';
 import { stripChannelPrefix } from './utils.js';
 
@@ -22,6 +22,10 @@ export function normalizeAllowList(entries: string[] | undefined): string[] {
   )];
 }
 
+export function isIdentityAllowed(identity: string, allowFrom: string[] | undefined): boolean {
+  return normalizeAllowList(allowFrom).includes(identity);
+}
+
 /**
  * Extract the owner user ID from a Bitrix24 inbound webhook URL.
  * Format: https://{portal}/rest/{user_id}/{webhook_token}/
@@ -55,15 +59,22 @@ export function checkAccess(
   config: Bitrix24AccountConfig,
   _options?: { dialogId?: string; isDirect?: boolean },
 ): boolean {
-  const dmPolicy = config.dmPolicy ?? 'webhookUser';
+  const dmPolicy = resolveDmPolicy(config.dmPolicy);
   const identity = resolveAccessIdentity(senderId);
 
-  if (dmPolicy === 'webhookUser') {
-    const webhookUserId = getWebhookUserId(config.webhookUrl);
-    return webhookUserId === identity;
+  switch (dmPolicy) {
+    case 'webhookUser': {
+      const webhookUserId = getWebhookUserId(config.webhookUrl);
+      return webhookUserId === identity;
+    }
+    case 'open':
+      return true;
+    case 'allowlist':
+      return isIdentityAllowed(identity, config.allowFrom);
+    case 'pairing':
+    default:
+      return false;
   }
-
-  return false;
 }
 
 export type AccessResult = 'allow' | 'deny' | 'pairing';
@@ -96,7 +107,15 @@ export async function checkAccessWithPairing(params: {
     logger,
   } = params;
   const identity = resolveAccessIdentity(senderId);
-  const dmPolicy = config.dmPolicy ?? 'webhookUser';
+  const dmPolicy = resolveDmPolicy(config.dmPolicy);
+
+  if (dmPolicy === 'open') {
+    return 'allow';
+  }
+
+  if (dmPolicy === 'allowlist') {
+    return isIdentityAllowed(identity, config.allowFrom) ? 'allow' : 'deny';
+  }
 
   if (dmPolicy === 'webhookUser') {
     const webhookUserId = getWebhookUserId(config.webhookUrl);
@@ -151,3 +170,7 @@ export async function checkAccessWithPairing(params: {
 function resolveAccessIdentity(senderId: string): string {
   return normalizeAllowEntry(String(senderId));
 }
+
+function resolveDmPolicy(policy: Bitrix24AccountConfig['dmPolicy']): Bitrix24DmPolicy {
+  return policy ?? 'webhookUser';
+}

package/src/api.ts

@@ -1,7 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import type {
   B24ApiResult,
   B24V2BotResult,
   B24V2BotListResult,
+  B24V2GetMessageContextResult,
+  B24V2GetMessageResult,
   B24V2SendMessageResult,
   B24V2ReadMessageResult,
   B24InputActionStatusCode,
@@ -261,28 +264,94 @@ export class Bitrix24Api {
     webhookUrl: string,
     bot: BotContext,
     dialogId: string,
-    message: string,
-    options?: { keyboard?: B24Keyboard; attach?: unknown; system?: boolean; urlPreview?: boolean },
+    message: string | null,
+    options?: {
+      keyboard?: B24Keyboard;
+      attach?: unknown;
+      system?: boolean;
+      urlPreview?: boolean;
+      forwardMessages?: number[];
+    },
   ): Promise<number> {
-    const fields: Record<string, unknown> = { message };
+    const fields: Record<string, unknown> = {};
+    if (typeof message === 'string') {
+      fields.message = message;
+    }
     if (options?.keyboard) fields.keyboard = options.keyboard;
     if (options?.attach) fields.attach = options.attach;
     if (options?.system !== undefined) fields.system = options.system;
     if (options?.urlPreview !== undefined) fields.urlPreview = options.urlPreview;
+    if (options?.forwardMessages?.length) {
+      fields.forwardIds = Object.fromEntries(
+        options.forwardMessages.map((forwardMessageId) => [randomUUID(), forwardMessageId]),
+      );
+    }
+
+    const params: Record<string, unknown> = {
+      botId: bot.botId,
+      botToken: bot.botToken,
+      dialogId,
+      fields,
+    };
 
     const result = await this.callWebhook<B24V2SendMessageResult>(
       webhookUrl,
       'imbot.v2.Chat.Message.send',
-      { botId: bot.botId, botToken: bot.botToken, dialogId, fields },
+      params,
     );
     const messageId = result.result?.id;
-    if (!Number.isFinite(messageId) || messageId <= 0) {
+    if (!Number.isFinite(messageId) || Number(messageId) <= 0) {
+      if (options?.forwardMessages?.length && typeof message !== 'string') {
+        return 0;
+      }
       throw new Bitrix24ApiError(
         'INVALID_RESPONSE',
         'imbot.v2.Chat.Message.send returned response without valid message id',
       );
     }
-    return messageId;
+    return Number(messageId);
+  }
+
+  /**
+   * Get a single message by id (imbot.v2.Chat.Message.get).
+   */
+  async getMessage(
+    webhookUrl: string,
+    bot: BotContext,
+    messageId: number,
+  ): Promise<B24V2GetMessageResult> {
+    const result = await this.callWebhook<B24V2GetMessageResult>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.get',
+      {
+        botId: bot.botId,
+        botToken: bot.botToken,
+        messageId,
+      },
+    );
+    return result.result;
+  }
+
+  /**
+   * Get message window around a message id (imbot.v2.Chat.Message.getContext).
+   */
+  async getMessageContext(
+    webhookUrl: string,
+    bot: BotContext,
+    messageId: number,
+    range?: number,
+  ): Promise<B24V2GetMessageContextResult> {
+    const result = await this.callWebhook<B24V2GetMessageContextResult>(
+      webhookUrl,
+      'imbot.v2.Chat.Message.getContext',
+      {
+        botId: bot.botId,
+        botToken: bot.botToken,
+        messageId,
+        ...(range ? { range } : {}),
+      },
+    );
+    return result.result;
   }
 
   /**
@@ -503,7 +572,7 @@ export class Bitrix24Api {
   async fetchEvents(
     webhookUrl: string,
     bot: BotContext,
-    params: { offset?: number; limit?: number },
+    params: { offset?: number; limit?: number; withUserEvents?: boolean },
   ): Promise<B24V2EventGetResult> {
     const result = await this.callWebhook<B24V2EventGetResult>(
       webhookUrl,