Работа с командами

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

Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.

Обратите внимание! Для обработки команды, нужно чтобы в приложении была обработка события добавления команды ONIMCOMMANDADD.

Регистрация команды для обработки чат-ботом

Rest-метод: imbot.command.register

Вызов метода:

$result = restCommand('imbot.command.register', Array(

   'BOT_ID' => 62, // Идентификатор чат-бота владельца команды
   'COMMAND' => 'echo', // Текст команды, которую пользователь будет вводить в чатах
   'COMMON' => 'Y', // Если указан Y, то команда доступна во всех чатах, если N - то доступна только в тех, где присутствует чат-бот
    'HIDDEN' => 'N', // Скрытая команда или нет - по умолчанию N
   'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям Экстранет, по умолчанию N
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
   'LANG' => Array( // Массив переводов, обязательно указывать, как минимум, для RU и EN
      Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Get echo message', 'PARAMS' => 'some text'), // Язык, описание команды, какие данные после команды нужно вводить.
   ),
   'EVENT_COMMAND_ADD' => 'http://www.hazz/chatApi/bot.php', // Ссылка на обработчик для команд

), $_REQUEST["auth"]);

Важно! Обязательно указывать массив переводов LANG, как минимум, для RU и EN. Если нет фразы для BY, UA, KZ, то показывается по умолчанию фразы RU, если в RU нет фразы - команда скрывается. Для остальных языков тоже самое - если нет фраз, то по умолчанию показываются фразы EN, если в EN нет фразы, то команда скрывается в публичной части.

Результат выполнения: идентификатор команды COMMAND_ID или ошибка.

Ссылки по теме:

Событие на получение чат-ботом команды ONIMCOMMANDADD

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

Код ошибки	Описание ошибки
EVENT_COMMAND_ADD	Ссылка обработчик события невалидная или не указана.
COMMAND_ERROR	Не указан текст команды, на которую должен откликаться чат-бот.
BOT_ID_ERROR	Чат-бот не найден.
APP_ID_ERROR	Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
LANG_ERROR	Не переданы языковые фразы для видимой команды.
WRONG_REQUEST	Что-то пошло не так.

Внимание! Если планируется устанавливать более одной команды для чат-бота: Bitrix24 Rest накладывает ограничение на работу с обработчиками событий - обработчик может быть только один на одно приложение. Поэтому при регистрации второй команды ссылки на обработчики EVENT_COMMAND_ADD должны быть такими же, как и у первой команды.

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

Удаление обработки команды

Rest-метод: imbot.command.unregister

Вызов метода:

$result = restCommand('imbot.command.unregister', Array(

    'COMMAND_ID' => 13, // Идентификатор команды для удаления
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
), $_REQUEST["auth"]);

Результат выполнения: true или ошибка.

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

Код ошибки	Описание ошибки
COMMAND_ID_ERROR	Команда не найдена.
APP_ID_ERROR	Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
WRONG_REQUEST	Что-то пошло не так.

Обновление данных в команде

Rest-метод: imbot.command.update

Вызов метода:

$result = restCommand('imbot.command.update', Array(

   'COMMAND_ID' => 13, // Идентификатор чата
   'FIELDS' => Array(
      'EVENT_COMMAND_ADD' => 'http://www.hazz/chatApi/bot.php', // Ссылка на обработчик команд
      'HIDDEN' => 'N', // Скрытая команда или нет
      'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям Экстранет
      'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
      'LANG' => Array( // Новые фразы перевода, все предыдущие будут удалены
         Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Get echo message', 'PARAMS' => 'some text'),
      ),
   )

), $_REQUEST["auth"]);

Обязательные поля: идентификатор команды и одно из нужных полей для редактирования.

Результат выполнения: true или ошибка.

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

Код ошибки	Описание ошибки
COMMAND_ID_ERROR	Команда не найдена.
APP_ID_ERROR	Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
EVENT_COMMAND_ADD	Ссылка обработчик события невалидная или не указана.
WRONG_REQUEST	Что-то пошло не так.

Публикация ответа на команду

Rest-метод: imbot.command.answer

Вызов метода:

$result = restCommand('imbot.command.answer', Array(

    'COMMAND_ID' => 13, // Идентификатор команды, которая подготовила ответ (обязательно указывать или COMMAND)
    'COMMAND' => 'echo', // Название команды, которая подготовила ответ (обязательно указывать или COMMAND_ID)
    'MESSAGE_ID' => 1122, // Идентификатор сообщения, на которое необходимо дать ответ
    'MESSAGE' => 'answer text' // Текст ответа
    'ATTACH' => '' // Вложение, необязательное поле
    'KEYBOARD' => '' // Клавиатура, необязательное поле
    'MENU' => '' // Контекстное меню, необязательное поле 
    'SYSTEM' => 'N' // Отображать сообщения в виде системного сообщения, необязательное поле, по умолчанию 'N'
    'URL_PREVIEW' => 'Y' // Преобразовывать ссылки в rich-ссылки, необязательное поле, по умолчанию 'Y'
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков

), $_REQUEST["auth"]);

Результат выполнения: идентификатор сообщения команды MESSAGE_ID или ошибка.

Ссылки по теме:

Как работать с набираемыми клавиатурами
Как работать с вложениями
Форматирование сообщения

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

Код ошибки	Описание ошибки
COMMAND_ID_ERROR	Команда не найдена.
APP_ID_ERROR	Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
MESSAGE_EMPTY	Не передан текст сообщения.
ATTACH_ERROR	Весь переданный объект вложения не прошел валидацию.
ATTACH_OVERSIZE	Превышен максимально допустимый размер вложения (30 Кб).
KEYBOARD_ERROR	Весь переданный объект клавиатуры не прошел валидацию.
KEYBOARD_OVERSIZE	Превышен максимально допустимый размер клавиатуры (30 Кб).
MENU_ERROR	Весь переданный объект меню не прошел валидацию.
MENU_OVERSIZE	Превышен максимально допустимый размер меню (30 Кб).
WRONG_REQUEST	Что-то пошло не так.

Курсы разработаны в компании «1С-Битрикс»