Bitrix24 is an internal employee instant-messaging channel — the same role
Telegram or Slack plays for staff. An AiHummer agent appears inside your
company’s Bitrix24 as a colleague that employees can message and mention.
The channel ships as a connector from the in-product
Marketplace and runs host-native. It is
configured from the Admin UI, like any other channel.
[!NOTE]
The Bitrix24 channel requires an active Starter, Business or
Enterprise licence. On the Community plan, installing the connector returns
HTTP 402 “upgrade required” (code plan_limit) — see
Licensing.
[!WARNING]
Bitrix24 here is strictly an internal employee IM channel. It is not
customer omnichannel, not Bitrix24 Open Lines, not a ticket queue, and
not an operator-escalation surface. Do not use it to route external
customer conversations.
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.
A human-like agent identity
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.
Ports and runtime
Port
Purpose
8810
Loopback connector service: health and Deliver
How messages flow
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.
What is supported
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.
[!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.
**Bitrix24 is an internal employee instant-messaging channel** — the same role
Telegram or Slack plays for staff. An AiHummer agent appears inside your
company's Bitrix24 as a colleague that employees can message and mention.
The channel ships as a **connector from the in-product
[Marketplace](/en/v1.4/marketplace/overview-tiers/)** and runs host-native. It is
configured from the Admin UI, like any other channel.
> [!NOTE]
> The Bitrix24 channel requires an active **Starter**, **Business** or
> **Enterprise** licence. On the Community plan, installing the connector returns
> **HTTP 402 "upgrade required"** (code `plan_limit`) — see
> [Licensing](/en/v1.4/commercial/licensing/).
> [!WARNING]
> Bitrix24 here is strictly an **internal employee IM channel**. It is **not**
> customer omnichannel, **not** Bitrix24 Open Lines, **not** a ticket queue, and
> **not** an operator-escalation surface. Do not use it to route external
> customer conversations.
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.
## A human-like agent identity
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](/en/v1.4/access/connections-oauth2/).
## Ports and runtime
| Port | Purpose |
|---|---|
| 8810 | Loopback connector service: health and Deliver |
## How messages flow
- 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.
## What is supported
- 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.
> [!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.
## Where to next
- On installing connectors: [Marketplace](/en/v1.4/marketplace/overview-tiers/).
- For interactive keyboards and polls, use [Telegram](/en/v1.4/channels/telegram/)
or [MAX](/en/v1.4/channels/max/).
- See the underlying ingestion API in
[Generic inbound](/en/v1.4/channels/generic-inbound/).
