Битрикс24: методы для работы с чатами через API

Подборка методов для работы с модулем «Веб-мессенджер» (im) коробочной версии «Битрикс24».  Для работы с методами обязательно подключение модуля: CModule::IncludeModule('im');

Создание чата

$pic = $_SERVER['DOCUMENT_ROOT'] . '/test.jpg';
$avatarId = \CFile::SaveFile(\CFile::MakeFileArray($pic), 'im');
$chat = new \CIMChat;
$chat->Add(array(
'TITLE' => 'Тестовый чат',
'DESCRIPTION' => 'Описание тестового чата',
'COLOR' => 'RED',//цвет
'TYPE' => IM_MESSAGE_OPEN,//тип чата
'AUTHOR_ID' => '1',//владелец чата
'AVATAR_ID' => $avatarId //иконка чата
));
//TYPE = IM_MESSAGE_CHAT – закрытый чат
//список доступных цветов: \Bitrix\Im\Color::getSafeColors()

Сменить владельца (модератора) чата

$change = CIMChat::SetOwner($chatID, $userID, $checkPermission);

Подробный мануал представлен в этой статье.

Переименование чата

\Bitrix\Im\Model\ChatTable::update($chatID, array('TITLE' => $new_name));

Получить список участников чата

Обратите внимание на возвращаемый методом массив данных, так как он позволяет решить сразу несколько задач:

• список участников чата (ключ userInChat)
• список участников чата отключивших уведомления (ключ mute_list)
• иконка чата (ключ avatar)
• идентификатор владельца/модератора чата (ключ owner)
• название чата (ключ name)
• внешний/внутренний чат (ключ extranet)

Пример вызова метода:

$ChatData = CIMChat::GetChatData(array('ID'=>$chatID));

Добавление пользователя в чат

Метод CIMChat::AddUser достаточно специфичный, подробности — в документации.

Для добавления пользователя в чат без системного уведомления о добавлении нового пользователя:

$chat = new \CIMChat(0);
$chat->AddUser($chatID, $userID, null, true, true);

В данном примере пользователь добавляется без доступа к истории сообщений чата. За это отвечает третий параметр, который задан как null. Для добавления пользователя в чат с доступом к старой переписке — этот параметр нужно убрать.

Для добавления пользователя с системным комментарием вида «Иванов Иван присоединился к чату»:

$chat = new \CIMChat(0);
$chat->AddUser($chatID, $userID, null, false, false);

Удаление пользователя из чата

Используем метод CIMChat::DeleteUser. Ссылка на документацию.

$chat = new \CIMChat();
$chat->DeleteUser($chatId, $userID, false, true, true);

Открыть чат по клику на ссылку

Данное решение будет полезно для того, чтобы добавить ссылку на определенный чат в документацию или Базу Знаний вашего портала. Все просто:

<a href="/online/?IM_DIALOG=chat[CHAT_ID]">Открыть чат</a>

где [CHAT_ID] — уникальный идентификатор чата.

Получить сообщения из чата

/*сообщения, старше 10-ти дней*/
$days = 10;
$dateCreate = new DateTime();
$dateCreate->sub(new DateInterval("P".$days."D"));

$filter = [
/*ID чата из которого получать сообщения*/
"=CHAT_ID" => $chatID;
/*выборка сообщений старше указанного кол-ва дней*/
"<=DATE_CREATE" => \Bitrix\Main\Type\DateTime::createFromUserTime(date("d.m.Y H:i:s", $dateCreate->getTimestamp()));
];

/*сколько сообщений получать*/
$limit = 50;
$params = Array(
    'filter' => $filter,
    'limit' => $limit,
    'order' => Array('ID' => 'ASC'),
);
$message_list = \Bitrix\Im\Model\MessageTable::getList($params);
while($message = $message_list->Fetch()){
//вывод данных
}

Массив $message будет содержать выборку списка сообщений чата.

Механизмы работы с сообщениями в чате

Рассмотрим несколько методов для работы с сообщениями по их уникальному идентификатору. ID сообщения можно посмотреть через исходный код страницы:

Получение сообщения по ID

$message = CIMMessenger::GetById($id);

Результат выполнения:

Array
(
    [ID] => 26066083
    [CHAT_ID] => 12345
    [AUTHOR_ID] => 1
    [MESSAGE] => Текст тестового сообщения.
    [MESSAGE_OUT] =>
    [DATE_CREATE] => 1620737943
    [EMAIL_TEMPLATE] =>
    [NOTIFY_TYPE] => 0
    [NOTIFY_MODULE] => im
    [NOTIFY_EVENT] => private
    [NOTIFY_TAG] =>
    [NOTIFY_SUB_TAG] =>
    [NOTIFY_TITLE] =>
    [NOTIFY_BUTTONS] =>
    [NOTIFY_READ] => N
    [IMPORT_ID] =>
    [MESSAGE_TYPE] => P
    [CHAT_AUTHOR_ID] => 1
    [CHAT_ENTITY_TYPE] =>
    [CHAT_ENTITY_ID] =>
    [CHAT_PARENT_ID] => 0
    [CHAT_PARENT_MID] => 0
    [CHAT_ENTITY_DATA_1] =>
    [CHAT_ENTITY_DATA_2] =>
    [CHAT_ENTITY_DATA_3] =>
    [PARAMS] => Array
        (
        )
)

Редактирование сообщения по ID

Стоит обратить внимание на параметры функции:

• $id — идентификатор редактируемого сообщения
• $text — новый текст сообщения
• $urlPreview — показывать превью ссылок
• $editFlag — показывать что сообщение было отредактировано
• $userId — идентификатор пользователя (автора)

Если в качестве $text передать пустое значение, то это будет равносильно удалению сообщения. Однако, это не совсем полноценное удаление, так как в чате останутся следы в виде фразы «Это сообщение было удалено».

Для редактирования сообщения других пользователей обязательно передавать ID автора сообщения в параметре$userId .

Пример вызова метода:

$edit_message = CIMMessenger::Update($id, "Текст сообщения", false, false, $userId);

Удаление сообщения по ID

Разберем параметры:

• $id — идентификатор удаляемого сообщения
• $userId — идентификатор пользователя (автора)
• $completeDelete — полное удаление / замена на сообщение-заглушку

Здесь все по аналогии с редактированием сообщения, если сообщение нужно удалить полностью, то третьим параметром передаем значение true. Если передать false, то будет выполнена замена текста сообщения на «Это сообщение было удалено». Исходный код метода.

Пример вызова:

$delete_message = CIMMessenger::Delete($id, $userID, true);

Есть и альтернативный вариант, в котором требуется указать только идентификатор сообщения:

$delete_message = \Bitrix\Im\Model\MessageTable::delete($id);

Написать сообщение в чат

Сообщение в чат от имени пользователя:

$ar = Array(
"TO_CHAT_ID" => 21441, // ID чата
"FROM_USER_ID" => 1, // ID пользователя состоящего в чате
"MESSAGE" => "Сообщение от пользователя", // Произвольный текст
);
CIMChat::AddMessage($ar);

Отправка системного уведомления в чат:

$ar = Array(
"TO_CHAT_ID" => 21441, // ID чата
"FROM_USER_ID" => 0,
"SYSTEM" => Y,
"MESSAGE"  => "Системное сообщение", // Произвольный текст
);
CIMChat::AddMessage($ar);