Development of custom CRM robots for Bitrix24

Developing Custom Robots for Bitrix24 CRM

Standard robots are not enough: when a deal moves to the "Won" stage you need to automatically create a project in Jira, send the client's data to an ERP, and raise an invoice via 1C. None of these scenarios are covered by built-in actions. Time to write a custom robot.

Architecture of Custom Robots

Robots in Bitrix24 are a layer on top of the business process engine (bizproc). A custom robot is registered as a business process activity (CBPActivity) with a special FILTER flag that restricts its scope (CRM, specific entity types).

Two ways to create a custom robot:

1. Via REST API — method bizproc.robot.add. Registers an external webhook as a robot. Bitrix24 calls the URL when triggered, passes entity data, receives a response. Suitable for cloud Bitrix24, requires no access to the file system.

2. Via PHP module — a class is created that inherits \Bitrix\Bizproc\Activity\BaseActivity. Registered in RegisterModuleDependences on the OnBizProcActivityList event. Available only on on-premise Bitrix24 with server access.

Development via REST API (Cloud and On-premise)

This is the preferred approach for cloud portals. How it works:

Deal transitions to stage
  → Bitrix24 calls robot webhook (POST)
  → External server processes data
  → Server returns result to Bitrix24 via callback
  → Bitrix24 continues workflow execution

Robot registration via REST:

$client->call('bizproc.robot.add', [
    'CODE'         => 'MY_CUSTOM_ROBOT',
    'HANDLER'      => 'https://my-server.com/bitrix-robot-handler',
    'AUTH_USER_ID' => 1,
    'NAME'         => 'Create project in Jira',
    'PROPERTIES'   => [
        'project_key' => [
            'Name'     => 'Jira project key',
            'Type'     => 'string',
            'Required' => 'Y',
        ],
    ],
    'RETURN_PROPERTIES' => [
        'issue_id' => [
            'Name' => 'Jira issue ID',
            'Type' => 'string',
        ],
    ],
    'DOCUMENT_TYPE' => ['crm', 'CCrmDocumentDeal', 'DEAL'],
]);

The DOCUMENT_TYPE parameter determines which entities the robot is available for. For smart processes the type looks like ['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_{TYPE_ID}'].

Webhook Handler

Bitrix24 sends a POST request to the handler URL with the following fields:

{
  "event": "onBpActivityExecute",
  "data": {
    "WORKFLOW_ID": "...",
    "DOCUMENT_ID": ["crm", "CCrmDocumentDeal", "DEAL_123"],
    "PROPERTIES": {
      "project_key": "SALES"
    },
    "auth": { "access_token": "...", "domain": "portal.bitrix24.com" }
  }
}

The handler must return a response within 5 seconds — otherwise Bitrix24 considers the call hung. For long operations, async mode is used: the handler immediately returns {"status": "async"}, performs the work in the background, then reports the result via bizproc.event.send.

Development via PHP Module (On-premise Bitrix24)

For on-premise installations, a local module or component is created with activity registration:

// local/php_interface/init.php
AddEventHandler('bizproc', 'OnBizProcActivityList', function(&$arActivities) {
    $arActivities['MyCustomRobot'] = [
        'NAME'        => 'Create project in Jira',
        'DESCRIPTION' => 'Creates a Jira project from deal data',
        'TYPE'        => ['activity', 'robot_activity'],
        'CLASS'       => 'MyJiraRobot',
        'JSCLASS'     => 'BizProcActivity',
        'CATEGORY'    => ['ID' => 'integration'],
        'ROBOT_SETTINGS' => [
            'CATEGORY' => 'employee',
            'RETURN'   => ['ISSUE_ID' => ['Name' => 'Issue ID', 'Type' => 'string']],
        ],
        'FILTER'      => ['INCLUDE' => [['crm', 'CCrmDocumentDeal', 'DEAL']]],
    ];
});

The MyJiraRobot class inherits \Bitrix\Bizproc\Activity\BaseActivity and implements the execute() method, which is called when the robot fires.

Real Case: ERP Synchronisation Robot

Task: a manufacturing company, 150 deals per month. When a deal transitions to the "Order confirmed" stage, the system must:

1. Create an order in the ERP (SOAP API)
2. Write the ERP order number back to the deal field UF_CRM_ERP_ORDER_ID
3. Notify the responsible person in Bitrix24 about the result

Solution: a REST robot on a separate PHP server. The handler receives deal data, calls the ERP SOAP API asynchronously (a job in a Redis queue), and upon receiving the ERP response, updates the deal field via crm.deal.update and sends a notification via im.notify.system.add.

Issue encountered: the ERP sometimes responds in 30–40 seconds. Synchronous mode did not work — Bitrix24 marked the call as hung. Switching to async mode with bizproc.event.send resolved the problem. Retry logic was added for cases when the ERP is unavailable, with a retry after 5 minutes.

Result: manual entry of orders into the ERP disappeared entirely. Time from deal confirmation to order appearing in the ERP — 1–3 minutes.

Development Timeframes

Total development time for a custom robot — 1–2 weeks including design, development, and testing in a real pipeline.