Битрикс24: методы работы с чатами через API (модуль im)

Для чего нужны эти методы

Веб-мессенджер (модуль im) в коробочной версии Битрикс24 отвечает не только за общение сотрудников, но и часто используется разработчиками как канал уведомлений: системные сообщения о статусе задачи, автоматическое создание рабочих чатов под проект, интеграция с внешними сервисами поддержки. Ниже собраны проверенные на практике методы API для управления чатами и сообщениями — без REST, напрямую через классы CIMChat и CIMMessenger.

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

\Bitrix\Main\Loader::includeModule('im');

Более старый синтаксис CModule::IncludeModule('im') тоже работает, но именно на Loader::includeModule стоит переходить в новых проектах — так рекомендует сама документация Битрикс24.

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

Новый чат создаётся через объект CIMChat. Можно сразу задать название, описание, цвет, тип (открытый или закрытый) и иконку — аватар подгружается через CFile::SaveFile:

$pic = $_SERVER['DOCUMENT_ROOT'] . '/test.jpg';
$avatarId = \CFile::SaveFile(\CFile::MakeFileArray($pic), 'im');

$chat = new \CIMChat;
$res = $chat->Add(array(
    'TITLE' => 'Тестовый чат',
    'DESCRIPTION' => 'Описание тестового чата',
    'COLOR' => 'RED', // цвет
    'TYPE' => IM_MESSAGE_OPEN, // тип чата
    'AUTHOR_ID' => '1', // владелец чата
    'AVATAR_ID' => $avatarId // иконка чата
));

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

Пояснения к параметрам:

• TYPE => IM_MESSAGE_OPEN — открытый чат, доступный по ссылке.
• TYPE => IM_MESSAGE_CHAT — закрытый чат, только для приглашённых участников.
• Список допустимых значений цвета чата можно получить через \Bitrix\Im\Color::getSafeColors().

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

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

Метод передаёт права модератора чата другому пользователю. Параметр $checkPermission определяет, нужно ли проверять права текущего инициатора действия перед сменой владельца.

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

Название чата можно изменить напрямую через таблицу данных:

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

Получение списка участников и данных чата

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

• 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);

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

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

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

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

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

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

Получение сообщений из чата за период

Для выборки сообщений старше указанного количества дней используется MessageTable::getList с фильтром по дате и идентификатору чата:

$days = 10;
$dateCreate = new DateTime();
$dateCreate->sub(new DateInterval("P" . $days . "D"));

$filter = [
    "=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()) {
    // обработка данных сообщения
}

Работа с сообщениями по идентификатору

Дальше — три ключевые операции с конкретным сообщением: получение, редактирование и удаление. ID сообщения можно найти в исходном коде страницы чата.

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

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

Результат — массив с полным набором данных о сообщении: CHAT_ID, AUTHOR_ID, MESSAGE, DATE_CREATE, MESSAGE_TYPE и другие служебные поля.

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

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

Параметры метода:

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

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

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

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

Параметры:

• $id — идентификатор удаляемого сообщения;
• $userId — идентификатор автора;
• $completeDelete — true для полного удаления, false — для замены текста на заглушку «Это сообщение было удалено».

Альтернативный вариант полного удаления без указания автора:

$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,
    "FROM_USER_ID" => 0,
    "SYSTEM" => "Y",
    "MESSAGE" => "Системное сообщение",
);
CIMChat::AddMessage($ar);

Частые вопросы

Как вставить ссылку в текст сообщения чата?
HTML-теги в сообщениях мессенджера не обрабатываются — вместо <a> нужно использовать BB-код: [URL=https://www.site.ru/]Ссылка[/URL].

Почему скрипт с созданием чата работает только при запуске авторизованным пользователем?
Часто причина в том, что сторонний вызов блокируется страницей авторизации портала. Для скриптов, вызываемых внешними сервисами, рекомендуется размещать код в директории /pub/ и подключать prolog_before.php вместо стандартных header/footer, например:

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

Работают ли эти методы в облачной версии Битрикс24?
Нет, CIMChat и CIMMessenger — это внутренние классы коробочной версии. В облаке аналогичный функционал реализуется через REST API модуля im.

Как узнать ID чата, который метод Add() только что создал?
Метод возвращает идентификатор нового чата в результате вызова — достаточно сохранить возвращаемое значение в переменную: $res = $chat->Add(...); print_r($res);.

Можно ли привязать чат к сущности CRM (лиду, сделке)?
Готового штатного решения через рассмотренные методы нет — эта задача требует дополнительной проработки на стороне связки модулей im и crm.