npm package: @ihazz/bitrix24
Description: Bitrix24 Messenger channel for OpenClaw
Latest version: 2.0.0

# @ihazz/bitrix24

OpenClaw channel plugin for Bitrix24 Messenger based on Bot Platform 2.0 (`imbot.v2.*` / `im.v2.*`).

This is the official, Bitrix24-certified OpenClaw plugin for Bitrix24 Messenger.

## Providers

The plugin supports two providers for connecting to Bitrix24:

| Provider | Description | Recommended |
|---|---|---|
| **VibeCode** | Connects through the VibeCode Bot API proxy. Simpler setup, no webhook URL management. | Yes |
| **Native REST** | Connects directly to Bitrix24 REST API via an inbound webhook. Full control, requires webhook URL and scopes. | For advanced use cases |

### VibeCode (recommended)

VibeCode is the recommended provider for most deployments. It requires only an API key obtained from the VibeCode developer portal. No inbound webhook setup is needed.

### Native REST

The native provider connects directly to Bitrix24 REST API using an inbound webhook URL. Use this when you need full control over API scopes or are running in an environment that cannot reach the VibeCode proxy.

## Installation

```bash
openclaw plugins install @ihazz/bitrix24
```

Allow the plugin in `openclaw.json`:

```json
{
  "plugins": {
    "allow": ["bitrix24"]
  }
}
```

## Configuration

### VibeCode provider (recommended)

```json
{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-vibecode-api-key"
      }
    }
  }
}
```

### Native REST provider

```json
{
  "channels": {
    "bitrix24": {
      "provider": "native",
      "providerConfig": {
        "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123xyz456/"
      }
    }
  }
}
```

The `botToken` is auto-derived from `md5(webhookUrl)`. Set it explicitly in `providerConfig.botToken` only if your webhook URL may change and you want to preserve bot identity.

### SecretRef for production secrets

In production, avoid placing raw API keys or webhook URLs in config files. Use a SecretRef to reference environment variables:

```json
{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": { "source": "env", "id": "B24_VIBE_API_KEY" }
      }
    }
  }
}
```

A SecretRef object has `source` (currently only `"env"`) and `id` (the environment variable name). The plugin resolves the value at startup.

### Multi-account configuration

Multiple accounts can run within a single OpenClaw instance. This is useful for testing different providers side-by-side on the same Bitrix24 portal or for running multiple bots with different roles.

The root-level config defines the primary account. Additional accounts go into the `accounts` block and inherit root-level defaults (they can override any setting):

```json
{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-vibecode-api-key"
      },
      "botName": "Main Bot",
      "agentMode": true,
      "accounts": {
        "native": {
          "provider": "native",
          "providerConfig": {
            "webhookUrl": "https://your-portal.bitrix24.com/rest/1/abc123/"
          },
          "botName": "Native Bot",
          "agentMode": false
        }
      }
    }
  }
}
```

> **Important: Agent Mode is portal-wide.** When using multiple accounts on the same Bitrix24 portal, enable `agentMode` on only one account. The user event subscription is shared at the portal level — if one account subscribes and another unsubscribes, the subscription will be revoked for both.

> **Recommendation:** For production with different Bitrix24 portals, use a separate OpenClaw installation per portal. Multi-account in a single instance shares the LLM workspace, session history, and file storage between accounts, which may lead to unintended cross-talk. Separate installations provide full isolation.

## Configuration Options

| Parameter | Default | Description |
|---|---|---|
| `provider` | `"native"` | Provider to use: `"vibecode"` or `"native"`. |
| `providerConfig` | -- | Provider-specific credentials. For vibecode: `{ apiKey }`. For native: `{ webhookUrl, botToken? }`. |
| `botName` | `"OpenClaw"` | Bot display name. |
| `botCode` | auto | Optional explicit bot code. If omitted, the plugin registers the bot as `openclaw_<webhookUserId>` and falls back to `_2`, `_3`, etc. |
| `botAvatar` | -- | Optional base64 avatar override. |
| `allowFrom` | -- | Sender allowlist for `dmPolicy: "allowlist"` and as an approved-sender source for pairing/group overrides. |
| `dmPolicy` | `"keyOwner"` | Direct-message access policy: `keyOwner`, `pairing`, `allowlist`, `open`. |
| `groupPolicy` | `"keyOwner"` | Group-chat access policy: `disabled`, `keyOwner`, `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` | Enables combined polling with user-visible events and stores them in RAM history. Requires `im` scope for native provider. |
| `agentWatch` | -- | Watch rules for user-visible events captured through `agentMode`. |
| `pollingIntervalMs` | `3000` | Base poll interval for fetch mode. |
| `pollingFastIntervalMs` | `100` | Fast follow-up poll interval when more events are pending. |
| `verboseLog` | `false` | Enables detailed `info` and `debug` logs for development. |
| `urlRewriteMap` | -- | Origin rewrite map for file download URLs. Keys are source origins (e.g. `"https://internal.host"`), values are replacement origins. Useful when Bitrix24 returns hostnames unreachable from the bot server. |

## Access Policies

### Direct Messages

- `keyOwner` (recommended): only the key owner (webhook user or VibeCode API key owner) 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

### Group Chats

- `disabled`: bot sends a short notice and leaves the chat
- `keyOwner` (recommended): only the key 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

`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.

### Group Message Memory

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. RAM-backed context and cross-chat lookup still see the delivered group history regardless of reply rules.

### Group Watches

Per-group `watch` rules let the bot react to a specific user and only on selected topics:

```json
{
  "groups": {
    "chat615": {
      "watch": [
        { "userId": "77", "topics": ["secret", "contract"], "mode": "reply" }
      ]
    }
  }
}
```

- `mode: "reply"` answers in the group even if the normal group policy would otherwise require a mention
- `mode: "notifyOwnerDm"` sends the key owner a DM notice with a deep link, then tries a native forward and falls back to a quoted copy
- `groups["*"].watch` applies to every allowed group chat as a fallback

## Bitrix24 Setup (VibeCode Provider)

1. Go to [vibecode.bitrix24.tech](https://vibecode.bitrix24.tech/)
2. Sign in with your Bitrix24 account
3. Click **Create Bot** (or **Создать бота**)
4. Fill in the bot details:
   - **Name** -- display name for your bot in Bitrix24 Messenger
   - **Portal** -- select the Bitrix24 portal where the bot will be installed
5. After creation, copy the **API Key** from the bot settings page
6. Add the API key to your OpenClaw config:

```json
{
  "channels": {
    "bitrix24": {
      "provider": "vibecode",
      "providerConfig": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}
```

For production, use a SecretRef instead of a plain key (see [SecretRef](#secretref-for-production-secrets) above).

The VibeCode portal also shows bot activity logs and lets you manage installed bots across portals.

## Bitrix24 Setup (Native Provider)

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` for normal bot operation
   - `im` if you enable `agentMode`
   - add any extra scopes required by your Bitrix24 scenario
4. Save the webhook and copy the URL

The webhook URL contains credentials. Do not publish it or commit it to a repository.

## Agent Mode

When `agentMode: true` is enabled, the plugin:

- subscribes the key owner to `im.v2` event recording
- polls events 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

Combined with `agentWatch` rules, this enables the bot to monitor group chats for specific topics and notify the owner or respond when relevant messages appear.

## Inline Buttons

Add `inlineButtons` to channel capabilities:

```json
{ "capabilities": ["inlineButtons"] }
```

The plugin supports native Bitrix24 keyboard payload via `channelData.bitrix24.keyboard` and generic OpenClaw button rows via `channelData.telegram.buttons` (auto-converted). Markdown action links (`send:`, `put:`, `tel:`, `user:`, `chat:`, `context:`, `timestamp:`) are converted to native Bitrix24 BBCode.

## Rich Attachments

For Bitrix24 rich `ATTACH` blocks, pass a native payload through `channelData.bitrix24.attach` or `channelData.bitrix24.attachments`. This is separate from normal file upload via `mediaUrl` / `mediaUrls`.

## Verification

1. Start OpenClaw with the plugin enabled.
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 `keyOwner`, verify that only the key owner can use direct messages.
5. Add the bot to an allowed group and mention it.
6. Verify the bot answers when mentioned and stays silent when `requireMention: true` and no mention is present.

Local development checks:

```bash
npm test
npm run build
```

## Troubleshooting

- If the bot leaves a group immediately, check `groupPolicy`, `groupAllowFrom` and `groups`.
- If the bot stays in the group but does not answer, check `requireMention`.
- If the bot does not answer a user in group chat, check `groupPolicy`, `allowFrom`, and per-group overrides.
- If `agentMode` is enabled but user-visible events never appear, verify the webhook has the `im` scope (native provider).
- If file transfer fails, verify file size and that local uploads come from the OpenClaw workspace or managed media directory. If downloads fail with an unreachable host, add a `urlRewriteMap` entry to rewrite the origin.
- If using multi-account with `agentMode`, ensure only one account has it enabled per portal.

## Compatibility

| OpenClaw Version | Status |
|---|---|
| **v2026.4.1** | ✅ Recommended — fully tested, all features working |
| v2026.4.5 | ⚠️ Known issues — plugin skills not resolved from extensions directory, bot may fail to respond to messages |

Use OpenClaw **v2026.4.1** until the skill resolution issue in v2026.4.5 is fixed.

## Development

```bash
npm install
npm test
npm run build
```

## License

MIT