Пункт выпадающего меню над списком задач TASK_USER_LIST_TOOLBAR, TASK_GROUP_LIST_TOOLBAR

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: placement, task

Виджет добавляет свой пункт в выпадающее меню над списком задач. Точка работает со списком целиком, а не с отдельной задачей: обработчик получает идентификатор владельца списка — пользователя или рабочей группы.

Список задач пользователя и список задач группы — это две разные точки встраивания с разными кодами. Зарегистрируйте обе, если приложение должно работать в обоих списках.

Код точки встраивания указывается в параметре PLACEMENT метода placement.bind.

Виджет не отображается в интерфейсе, пока установка приложения не завершена. Проверьте установку приложения

Куда встраивается виджет

Код точки встраивания

Место

TASK_USER_LIST_TOOLBAR

Пункт выпадающего меню над списком задач пользователя

TASK_GROUP_LIST_TOOLBAR

Пункт выпадающего меню над списком задач рабочей группы или проекта

Где находится в интерфейсе

Откройте список задач и нажмите стрелку у кнопки в правой части панели над списком. Пункт приложения выводится в этом меню рядом с пунктами баз знаний и Маркетплейса. На самой кнопке стоит значок ••• или название пункта, который открывали последним.

Пункт выпадающего меню над списком задач пользователя

Пункт выпадающего меню над списком задач группы

Что получает обработчик

Данные передаются POST-запросом: часть параметров — в query-строке адреса обработчика, остальные — в теле запроса


Array
(
    [DOMAIN] => xxx.bitrix24.com
    [PROTOCOL] => 1
    [LANG] => ru
    [APP_SID] => 4617fa96af5d1f523fc2e2b72bd54f11
    [AUTH_ID] => 5253ba6600705a0700005a4b00000001f0f1076fef51e6d3d3c1616a9fd92a71
    [AUTH_EXPIRES] => 3600
    [REFRESH_ID] => 42d2e16600705a0700005a4b00000001f0f107cf69d8060249da353587f8ec86
    [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
    [APPLICATION_TOKEN] => 3f0a7c19e5b84d2196c8ad470e5f2b31
    [APPLICATION_SCOPE] => task,placement
    [member_id] => da45a03b265edd8787f8a258d793cc5d
    [status] => L
    [PLACEMENT] => TASK_USER_LIST_TOOLBAR
    [PLACEMENT_OPTIONS] => {"USER_ID":"1","URI":"\/company\/personal\/user\/1\/tasks\/"}
)


Array
(
    [DOMAIN] => xxx.bitrix24.com
    [PROTOCOL] => 1
    [LANG] => ru
    [APP_SID] => 9f3b397a4bc09ad1ee9b7a5db991a603
    [AUTH_ID] => cc53ba6600705a0700005a4b00000001f0f107e316cd1ed3be4be6856b7077e1
    [AUTH_EXPIRES] => 3600
    [REFRESH_ID] => bcd2e16600705a0700005a4b00000001f0f1075b826a128425efbda11902d7f5
    [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
    [APPLICATION_TOKEN] => 3f0a7c19e5b84d2196c8ad470e5f2b31
    [APPLICATION_SCOPE] => task,placement
    [member_id] => da45a03b265edd8787f8a258d793cc5d
    [status] => L
    [PLACEMENT] => TASK_GROUP_LIST_TOOLBAR
    [PLACEMENT_OPTIONS] => {"GROUP_ID":"129","URI":"\/workgroups\/group\/129\/tasks\/"}
)

Обязательные параметры отмечены *

Параметры в query-строке адреса обработчика

Параметр
тип

Описание

DOMAIN*
string

Адрес Битрикс24, на котором был вызван обработчик виджета

PROTOCOL*
string

Защищенный или незащищенный протокол HTTP:

  • 0 — HTTP
  • 1 — HTTPS

LANG*
string

Язык интерфейса пользователя Битрикс24, который вызвал виджет. Вы можете локализовать язык интерфейса в своем виджете, ориентируясь на это значение

APP_SID*
string

Идентификатор сессии приложения. Битрикс24 создает его заново при каждой отрисовке виджета и использует, чтобы связать js-библиотеку с окружением приложения

Параметры в теле POST-запроса

Параметр
тип

Описание

AUTH_ID
string

Авторизационный токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для вызовов REST API от лица этого пользователя

AUTH_EXPIRES
integer

Время в секундах, после которого авторизационный токен станет неактуальным

REFRESH_ID
string

Refresh-токен OAuth 2, выписанный для пользователя, вызвавшего виджет. Можно использовать для обновления авторизационного токена от лица этого пользователя

SERVER_ENDPOINT*
string

Адрес сервера авторизации Битрикс24, необходимый для обновления токенов OAuth 2

APPLICATION_TOKEN*
string

Токен приложения. То же значение приходит в параметре application_token при вызове обработчиков событий. По нему обработчик виджета может проверить, что запрос пришел от Битрикс24

APPLICATION_SCOPE*
string

Список скоупов, выданных приложению, через запятую. Показывает, какие методы REST API доступны с полученным авторизационным токеном

member_id*
string

Уникальный строковый идентификатор Битрикс24, на котором был вызван обработчик виджета

status
string

Тип приложения, зарегистрировавшего обработчик данного виджета. Принимает значения:

PLACEMENT*
string

Код точки встраивания. Вы можете использовать один и тот же URL обработчика для всех своих виджетов. Значение, которое Битрикс24 будет сообщать в параметре PLACEMENT, поможет определить, из какой именно точки встраивания был вызван ваш обработчик в каждом конкретном случае

PLACEMENT_OPTIONS
string

Дополнительные данные в виде JSON-строки, определяющие контекст выполнения виджета. Например, это может быть массив, содержащий числовой идентификатор элемента CRM, в карточке которого был вызван обработчик виджета, и так далее. Параметр PLACEMENT_OPTIONS вместе с параметром PLACEMENT позволяет точно определить, для какой именно точки встраивания и какого объекта был вызван обработчик виджета

Битрикс24 добавляет в PLACEMENT_OPTIONS ключ URI — путь с query-строкой той страницы, с которой открыт виджет. Он приходит для любой точки встраивания, вместе с ее собственными ключами. Ключа не будет, если браузер не передал заголовок Referer или виджет открыт со страницы другого домена.

Как разобрать контекст вызова

PLACEMENT_OPTIONS приходит JSON-строкой, а не массивом: перед использованием разберите ее на стороне обработчика. Состав ключей у каждой точки свой и описан в разделе PLACEMENT_OPTIONS этой страницы.

$placement = $_POST['PLACEMENT'] ?? '';
$options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")

В B24JsSDK разбирать строку не нужно: свойство $b24.placement.options возвращает готовый объект, а $b24.placement.placement — код точки встраивания.

Что должен вернуть обработчик

Обработчик отвечает обычной HTML-страницей — Битрикс24 показывает ее во фрейме на месте виджета. Страница должна разрешать встраивание: если сервер приложения отдает заголовки X-Frame-Options или Content-Security-Policy, запрещающие фрейм, на месте виджета останется пустая область. Как это исправить, описано в статье Сайт не разрешает подключение.

PLACEMENT_OPTIONS

Значение PLACEMENT_OPTIONS передается как JSON-строка с контекстом вызова. Кроме универсального ключа URI в контекст попадает собственный ключ точки: у каждой точки он свой.

Обязательные параметры отмечены *

Параметр

Описание

USER_ID*
string

Идентификатор пользователя, над списком задач которого открыт виджет. Приходит только у точки TASK_USER_LIST_TOOLBAR.

Данные пользователя возвращает метод user.get

GROUP_ID*
string

Идентификатор рабочей группы или проекта, над списком задач которого открыт виджет. Приходит только у точки TASK_GROUP_LIST_TOOLBAR.

Данные группы возвращает метод sonet_group.get

Примеры кода

Как использовать примеры в документации

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "PLACEMENT": "TASK_USER_LIST_TOOLBAR",
    "HANDLER": "https://your-domain.com/widgets/task-list-toolbar-handler.php",
    "TITLE": "Мой пункт над списком задач",
    "LANG_ALL": {
      "ru": {
        "TITLE": "Мой пункт над списком задач"
      },
      "en": {
        "TITLE": "My task list item"
      }
    },
    "auth": "**put_access_token_here**"
  }' \
  https://**put_your_bitrix24_address**/rest/placement.bind
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<boolean>({
    method: 'placement.bind',
    params: {
      PLACEMENT: 'TASK_USER_LIST_TOOLBAR',
      HANDLER: 'https://your-domain.com/widgets/task-list-toolbar-handler.php',
      TITLE: 'My task list item',
      LANG_ALL: {
        ru: {
          TITLE: 'Мой пункт над списком задач',
        },
        en: {
          TITLE: 'My task list item',
        },
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Placement bound successfully:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function bindTaskUserListToolbar() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'placement.bind',
        params: {
          PLACEMENT: 'TASK_USER_LIST_TOOLBAR',
          HANDLER: 'https://your-domain.com/widgets/task-list-toolbar-handler.php',
          TITLE: 'My task list item',
          LANG_ALL: {
            ru: {
              TITLE: 'Мой пункт над списком задач',
            },
            en: {
              TITLE: 'My task list item',
            },
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Placement bound successfully:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', bindTaskUserListToolbar)
</script>
try {
    $response = $b24Service
        ->core
        ->call(
            'placement.bind',
            [
                'PLACEMENT' => 'TASK_USER_LIST_TOOLBAR',
                'HANDLER' => 'https://your-domain.com/widgets/task-list-toolbar-handler.php',
                'TITLE' => 'Мой пункт над списком задач',
                'LANG_ALL' => [
                    'ru' => [
                        'TITLE' => 'Мой пункт над списком задач',
                    ],
                    'en' => [
                        'TITLE' => 'My task list item',
                    ],
                ],
            ]
        );

    $result = $response->getResponseData()->getResult();
    if ($result->error()) {
        error_log($result->error());
    } else {
        echo 'Success: ' . print_r($result->data(), true);
    }
} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error binding placement: ' . $e->getMessage();
}
BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'TASK_USER_LIST_TOOLBAR',
        HANDLER: 'https://your-domain.com/widgets/task-list-toolbar-handler.php',
        TITLE: 'Мой пункт над списком задач',
        LANG_ALL: {
            ru: { TITLE: 'Мой пункт над списком задач' },
            en: { TITLE: 'My task list item' }
        }
    },
    function(result) {
        if (result.error()) {
            console.error(result.error());
        } else {
            console.log(result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'TASK_USER_LIST_TOOLBAR',
        'HANDLER' => 'https://your-domain.com/widgets/task-list-toolbar-handler.php',
        'TITLE' => 'Мой пункт над списком задач',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Мой пункт над списком задач',
            ],
            'en' => [
                'TITLE' => 'My task list item',
            ],
        ],
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "placement.bind", b24.Params{
	"PLACEMENT": "TASK_USER_LIST_TOOLBAR",
	"HANDLER":   "https://your-domain.com/widgets/task-list-toolbar-handler.php",
	"TITLE":     "Мой пункт над списком задач",
	"LANG_ALL": b24.Params{
		"ru": b24.Params{
			"TITLE": "Мой пункт над списком задач",
		},
		"en": b24.Params{
			"TITLE": "My task list item",
		},
	},
})
if err != nil {
	return fmt.Errorf("placement.bind: %w", err)
}

// Ответ приходит как json.RawMessage — разберите его по форме ответа
// метода placement.bind, см. раздел «Обработка ответа» на его странице.
fmt.Printf("%s\n", res.Result)

Продолжите изучение