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).

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.