Виджет над полем ввода IM_TEXTAREA

Scope: im

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

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

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

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

Код встройки

Место

IM_TEXTAREA

Пункт в панели над полем ввода

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

Откройте чат и перейдите к нижней части окна, где находится поле ввода сообщения. В правом нижнем углу поля ввода откройте панель приложений. Пункт приложения с PLACEMENT=IM_TEXTAREA находится в этой панели.

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

Данные передаются в виде 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_TEXTAREA
            [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_TEXTAREA в контекст передается ключ:

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

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

Для IM_TEXTAREA метод 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 — графитовый

width
integer

Ширина блока в процентах, по умолчанию 100, значение должно быть больше или равно 0

height
integer

Высота блока в процентах, по умолчанию 100, значение должно быть больше или равно 0

Примеры кода

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

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "PLACEMENT": "IM_TEXTAREA",
            "HANDLER": "https://your-domain.com/widgets/im-textarea-handler.php",
            "TITLE": "Мой пункт панели",
            "LANG_ALL": {
              "ru": {
                "TITLE": "Мой пункт панели"
              },
              "en": {
                "TITLE": "My toolbar item"
              }
            },
            "OPTIONS": {
              "iconName": "chat-compose",
              "context": "ALL",
              "role": "USER",
              "extranet": "N",
              "color": "LIGHT_BLUE",
              "width": 100,
              "height": 100
            },
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/placement.bind
        
try
        {
            const response = await $b24.callMethod(
                'placement.bind',
                {
                    PLACEMENT: 'IM_TEXTAREA',
                    HANDLER: 'https://your-domain.com/widgets/im-textarea-handler.php',
                    TITLE: 'Мой пункт панели',
                    LANG_ALL: {
                        ru: {
                            TITLE: 'Мой пункт панели',
                        },
                        en: {
                            TITLE: 'My toolbar item',
                        }
                    },
                    OPTIONS: {
                        iconName: 'chat-compose',
                        context: 'ALL',
                        role: 'USER',
                        extranet: 'N',
                        color: 'LIGHT_BLUE',
                        width: 100,
                        height: 100,
                    }
                }
            );
        
            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_TEXTAREA',
                        'HANDLER' => 'https://your-domain.com/widgets/im-textarea-handler.php',
                        'TITLE' => 'Мой пункт панели',
                        'LANG_ALL' => [
                            'ru' => [
                                'TITLE' => 'Мой пункт панели',
                            ],
                            'en' => [
                                'TITLE' => 'My toolbar item',
                            ],
                        ],
                        'OPTIONS' => [
                            'iconName' => 'chat-compose',
                            'context' => 'ALL',
                            'role' => 'USER',
                            'extranet' => 'N',
                            'color' => 'LIGHT_BLUE',
                            'width' => 100,
                            'height' => 100,
                        ],
                    ]
                );
        
            $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_TEXTAREA',
                HANDLER: 'https://your-domain.com/widgets/im-textarea-handler.php',
                TITLE: 'Мой пункт панели',
                LANG_ALL: {
                    ru: { TITLE: 'Мой пункт панели' },
                    en: { TITLE: 'My toolbar item' }
                },
                OPTIONS: {
                    iconName: 'chat-compose',
                    context: 'ALL',
                    role: 'USER',
                    extranet: 'N',
                    color: 'LIGHT_BLUE',
                    width: 100,
                    height: 100
                }
            },
            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_TEXTAREA',
                'HANDLER' => 'https://your-domain.com/widgets/im-textarea-handler.php',
                'TITLE' => 'Мой пункт панели',
                'LANG_ALL' => [
                    'ru' => [
                        'TITLE' => 'Мой пункт панели',
                    ],
                    'en' => [
                        'TITLE' => 'My toolbar item',
                    ],
                ],
                'OPTIONS' => [
                    'iconName' => 'chat-compose',
                    'context' => 'ALL',
                    'role' => 'USER',
                    'extranet' => 'N',
                    'color' => 'LIGHT_BLUE',
                    'width' => 100,
                    'height' => 100,
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

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