Developing a notification bot for Bitrix24

Development of Notification Bot for Bitrix24

A notification bot is a service agent in Bitrix24 that writes to employees in private chat when events occur: new lead, overdue task, order payment, server alert. Unlike standard B24 email notifications, the bot works in real time, reaches the Bitrix24 mobile app, and supports quick action buttons.

Bot Registration

The bot is registered via REST API with a single imbot.register call:

POST /rest/imbot.register
{
  "NAME": "Notifications",
  "CODE": "notify_bot",
  "TYPE": "S",  // S = System, not shown in contacts
  "COLOR": "GREEN",
  "PROPERTIES": {
    "OPENLINE": "N"
  }
}

After registration, Bitrix24 returns BOT_ID. This identifier is used to send messages on behalf of the bot.

Sending Notifications

A message to a user is sent via im.message.add or imbot.message.add. The difference: im.message.add creates a dialog on behalf of the OAuth application user; imbot.message.add — on behalf of a registered bot. For a notification bot, we use the second option.

$b24->callMethod('imbot.message.add', [
    'BOT_ID'    => $botId,
    'DIALOG_ID' => 'u' . $userId, // private chat with user
    'MESSAGE'   => '[b]New lead:[/b] ' . $leadTitle,
    'ATTACH'    => [
        [
            'TITLE'       => $leadTitle,
            'DESCRIPTION' => "Phone: {$phone}\nSource: {$source}",
            'COLOR'       => '#ff6600',
            'LINK'        => $crmUrl,
        ],
    ],
    'KEYBOARD'  => [
        'BUTTONS' => [[
            ['TEXT' => 'Open in CRM', 'LINK' => $crmUrl, 'BG_COLOR' => '#2fc6f6'],
            ['TEXT' => 'Take into work', 'COMMAND' => 'take_lead', 'COMMAND_PARAMS' => $leadId],
        ]],
    ],
]);

ATTACH — card formatting block. KEYBOARD — buttons under the message. When clicking a button with COMMAND, Bitrix24 sends an ONIMBOTMESSAGEADD event with the command type — the bot handles it as an action.

Event Sources for Notifications

CRM events. Register a handler on onCrmLeadAdd, onCrmDealUpdate via event.bind:

POST /rest/event.bind
{
  "event": "ONCRMDEALUPDATE",
  "handler": "https://your-server.com/webhook/deal-update"
}

When a deal moves to "Won" stage — bot writes congratulations to the manager and manager's supervisor with amount and link.

Tasks. Event onTaskUpdate — on status change, deadline change, assignee change. Bot notifies the right employee.

External systems. Monitoring (Zabbix, Prometheus Alertmanager) sends POST to server bot webhook-endpoint → bot writes to on-call engineer in chat. Similarly — payment systems, 1C, third-party CRM.

Schedule. Cron on bot server runs a script once an hour — checks overdue tasks via tasks.task.list, deals without activity for N+ days via crm.deal.list, and sends a summary to those responsible.

Typical Notification Scenarios

Group Notifications

Bot can write to group chats. DIALOG_ID in this case is the chat ID (chatXXX). To create a service chat for a project or department, use im.chat.add, bot is added as a participant via im.chat.user.add.

Queue and Reliability

If there are multiple event sources and many notifications — add a queue (Redis, RabbitMQ). The webhook handler immediately accepts the event and puts it in the queue (response 200 in < 1 second). Worker pulls from queue and sends to Bitrix24. This prevents message loss if REST API is temporarily unavailable.

Timeline

Total: 1–2 weeks depending on number of scenarios and event sources.