Developing a bot for the Bitrix24 internal chat

Bot Development for the Bitrix24 Internal Chat

The Bitrix24 internal chat is not just a messenger for team communication. CRM notifications, task reminders, and alerts from external systems all pass through it. A bot for the internal chat automates routine tasks: answers employee questions, aggregates data from different modules, and executes commands directly from the chat window.

How an Internal Bot Differs from a Client-Facing Bot

The fundamental difference lies in the audience and access permissions. A client-facing bot works in open lines; an internal bot works in the im module of Bitrix24 with full access to the portal's internal data.

An internal bot can:

• Retrieve CRM data, tasks, and projects via the REST API without open line restrictions.
• Use the permissions of a specific user (the bot performs actions on behalf of its owner user).
• Work in group chats, not only in private dialogs.
• Send rich messages with buttons, attach files from Bitrix24 Drive.

Registration is done via the same imbot.register, but without the OPENLINE: Y flag.

Typical Internal Bot Scenarios

HR bot. An employee writes /vacation 15.07–28.07 → the bot creates a vacation request via timeman.absence.create, notifies the manager, and marks the days in the calendar via calendar.event.add. No navigating through Bitrix24 sections required.

Reporting bot. A manager writes /report sales june → the bot calls crm.deal.list filtered by date and responsible employee → returns a summary directly in chat: number of deals, total amount, conversion by stage.

On-call bot. Monitors external systems (server, website, task queue) → when thresholds are exceeded, sends an alert to the on-call engineer's chat with "Acknowledged" and "Escalate" buttons.

IT helpdesk bot. An employee describes a problem → the bot creates a task in the support project via tasks.task.add, assigns a handler by rotation, and replies with a ticket number. Ticket status can be queried with /ticket 1234.

Registration and Command Handling

The bot is registered with a command handler specified:

POST /rest/imbot.register
{
  "CODE": "internal_helper",
  "EVENT_MESSAGE_ADD": "https://your-server.com/internal-bot/message",
  "EVENT_COMMAND_ADD": "https://your-server.com/internal-bot/command",
  "OPENLINE": "N"
}

Commands are registered via imbot.command.register:

{
  "BOT_ID": 456,
  "COMMAND": "report",
  "COMMON": "Y",
  "HIDDEN": "N",
  "EXTRANET_SUPPORT": "N",
  "LANG": [{"LANGUAGE_ID": "en", "TITLE": "Sales Report", "PARAMS": "period"}]
}

After registration, the command appears in chat autocomplete when typing /.

Case: Assistant Bot for the Sales Department

Task: 12 managers, frequent questions: "how many open deals do I have", "when was the last contact with client X", "what tasks do I have today".

Implementation: Python (FastAPI) + Bitrix24 REST API.

Commands:

• /deals → list of the manager's open deals with amounts and stages (from crm.deal.list, filtered by ASSIGNED_BY_ID = the user ID from event context).
• /client [name] → search for a contact/company + last activity (crm.activity.list).
• /tasks → today's tasks from tasks.task.list with a deadline on the current day.
• /call [phone] → initiate an outbound call via voip.call.start.

Authorization: the bot performs requests on behalf of the user who sent the command. To do this, USER_ID from the event is used + obtaining a user token via OAuth flow on first use. Tokens are stored in Redis with TTL = refresh token lifetime.

Result: each manager saves 15–20 minutes per day on interface navigation. System load is minimal — the bot makes 3–5 API calls per command.

Main challenge: token rotation. Bitrix24 REST tokens live for 1 hour, refresh tokens for 30 days. If a user hasn't used the bot for 30 days — re-authorization is required. Solution: use a webhook instead of OAuth for portal applications (a webhook doesn't expire, but has application-level permissions rather than per-user permissions).

Deployment and Reliability

The bot service must respond to the Bitrix24 webhook within 3 seconds. Otherwise Bitrix24 considers the request failed and retries it — resulting in duplicate messages.

Correct architecture:

1. Webhook receives the request, immediately returns 200 OK.
2. Task is placed in a queue (Redis Queue, RabbitMQ).
3. Worker processes the task asynchronously, replies via imbot.message.add.