Bitrix24 plugin

v1.4.x · updated 2026-10-14

The Bitrix24 plugin connects your agent to Bitrix24 as an internal employee instant-messaging channel. Staff message the agent the same way they would message a colleague, and the agent replies inside Bitrix24’s chat.

[!WARNING] Bitrix24 here is an internal employee IM channel — like Telegram or Slack for staff. It is not customer omnichannel: there are no Open Lines, no ticket queue and no operator escalation. Do not use this plugin to front a customer support line.

The plugin runs host-native and talks to the gateway over the aihummer.connector.v1 contract. End-user channel behaviour is on the channel page Bitrix24; this page covers the plugin itself.

The media and shared OAuth behavior below requires signed Core 1.4.15 and the separately signed connector 1.1.1 after catalog publication and update. An installed connector 1.1.0 does not establish that these features are available.

Facts

Field	Value
Version	1.1.1
Port	8810
Runtime	host-native

What it is

A two-way bridge between Bitrix24 chat and AiHummer. The agent appears as a human-like identity in Bitrix24 — each agent authenticates with its own OAuth identity rather than a generic bot account — so conversations feel like talking to a colleague. Access follows the organisation’s department-tree ACL, so an agent’s reach respects your Bitrix24 structure.

Configure dedicated portal users in BITRIX24_AGENT_USER_IDS and the portal in BITRIX24_PORTAL. Department routing admits employees; the agent account does not replace the person initiating a task. Optional existing automatic provisioning uses BITRIX24_ADMIN_LOGIN / BITRIX24_ADMIN_PASSWORD.

With the versions above, BITRIX24_VAULT_CONNECTIONS selects an existing, current, autonomous OAuth credential owned by the registering person. Use supported native vault/connection management; reuse its credential ID in tool bindings. The actual owner registers the running connector in its workspace at /v1/admin/connections/channel with a dedicated connection-token key. Set endpoint and apiKey by agent user ID inside the secret BITRIX24_VAULT_CONNECTIONS setting; never put them in agent profiles or prompts. Only the vault refreshes tokens; tools retain actor and sharing checks. See OAuth2.

How it is used

Inbound: the poller reads messages. Media is downloaded as bytes and registered through /v1/inbound/media; the agent receives media_id, rather than only a URL or file metadata.
Outbound: Deliver converts Markdown to BB-code and uploads actual bytes through im.v2.File.upload. Media confirmation needs real FILE_ID and message IDs; a text reply or link is not a file receipt.

Keep the durable delivery journal across updates. A confirmed duplicate operation returns its prior receipt. Partial or unknown effects are not automatically resent; check them before retrying.

employee ─▶ Bitrix24 chat ─▶ pull poller ─▶ gateway (router · turn) ─▶ Deliver (Markdown→BB-code, idempotent) ─▶ Bitrix24

Supported features

Reactions and @-mentions.
Typing and replies when the account and provider support im.dialog.writing and REPLY_ID.
Incoming images, audio, voice and files, with the version requirements above.
Message edit/delete only for legacy integrations with a separate bot identity; these are not advertised for ordinary OAuth users.

Limits

[!WARNING] Interactive keyboards, buttons and threads are not supported.

A generated or prepared file is not confirmed delivery. Keep partial, failed and unknown results visible.

Installation

Install Bitrix24 in one click from the marketplace in the admin UI. The host-native deployer downloads the plugin, runs its install step, renders a sandboxed systemd unit and waits for health before marking it ready — see Install & updates. You then connect each agent’s OAuth identity and map the department-tree ACL.

Security and limits

Internal employee IM only — not customer omnichannel.
Per-agent human-like OAuth identity — agents are not generic bot accounts.
Department-tree ACL — reach respects your org structure.
Host-native — runs under systemd, not in a container.