rustams/implement-b24-features

Implement Битрикс24 Features

Widgets (Embeds)

Widgets allow embedding your application into Битрикс24 UI (e.g., CRM tabs, menus).

Registration

Use placement.bind method (usually during app installation).

await $b24.callMethod('placement.bind', {
    PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
    HANDLER: 'https://your-domain.com/widget-handler', // Must be public URL
    TITLE: 'My Widget',
    DESCRIPTION: 'Widget description'
});

Handling

• Frontend: Create a page (e.g., pages/handler/my-widget.client.vue) that renders the widget content.
• Backend: Ensure the handler URL points to this page (or a backend endpoint that serves it).
• Context: Битрикс24 sends PLACEMENT_OPTIONS (e.g., ID of the deal) in the POST request.

Robots (Automation)

Robots are custom automation actions in Битрикс24.

Registration

Use bizproc.robot.add method.

await $b24.callMethod('bizproc.robot.add', {
    CODE: 'my_robot',
    HANDLER: 'https://your-domain.com/api/robot-handler', // Backend endpoint
    NAME: 'My Robot',
    PROPERTIES: {
        my_param: { Name: 'Parameter', Type: 'string' }
    }
});

Handling

• Backend: Create a public endpoint (e.g., /api/robot-handler) that receives the robot execution request.
• Logic: Perform the task (e.g., call external API).
• Result: If USE_SUBSCRIPTION is 'Y', call bizproc.event.send to return data to the workflow.

Events

Handle Битрикс24 events (e.g., ONCRMDEALADD).

Registration

Use event.bind method.

await $b24.callMethod('event.bind', {
    event: 'ONCRMDEALADD',
    handler: 'https://your-domain.com/api/events' // Backend endpoint
});

Handling

• Backend: Create a public endpoint (e.g., /api/events) to receive event data.
• Verification: Verify the request comes from Битрикс24 (check auth tokens).

Queues (RabbitMQ)

Use queues for background processing (long-running tasks).

• Configuration: ENABLE_RABBITMQ=1 in .env.
• PHP: Use Symfony Messenger (instructions/queues/php.md).
• Python: Use Celery (instructions/queues/python.md).
• Node.js: Use amqplib (instructions/queues/node.md).

Smart Process Management (CRM Types)

API Parameter Pitfalls

These are verified against the official REST API and must be followed exactly:

| Method | Key Parameter | Correct | Wrong | |--------|--------------|---------|-------| | crm.type.update | id | ordinal ID (from crm.type.list → id) | entityTypeId | | crm.type.get | id | ordinal ID | entityTypeId | | crm.category.* | entityTypeId | entityTypeId (e.g. 1136) | ordinal ID | | userfieldconfig.delete | moduleId | required "crm" | omitting it |

Userfield Enumeration Values

When creating enumeration (list) fields via userfieldconfig.add, values go in field.enum with lowercase keys:

payload = {
    "moduleId": "crm",
    "field": {
        "entityId": "CRM_99",
        "fieldName": "UF_CRM_99_MY_LIST",
        "userTypeId": "enumeration",
        "enum": [
            {"value": "Option 1", "def": "N", "sort": "10"},
            {"value": "Option 2", "def": "Y", "sort": "20"},
        ],
    },
}

Critical: uppercase keys (VALUE, DEF, SORT) are silently ignored — the field is created but with zero values. settings.LIST also does NOT work for userfieldconfig.add.

When reading back via userfieldconfig.get, values appear under field.enum (not settings.LIST).

Stage Ordering Constraint

Битрикс24 forbids creating intermediate (non-terminal) stages after a terminal stage (SEMANTICS: "S" or "F").

Strategy for programmatic stage sync:

1. Temporarily neutralize existing terminal stages: update SEMANTICS to "P" (process)
2. Create/update all intermediate stages
3. Set correct SEMANTICS on terminal stages last

SORT vs terminals (critical for new smart processes): even with neutralized semantics, Bitrix may reject crm.status.add for an intermediate if its SORT is greater than or equal to the SORT of an existing SUCCESS/FAIL row on the target portal (RU error like «Нельзя создать промежуточную стадию после успешной»). Snapshot SORT values from a reference process can be high while a freshly created process has terminals at lower SORT. Inbound fix: media_template_apply._apply_stages computes the minimum SORT among target rows matching template terminal suffixes and clamps SORT for new intermediate adds to sit below that floor. Tests: main/tests/test_media_template_stage_sync.py (test_strict_clamps_new_intermediate_sort_below_terminal).

Media template apply (Inbound): after crm.type.update enabling funnels, Bitrix may lag before crm.status.list shows default stages (NEW, PREPARATION, CLIENT). The installer polls (stage_sync_barrier) before syncing. Bitrix-generated intermediate codes UC_* not in the template are deleted before crm.status.add for canonical suffixes to avoid Duplicate STATUS_ID (crm.status.add REST docs).

Snapshot-Apply Pattern for Smart Processes

Reference implementation: backends/python/api/main/services/media_template_installer.py

Key design decisions:

• Source vs Target: snapshot captures from reference process; apply targets user-selected process
• Deep-merge caveat: when saving snapshots to JSON config, wipe old snapshot first (set None then save new) to avoid stale keys from deep merge
• Field name remapping: UF_CRM_{source_ordinal}_{suffix} → UF_CRM_{target_ordinal}_{suffix}

Best Practices

1. Public URLs: Handlers for Widgets, Robots, and Events MUST be publicly accessible (use Cloudpub in dev).
2. Authentication: Robots and Events send auth tokens in the request body. Use them to authorize API calls back to Битрикс24.
3. Idempotency: Event handlers should be idempotent as Битрикс24 might retry requests.
4. API Parameter Verification: Always check the official REST API docs (via MCP) for the correct parameter names — id vs entityTypeId confusion is a common source of silent failures.