Виджет для сайдбара IM_SIDEBAR

Scope: im

Вы можете добавлять свой пункт в сайдбар чата

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

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

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

Код встройки

Место

IM_SIDEBAR

Пункт в сайдбаре чата

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

Откройте чат и нажмите кнопку сайдбара в правой части верхней панели чата. В открывшемся сайдбаре внизу есть блок Приложения, в котором отображается пункт приложения с PLACEMENT=IM_SIDEBAR.

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

Данные передаются в виде POST-запроса

Array
        (
            [DOMAIN] => xxx.bitrix24.com
            [PROTOCOL] => 1
            [LANG] => ru
            [APP_SID] => 99c80eff6378726287350416ee5fef0
            [AUTH_ID] => 6061e72600631fcd00005a4b00000001f0f1076700000000f69dd5fc643d9ce2fdbc1
            [AUTH_EXPIRES] => 3600
            [REFRESH_ID] => 50e00aa340631fcd00005a4b00000001f0f1071111116580a5b83c2de639ef28c12
            [member_id] => da45a03b265ed12127f8a258d793cc5d
            [status] => F
            [PLACEMENT] => IM_SIDEBAR
            [PLACEMENT_OPTIONS] => {"dialogId":"chat1489"}
        )

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

Параметр
тип

Описание

DOMAIN*
string

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

PROTOCOL*
string

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

  • 0 - HTTP
  • 1 - HTTPS

LANG*
string

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

APP_SID
string

Строковый идентификатор приложения, зарегистрировавшего обработчик виджета

AUTH_ID
string

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

AUTH_EXPIRES
integer

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

REFRESH_ID
string

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

member_id*
string

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

status
string

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

PLACEMENT*
string

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

PLACEMENT_OPTIONS
string

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

PLACEMENT_OPTIONS

Значение PLACEMENT_OPTIONS передается как JSON-строка с контекстом вызова.

Для IM_SIDEBAR в контекст передается ключ:

  • dialogId — идентификатор текущего чата

OPTIONS при регистрации через placement.bind

Для IM_SIDEBAR метод placement.bind поддерживает параметры OPTIONS.

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

Параметр
тип

Описание

iconName*
string

Подпись пункта в интерфейсе. До 50 символов, допускаются латинские буквы, пробел и -

extranet
string

Доступ в экстранете, по умолчанию N.

Возможные значения:

  • N — приложение недоступно для экстранет-пользователей
  • Y — приложение доступно для экстранет-пользователей

context
string

Контекст показа, по умолчанию ALL. Можно передать несколько значений через ;.

Возможные значения:

  • ALL — все чаты
  • USER — личные чаты пользователей, кроме чатов с ботами
  • CHAT — групповые чаты, кроме LINES и CRM
  • LINES — чаты открытых линий
  • CRM — чаты, созданные в рамках CRM

Если передан ALL вместе с другими значениями, используется только ALL. Неверное значение вызывает ошибку регистрации

role
string

Роль пользователя, по умолчанию USER.

Возможные значения:

  • USER — приложение доступно всем пользователям
  • ADMIN — приложение доступно только администраторам портала

color
string

Цвет иконки из палитры IM.

Возможные значения:

  • RED — красный
  • GREEN — зеленый
  • MINT — мятный
  • LIGHT_BLUE — светло-голубой
  • DARK_BLUE — темно-синий
  • PURPLE — фиолетовый
  • AQUA — аквамариновый
  • PINK — розовый
  • LIME — лаймовый
  • BROWN — коричневый
  • AZURE — лазурный
  • KHAKI — хаки
  • SAND — песочный
  • ORANGE — оранжевый
  • MARENGO — маренго
  • GRAY — серый
  • GRAPHITE — графитовый

Примеры кода

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

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "PLACEMENT": "IM_SIDEBAR",
            "HANDLER": "https://your-domain.com/widgets/im-sidebar-handler.php",
            "TITLE": "Мой пункт сайдбара",
            "LANG_ALL": {
              "ru": {
                "TITLE": "Мой пункт сайдбара"
              },
              "en": {
                "TITLE": "My sidebar item"
              }
            },
            "OPTIONS": {
              "iconName": "chat-tools",
              "context": "ALL",
              "role": "USER",
              "extranet": "N",
              "color": "LIGHT_BLUE"
            },
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/placement.bind
        
try
        {
            const response = await $b24.callMethod(
                'placement.bind',
                {
                    PLACEMENT: 'IM_SIDEBAR',
                    HANDLER: 'https://your-domain.com/widgets/im-sidebar-handler.php',
                    TITLE: 'Мой пункт сайдбара',
                    LANG_ALL: {
                        ru: {
                            TITLE: 'Мой пункт сайдбара',
                        },
                        en: {
                            TITLE: 'My sidebar item',
                        }
                    },
                    OPTIONS: {
                        iconName: 'chat-tools',
                        context: 'ALL',
                        role: 'USER',
                        extranet: 'N',
                        color: 'LIGHT_BLUE',
                    }
                }
            );
        
            const result = response.getData().result;
            if (result.error())
                console.error(result.error());
            else
                console.info(result.data());
        }
        catch (error)
        {
            console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'placement.bind',
                    [
                        'PLACEMENT' => 'IM_SIDEBAR',
                        'HANDLER' => 'https://your-domain.com/widgets/im-sidebar-handler.php',
                        'TITLE' => 'Мой пункт сайдбара',
                        'LANG_ALL' => [
                            'ru' => [
                                'TITLE' => 'Мой пункт сайдбара',
                            ],
                            'en' => [
                                'TITLE' => 'My sidebar item',
                            ],
                        ],
                        'OPTIONS' => [
                            'iconName' => 'chat-tools',
                            'context' => 'ALL',
                            'role' => 'USER',
                            'extranet' => 'N',
                            'color' => 'LIGHT_BLUE',
                        ],
                    ]
                );
        
            $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: 'IM_SIDEBAR',
                HANDLER: 'https://your-domain.com/widgets/im-sidebar-handler.php',
                TITLE: 'Мой пункт сайдбара',
                LANG_ALL: {
                    ru: { TITLE: 'Мой пункт сайдбара' },
                    en: { TITLE: 'My sidebar item' }
                },
                OPTIONS: {
                    iconName: 'chat-tools',
                    context: 'ALL',
                    role: 'USER',
                    extranet: 'N',
                    color: 'LIGHT_BLUE'
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.log(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'placement.bind',
            [
                'PLACEMENT' => 'IM_SIDEBAR',
                'HANDLER' => 'https://your-domain.com/widgets/im-sidebar-handler.php',
                'TITLE' => 'Мой пункт сайдбара',
                'LANG_ALL' => [
                    'ru' => [
                        'TITLE' => 'Мой пункт сайдбара',
                    ],
                    'en' => [
                        'TITLE' => 'My sidebar item',
                    ],
                ],
                'OPTIONS' => [
                    'iconName' => 'chat-tools',
                    'context' => 'ALL',
                    'role' => 'USER',
                    'extranet' => 'N',
                    'color' => 'LIGHT_BLUE',
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

Предыдущая
Виджет над сообщением
Следующая
Пункт контекстного меню сообщения