Widgets in Tasks: Overview of Placements

Placements add the application interface to tasks: an item in the context menu of a task, an item in the dropdown menu above the list, a button in the automation rules designer, and a widget inside the task card.

All placements of the section require the task scope. The handler receives the call context: the identifier of a task, a user, or a project, depending on where the widget is opened from.

To register a widget, use the placement.bind method and pass the required code in the PLACEMENT parameter.

Quick navigation: all placements

How to Choose a PlacementHow to Choose a Placement

Choose a placement by the task your application solves:

• add an action to an individual task in the list — TASK_LIST_CONTEXT_MENU
• add an action to the whole task list — TASK_USER_LIST_TOOLBAR and TASK_GROUP_LIST_TOOLBAR
• extend task automation — TASK_ROBOT_DESIGNER_TOOLBAR
• add your own screen to the task card — TASK_VIEW_TAB, TASK_VIEW_SIDEBAR, or TASK_VIEW_TOP_PANEL

The three placements of the card used to differ in rendering location: a tab, the right panel, and a button in the top panel. Starting with the tasks 25.700.0 module version, the new task card was released, and none of them has a place of its own anymore — all three are rendered as identical rows in the "Applications" block. Previously registered widgets keep working, and one placement out of the three is enough for a new integration.

The menu of the workgroup or project itself belongs to another section: the SONET_GROUP_DETAIL_TAB and SONET_GROUP_TOOLBAR placements require the sonet_group scope and are called from the group menu, not from tasks. The SONET_GROUP_ROBOT_DESIGNER_TOOLBAR placement is rendered in the same automation rules designer as TASK_ROBOT_DESIGNER_TOOLBAR but belongs to the workgroups section.

How to Get StartedHow to Get Started

1. Choose a placement for your scenario.
2. Register the handler with the placement.bind method and pass the code in the PLACEMENT parameter. The method is available to an administrator only and requires the application context: a placement cannot be bound with a webhook.
3. Limit the widget to specific projects if you need to. The groupId connection parameter is supported only by the TASK_VIEW_TAB and TASK_VIEW_SIDEBAR placements.
4. Complete the application installation. Until then, the widget is not displayed in the interface.
5. Open the place in the interface and call the widget. Where exactly the item is located is described on each placement page in the "Where to Find It in the Interface" section.
6. Parse PLACEMENT_OPTIONS in the handler — it carries the call context: the identifier of a task, a user, or a project, and the address of the page the widget was opened from.

What the Handler ReceivesWhat the Handler Receives

All placements of the section pass the same set of standard parameters to the handler.

Parameters in the Handler URL Query String

Parameters in the POST Request Body

Bitrix24 adds a URI key to PLACEMENT_OPTIONS — the path with the query string of the page from which the widget was opened. It arrives for any placement, along with the keys of that placement itself. The key is absent if the browser did not send the Referer header or if the widget was opened from a page on a different domain.

How to Parse the Call Context

PLACEMENT_OPTIONS arrives as a JSON string, not as an array: parse it on the handler side before use. The set of keys is specific to each placement and is described in the PLACEMENT_OPTIONS section of this page.

$placement = $_POST['PLACEMENT'] ?? '';
        $options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
        

options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
        

In B24JsSDK, there is no need to parse the string: the $b24.placement.options property returns a ready object, and $b24.placement.placement returns the placement code.

What the Handler Must Return

The handler responds with a regular HTML page — Bitrix24 displays it in a frame in place of the widget. The page must allow embedding: if the application server sends the X-Frame-Options or Content-Security-Policy headers that prohibit framing, an empty area remains in place of the widget. How to fix it is described in the article Site Does Not Allow Connection.

PLACEMENT_OPTIONSPLACEMENT_OPTIONS

The PLACEMENT_OPTIONS value is passed as a JSON string with the call context. The universal URI key arrives for every placement, while the set of the remaining keys is specific to each placement.

The key that carries the task identifier is named differently across the section: ID in the context menu of the list and taskId in the card.

Connection with Other ObjectsConnection with Other Objects

Task. The identifier from PLACEMENT_OPTIONS indicates which task the handler was called for. Task data is returned by the tasks.task.get method.

User. The USER_ID key indicates whose task list or whose personal planner is open. User data is returned by the user.get method.

Workgroup and project. The GROUP_ID key indicates which group the task list or the automation belongs to. Group data is returned by the sonet_group.get method.

Call page. The universal URI key contains the path of the Bitrix24 page the widget was opened from.

Common MistakesCommon Mistakes

Overview of PlacementsOverview of Placements

Scope: placement, task

Continue LearningContinue Learning

• Register a Widget Handler placement.bind
• Get Placements Available to the Application placement.list
• Delete a Widget Handler placement.unbind
• Interaction with UI: Overview of Methods
• Methods of BX24 SDK for Widgets
• Interactivity in Applications: Overview of Scenarios and Methods