Вызвать интерфейс удаления зарегистрированного обработчика события BX24.callUnbind

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

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
BX24.callUnbind(
    String event,
    String handler[,
        Integer|null auth_type[,
            Function callback
        ]
    ]
);

Функция BX24.callUnbind удаляет обработчик события, зарегистрированный для текущего приложения. Библиотека вызывает метод event.unbind от имени пользователя, который открыл приложение. Написание BX24.callUnBind — это тот же вызов, оставленный для совместимости.

Удаляются только обработчики того приложения, из которого выполнен вызов, и только обработчики онлайн-событий. Обработчик офлайн-события удаляют методом event.unbind с параметром event_type=offline: у функции нет параметра, который переключает тип события.

Вызвать функцию можно только из приложения, встроенного во фрейм Битрикс24.

Если вызвать функцию до BX24.init, библиотека дождется инициализации и повторит вызов, но синхронно вернет false. При отправленном запросе функция возвращает undefined, поэтому строгая проверка === false отличает отказ от отправки только внутри обработчика BX24.init.

Примечание

Функция работает только у пользователя с правами администратора Битрикс24. У остальных пользователей она синхронно возвращает false, не отправляет запрос и не вызывает callback. Ограничение задает библиотека: метод event.unbind доступен любому пользователю, но BX24.js проверяет права до отправки запроса.

Параметры

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

Название
тип

Описание

event*
string

Имя события, например ONAPPUNINSTALL. Регистр значения не важен

handler*
string

Адрес обработчика события. Значение сравнивается точно, вместе со схемой и завершающим слешем

auth_type
integer

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

Значение выбирают по тому, как обработчик регистрировали через BX24.callBind:

  • 0 или пустое значение — обработчики, зарегистрированные без auth_type, то есть с авторизацией от имени пользователя, действия которого привели к срабатыванию события
  • 15 или другой идентификатор пользователя — обработчики, зарегистрированные с auth_type этого пользователя
  • null или пропущенный параметр — обработчики события со всеми значениями auth_type

Параметры позиционные: чтобы удалить обработчики со всеми значениями auth_type и получить результат, передайте null третьим параметром

callback
function

Функция-обработчик результата вызова метода (подробное описание)

Примеры кода

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

Удалить все обработчики события по адресу, независимо от auth_type:

BX24.init(() => {
    BX24.callUnbind('ONAPPUNINSTALL', 'https://www.my-domain.ru/handler/');
});

Удалить обработчики, зарегистрированные без auth_type, и разобрать результат:

BX24.init(() => {
    BX24.callUnbind(
        'ONAPPUNINSTALL',
        'https://www.my-domain.ru/handler/',
        0,
        (result) => {
            if (result.error())
            {
                console.error(result.error());
            }
            else
            {
                console.log('Удалено обработчиков: ' + result.data().count);
            }
        }
    );
});

Обработка ответа

Функция callback получает объект ajaxResult — такой же, как у BX24.callMethod. Данные ответа возвращает метод data(), ошибку — метод error().

{
    "count": 1
}

Возвращаемые данные

Название
тип

Описание

count
integer

Количество удаленных обработчиков события. Значение 0 означает, что ни один обработчик не подошел под условия вызова

Обработка ошибок

{
    "status": 400,
    "ex": {
        "error": "ERROR_ARGUMENT",
        "error_description": "Argument 'HANDLER' is null or empty",
        "argument": "HANDLER"
    }
}

Код ошибки доступен как result.error().ex.error, текст — как result.error().ex.error_description, имя параметра, из-за которого возникла ошибка, — как result.error().ex.argument. HTTP-статус возвращают result.error().status и метод getStatus(), а готовую строку с кодом, текстом и статусом — метод toString().

Название
тип

Описание

error
string

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

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Статус

Код

Описание

Значение

400

ERROR_ARGUMENT

Argument 'EVENT' is null or empty

Не передано имя события

400

ERROR_ARGUMENT

Argument 'HANDLER' is null or empty

Не передан адрес обработчика

Ошибки метода event.unbind про нехватку прав администратора через эту функцию не приходят — запрос до сервера не доходит.

Ответы со статусом 5xx в callback тоже не попадают. Библиотека выбрасывает исключение Query error! из асинхронного обработчика запроса, поэтому try/catch вокруг вызова его не перехватит.

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

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

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

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

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Предыдущая
Зарегистрировать обработчик события
Следующая
Обзор функций