Работа с событиями

При генерации события (добавление нового сообщения, открытие диалога с чат-ботом, приглашение чат-бота в чат, удаление чат-бота со стороны клиента) формируется запрос на обработчик события, указанный вами при регистрации бота, подробнее об механизме событий можно почитать тут.

ONAPPINSTALL - событие на установку приложения.
ONAPPUPDATE - событие на обновление приложения.
ONIMBOTMESSAGEADD - событие на получение чат-ботом сообщения.
ONIMBOTMESSAGEUPDATE - событие на обновление сообщения чат-ботом.
ONIMBOTMESSAGEDELETE - событие на удаление сообщения чат-ботом.
ONIMCOMMANDADD - событие на получение чат-ботом команды.
ONIMBOTJOINCHAT - событие на получение информации чат-ботом о включении его в чат (или личную переписку).
ONIMBOTDELETE - событие на удаление чат-бота.
Пример кода обработчика для работы с событиями

Событие на установку приложения ONAPPINSTALL

[data] => Array(
  [LANGUAGE_ID] = ru // Базовый язык портала
  [VERSION] = 1 // Версия приложения
)
[auth] => Array(
    [access_token] => lh8ze36o8ulgrljbyscr36c7ay5sinva // Ключ для отправки запросов к REST-сервису
    [scope] => imbot // Разрешенные уровни доступа
    [domain] => b24.hazz // Домен портала Битрикс24, на который было установлено приложение
    [application_token] => c917d38f6bdb84e9d9e0bfe9d585be73 // Токен приложения, поможет вам «отбивать» лишние запросы на обработчик события, это поле есть во всех событиях

    [expires_in] => 3600 // Время истечения токена, после которого нужно будет запросить новый
    [member_id] => d41d8cd98f00b204e9800998ecf8427e // Уникальный идентификатор портала, потребуется для продления авторизации
    [refresh_token] => 5f1ih5tsnsb11sc5heg3kp4ywqnjhd09 // Ключ для продления авторизации
)

Обратите внимание! В базовом варианте работы с чат-ботом, поля expires_in, member_id, refresh_token - не требуются. Но, если для вашего приложения это необходимо, то прочитать, как с ними работать можно тут. Пример бота содержит возможность продления.

Событие на обновление приложения ONAPPUPDATE

[data] => Array(
  [LANGUAGE_ID] = ru // Базовый язык портала
  [VERSION] = 2 // Новая версия приложения
  [PREVIOUS_VERSION] => 1 // Старая версия приложения
)
[auth] => Array(
    [access_token] => lh8ze36o8ulgrljbyscr36c7ay5sinva // Ключ для отправки запросов к REST-сервису
    [scope] => imbot // Разрешенные уровни доступа
    [domain] => b24.hazz // Домен портала Битрикс24, на который было установлено приложение
    [application_token] => c917d38f6bdb84e9d9e0bfe9d585be73 // Токен приложения, поможет вам «отбивать» лишние запросы на обработчик события, это поле есть во всех событиях

    [expires_in] => 3600 // Время истечения токена, после которого нужно будет запросить новый
    [member_id] => d41d8cd98f00b204e9800998ecf8427e // Уникальный идентификатор портала, потребуется для продления авторизации
    [refresh_token] => 5f1ih5tsnsb11sc5heg3kp4ywqnjhd09 // Ключ для продления авторизации
)

Внимание! Все, что описывается ниже, - это содержимое поля [data] в событии. Данные авторизации в ключе [auth] содержат данные пользователя инициатора события, для получения данных авторизации бота, необходимо использовать [data][BOT][__BOT_CODE__].

Событие на получение чат-ботом сообщения
ONIMBOTMESSAGEADD

Событие на обновление чат-ботом сообщения
ONIMBOTMESSAGEUPDATE

Событие на удаление чат-ботом сообщения
ONIMBOTMESSAGEDELETE

[BOT] => Array // Массив кодов чат-ботов, которым предназначено сообщение
(
    [39] => Array
    (
   [AUTH] => Array // Параметры для авторизации под ботом, для выполнения действий
         (
            [domain] => b24.hazz
            [member_id] => d41d8cd98f00b204e9800998ecf8427e
            [application_token] => 8006ddd764e69deb28af0c768b10ed65
         )
        [BOT_ID] => 39    
        [BOT_CODE] => newbot
    )
)
[PARAMS] => Array // Массив данных сообщения
(
    [DIALOG_ID] => 1    // Идентификатор диалога
    [CHAT_TYPE] => P    // Тип сообщения и чата, может быть P (чат один-на-один), C (с ограниченным количеством участников), O (публичный чат), S (чат-бот с повышенными привилегиями - supervisor)
    [CHAT_ENTITY_TYPE] => 'LINES'    // для идентификации чата (данные поле вы можете задать в момент создания), для чатов открытых линий в данном поле будет указано LINES
    [CHAT_ENTITY_ID] => 13    // для идентификации чата (данные поле вы можете задать в момент создания)
    [MESSAGE_ID] => 392 // Идентификатор сообщения
    [MESSAGE] => test3 // Сообщение
    [FROM_USER_ID] => 1 // Идентификатор пользователя отправившего сообщение
    [TO_CHAT_ID] => 6   // Идентификатор чата (параметр доступен только в групповых чатах)
    [LANGUAGE] => ru    // Идентификатор языка портала по умолчанию
)
[USER] => Array // Массив данных автора сообщения, может быть пустым, если ID = 0
(
    [ID] => 1 // Идентификатор пользователя
    [NAME] => Евгений Шеленков // Имя и фамилия пользователя
    [FIRST_NAME] => Евгений // Имя пользователя
    [LAST_NAME] => Шеленков // Фамилия пользователя
    [WORK_POSITION] => // Занимаемая должность
    [GENDER] => M // Пол, может быть либо M (мужской), либо F (женский)
    [IS_BOT] => 'Y' // Это пользователь - бот (Y), иначе - N.
    [IS_CONNECTOR] => 'Y' // Это пользователь - коннектор (участник ОЛ-чата, клиент), иначе - N.
    [IS_NETWORK] => 'Y' // Это пользователь нетворка (может быть участником ОЛ-чата, клиент или просто внешний пользователь), иначе - N.
    [IS_EXTRANET] => 'Y' // Это пользователь экстранет (все пользователи, которые не-интранет), иначе - N.
)

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

[COMMAND] => Array // Массив команд, которые были вызваны пользователем
(
    [14] => Array 
    (
      [AUTH] => Array // Параметры для авторизации под чат-ботом для выполнения действий
      (
         [domain] => b24.hazz
         [member_id] => d41d8cd98f00b204e9800998ecf8427e
         [application_token] => 8006ddd764e69deb28af0c768b10ed65
      )
      [BOT_ID] => 62 // Идентификатор чат-бота
      [BOT_CODE] => echobot // Код чат-бота
      [COMMAND] => echo // Вызванная команда
      [COMMAND_ID] => 14 // Идентификатор команды
      [COMMAND_PARAMS] => test // Параметры, с которыми была вызвана команда
      [COMMAND_CONTEXT] => TEXTAREA // Контекст выполнения команды. TEXTAREA, если команда введена руками, или KEYBOARD, если нажал на кнопку в клавиатуре
      [MESSAGE_ID] => 1221 // Идентификатор сообщения, на которое необходимо ответить
    )
)
[PARAMS] => Array // Массив данных сообщения
(
    [DIALOG_ID] => 1    // Идентифкатор диалога
    [CHAT_TYPE] => P    // Тип сообщения и чата, может быть P (чат один-на-один), C (с ограниченным количеством участников), O (публичный чат)
    [MESSAGE_ID] => 1221 // Идентификатор сообщения
    [MESSAGE] => /echo test // Сообщение
    [MESSAGE_ORIGINAL] => /echo test // Оригинальное сообщение с BB-кодом бота (параметр доступен только в групповых чатах)
    [FROM_USER_ID] => 1 // Идентификатор пользователя отправившего сообщение
    [TO_USER_ID] => 2 // Идентификатор другого пользователя (параметр доступен только в чатах один-на-один)
    [TO_CHAT_ID] => 6   // Идентификатор чата (параметр доступен только в групповых чатах)
    [LANGUAGE] => ru    // Идентификатор языка портала по умолчанию
)
[USER] => Array // Массив данных автора сообщения, может быть пустым, если ID = 0
(
    [ID] => 1 // Идентификатор пользователя
    [NAME] => Евгений Шеленков // Имя и фамилия пользователя
    [FIRST_NAME] => Евгений // Имя пользователя
    [LAST_NAME] => Шеленков // Фамилия пользователя
    [WORK_POSITION] => // Занимаемая должность
    [GENDER] => M // Пол, может быть либо M (мужской), либо F (женский)
)

Событие на получение информации чат-ботом о включении его
в чат (или личную переписку)
ONIMBOTJOINCHAT

[BOT] => Array // Массив кодов чат-ботов, которым предназначено событие
(
    [39] => Array // Параметры для авторизации под чат-ботом для выполнения действий
    (
   [AUTH] => Array // Параметры для авторизации под чат-ботом для выполнения действий
        (
            [domain] => b24.hazz 
            [member_id] => d41d8cd98f00b204e9800998ecf8427e
            [application_token] => 8006ddd764e69deb28af0c768b10ed65
        )
        [BOT_ID] => 39    
        [BOT_CODE] => newbot
    )
)
[PARAMS] => Array
(
    [DIALOG_ID] => 1 // Идентифкатор диалога
    [BOT_ID] => 39    // Идентификатор бота
    [CHAT_TYPE] => P // Тип сообщения и чата, может быть P (чат один-на-один), C (с ограниченным количеством участников), O (публичный чат), S (чат-бот с повышенными привилегиями - supervisor)
    [CHAT_ENTITY_TYPE] => 'LINES'    // Подтип чата, может принимать значение LINES (Открытые линии) или пусто 
    [USER_ID] => 1   // Идентификатор пользователя (для чата один-на-один - открывавший чат-бота, для групповых чатов - пригласивший чат-бота)
    [LANGUAGE] => ru // Идентификатор языка портала по умолчанию
)
[USER] => Array // Массив данных пользователя, может быть пустым, если ID = 0
(
    [ID] => 1 // Идентификатор пользователя
    [NAME] => Евгений Шеленков // Имя и фамилия пользователя
    [FIRST_NAME] => Евгений // Имя пользователя
    [LAST_NAME] => Шеленков // Фамилия пользователя
    [WORK_POSITION] => // Занимаемая должность
    [GENDER] => M // Пол, может быть либо M (мужской), либо F (женский)
)

Событие на удаление чат-бота ONIMBOTDELETE

[BOT_ID] => 39 // Идентификатор чат-бота
[BOT_CODE] => giphy // Код чат-бота

Пример кода обработчика для работы с событиями

Пример полностью рабочий, сохраняет конфигурацию в файл, он поможет вам понять, как в целом функционируют чат-боты.

Файл с комментариями и аватаркой доступны в репозитории по адресу: https://bitbucket.org/Bitrix24com/rest-bot-echotest/

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