0  /  169

Бот платформа Битрикс24

Содержание

Что нового?

Новинки API Бот платформы Битрикс24.


Январь 2022

Новые методы в Chat API (REST ревизии 30):

  • Получение информации об участниках чата (поддерживается пагинация) – im.dialog.users.list
  • Отправка статуса «вам пишут...» – im.dialog.writing
  • Установка метки «прочитано» для всех диалогов – im.dialog.read.all
  • Использование команды бота – im.message.command
  • Создание новых сущностей по сообщению в чате: новый чат, задача, пост в Новостях, событие в календаре – im.message.share
  • Установка метки «не прочитан» на чат или диалог – im.recent.unread
  • Получение списка последних диалогов пользователя (с поддержкой пагинации) – im.recent.list
  • «Прочтение» списка уведомлений, исключая уведомления типа CONFIRM – im.notify.read.list
  • Ответ на уведомление, поддерживающее быстрый ответ – im.notify.answer
  • Взаимодействие с кнопками нотификаций – im.notify.confirm


Август 2020

Июль 2020

Декабрь 2019

Июль 2019

Апрель 2019

Февраль 2019

Август 2018

Февраль 2018

Декабрь 2017


С чего начать

В главе дается представление о том, что такое чат-боты и зачем они нужны, как работают и что могут делать. Также мы расскажем, как создать своё приложение для чат-бота и, собственно, покажем пример готового чат-бота для платформы Битрикс24.
Внимание! Существует ограничение на создание чат-ботов в рамках rest-приложений: не более 5 на одно приложение.


Что такое чат-бот?

Что такое чат-боты и что они могут делать?

Чат-бот - это виртуальный собеседник, программа, которая создана для имитации поведения человека при общении с одним или несколькими собеседниками.

Что такое чат-боты, зачем они нужны и зачем вообще заниматься их разработкой?

В большей степени, этот тренд формируется сейчас за рубежом - существует огромное количество ботов для Slack или Telegram, решающих самые разные задачи – от поиска авиабилетов до управления небольшими командами разработчиков. И чтобы получить все это богатство, пользователям даже не нужно выходить из предпочитаемого мессенджера.

Что могут делать чат-боты?

  • Замена рутины - позволяет выполнять определенные функции, не привлекая людей, а работа будет выполнена моментально и безупречно;
  • Поиск и агрегация новостей, аналитики, данных (Data-Driven Collaboration), данные доступны в месте принятия решений - мессенджерах и всем участникам, которым они нужны;
  • E-commerce - для спонтанных покупок без долгого поиска, mobile ecommerce + visual search + chatbots, для общения с клиентами;
  • Первая линия работы с клиентами, помощники, консультанты, типовые вопросы, телефония;
  • Just for Fun - просто для развлечения.


Бот-платформа Битрикс24

А в Битрикс24 чаты (как индивидуальные, так и групповые) - это часть намного более сложной экосистемы, один из основных каналов коммуникации пользователей, полностью интегрированный с другими бизнес-инструментами. И в этом контексте использование чат-ботов открывает значительно более интересные перспективы для бизнес-пользователей, поскольку Битрикс24 (в браузере, десктоп- и мобильном приложениях) уже сейчас - основное рабочее место для большого количества компаний.

Очень просто написать чат-бота, который, например, будет сообщать в чат нужным пользователям срочную информацию о показателях внутренней учетной системы, интегрированной с Битрикс24. Можно написать чат-бота, который будет помогать курьерам удобно обрабатывать заказы на основании сделок CRM Битрикс24 на мобильном устройстве прямо в мессенджере - и не придется писать для них отдельное мобильное приложение.

Разработка чат-бота в Битрикс24 - это очень перспективный вариант быстрой и удобной автоматизации специфических бизнес-процессов. Удобной, поскольку, как мы уже выяснили, получение информации и управление через мессенджер - это то, что сейчас предпочитает массовый пользователь. А быстрой - потому что разработка чат-бота для Битрикс24 это довольно простой процесс.

Примечание: Для более четкого понимания, что могут делать чат-боты на платформе Битрикс24, можно посмотреть видео-примеры возможностей уже готовых чат-ботов тут.



Возможности чат-бота

Чат-бот:

  • это специальный пользователь в системе, с которым можно коммуницировать в чате, но под ним никто не может авторизоваться;
  • поддерживает обработку slash-команд;
  • позволяет использовать свои клавиатуры для ответов, превратив простой чат в терминал.

Slash-команды

Slash-команды позволяют быстро создавать запросы для вывода или получения какой-либо информации, форматировать сообщения.

Примечание: Подробнее о работе с командами можно прочитать здесь



Клавиатуры

Возможности [ds]клавиатур[/ds][di] Клавиатура - это набор кнопок, каждая кнопка может состоять из определённых ключей.

Подробнее...[/di] довольно широкие.

  1. EchoBot
    Постраничная навигация, кнопки при вызове команды «Помощь»

  2. Марта
    Просто напишите марте Поиграй со мной!. Клавиатура используется как игровое поле:

  3. Giphy
    Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему:

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



Чаты

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

Примечание: Подробнее о работе с чатами можно прочитать здесь



Уведомления

Уведомления от чат-бота могут быть полезны и информативны. Они могут состоять из нескольких блоков различной информации из внешних систем.

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



Жизненный цикл чат-бота

Чат-бот публикует свои сообщения в чат через Rest API, получает ответы и команды пользователя через События Rest API (POST запрос).

Схема жизни чат-бота выглядит так:



Создание своего приложения

Основное, что нам надо понимать про чат-боты – это то, что их логика обычно строится на реагировании на некие действия пользователя и системы.

И у нас есть 6 событий, которые полностью покрывают необходимый спектр реакций:

  • ONAPPINSTALL – событие на установку приложения с чат-ботом.
  • ONAPPUPDATE – событие на обновление приложения.
  • ONIMJOINCHAT – событие после приглашения чат-бота «к разговору», т.е. либо при вызове его пользователем в индивидуальном чате, либо при подключении его к групповому чату.
  • ONIMBOTMESSAGEADD – событие после отправки сообщения от пользователя к чат-боту (в групповом чате, при явном упоминании бота).
  • ONIMCOMMANDADD – событие после отправки команды от пользователя к чат-боту (в персональной переписке с ним, или в групповом чате (если команда глобальная, то он может не участвовать в чате)).
  • ONIMBOTDELETE – событие после удаления приложения. Событие вызывается параллельно с OnAppUninstall.

Иными словами, мы должны написать обработчики указанных событий, чтобы реализовать простую логику:

  1. Зарегистрировать чат-бота на портале пользователя при установке.
  2. Вывести приветствие-справку от имени чат-бота в момент приглашения его в чат.
  3. Научиться анализировать текст сообщения от пользователя и что-то отправлять в ответ, причем под анализом подразумевается простой «разбор командной строки», а не лексический разбор естественного языка.

И для этого у нас есть набор простых методов, добавленных в REST API. Нам для старта потребуются только два:

Очевидно, что в обработчике события ONAPPINSTALL мы вызовем метод imbot.register для того, чтобы добавить чат-бота на текущий портал, а затем в событии ONIMJOINCHAT воспользуемся методом imbot.message.add для вывода справки о функционале чат-бота, и в обработчике ONIMBOTMESSAGEADD будем отвечать пользователю при помощи того же imbot.message.add. Ничего сложного, согласитесь?

А также вам не придется реализовывать в приложении полноценный OAuth 2.0, поскольку параметры, необходимые для авторизации, приходят в обработчики в массиве $_REQUEST.

Примечание: Полный список методов и событий Bot API можно посмотреть здесь.



Пример создания чат-бота

Код чат-бота

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

Пример простого чат-бота:

<?php
/**
 * Полезный чат-бот c отчетами для bitrix24
 */

$appsConfig     = array();
$configFileName = '/config_' . trim(str_replace('.', '_', $_REQUEST['auth']['domain'])) . '.php';
if (file_exists(__DIR__ . $configFileName)) {
   include_once __DIR__ . $configFileName;
}
// receive event "new message for bot"
if ($_REQUEST['event'] == 'ONIMBOTMESSAGEADD') {
   // check the event - register this application or not
   if (!isset($appsConfig[$_REQUEST['auth']['application_token']])) {
      return false;
   }
   // response time
   $arReport = getAnswer($_REQUEST['data']['PARAMS']['MESSAGE'], $_REQUEST['data']['PARAMS']['FROM_USER_ID']);
   $arReport['attach'][] = array("MESSAGE" => 'Как разберетесь с этими задачами, просто спросите еще раз [send=что горит]Что горит?[/send] и я дам новую сводку!');
   
   // send answer message
   $result = restCommand('imbot.message.add', 
      array(
         "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
         "MESSAGE"   => $arReport['title'] . "\n" . $arReport['report'] . "\n",
         "ATTACH"    => array_merge(
            $arReport['attach']
         ),
      ), 
      $_REQUEST["auth"]);

} // receive event "open private dialog with bot" or "join bot to group chat"
else {
   if ($_REQUEST['event'] == 'ONIMBOTJOINCHAT') {
      // check the event - register this application or not
      if (!isset($appsConfig[$_REQUEST['auth']['application_token']])) {
         return false;
      }
      // send help message how to use chat-bot. For private chat and for group chat need send different instructions.
      $result = restCommand('imbot.message.add', array(
         'DIALOG_ID' => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
         'MESSAGE'   => 'Привет! Я Докладун, докладываю все как есть.',
         "ATTACH"    => array(
            array('MESSAGE' => '[send=что горит]Что горит?[/send]'),
         ),
      ), $_REQUEST["auth"]);

   } // receive event "delete chat-bot"
   else {
      if ($_REQUEST['event'] == 'ONIMBOTDELETE') {
         // check the event - register this application or not
         if (!isset($appsConfig[$_REQUEST['auth']['application_token']])) {
            return false;
         }
         // unset application variables
         unset($appsConfig[$_REQUEST['auth']['application_token']]);
         // save params
         saveParams($appsConfig);

      } // receive event "Application install"
      else {
         if ($_REQUEST['event'] == 'ONAPPINSTALL') {
            // handler for events
            $handlerBackUrl = ($_SERVER['SERVER_PORT'] == 443 ? 'https' : 'http') . '://' . $_SERVER['SERVER_NAME'] . (in_array($_SERVER['SERVER_PORT'],
               array(80, 443)) ? '' : ':' . $_SERVER['SERVER_PORT']) . $_SERVER['SCRIPT_NAME'];
            // If your application supports different localizations
            // use $_REQUEST['data']['LANGUAGE_ID'] to load correct localization
            // register new bot
            $result = restCommand('imbot.register', array(
               'CODE'                  => 'ReportBot',
               // строковой идентификатор бота, уникальный в рамках вашего приложения (обяз.)
               'TYPE'                  => 'B',
               // Тип бота, B - бот, ответы  поступают сразу, H - человек, ответы поступаю с задержкой от 2х до 10 секунд
               'EVENT_MESSAGE_ADD'     => $handlerBackUrl,
               // Ссылка на обработчик события отправки сообщения боту (обяз.)
               'EVENT_WELCOME_MESSAGE' => $handlerBackUrl,
               // Ссылка на обработчик события открытия диалога с ботом или приглашения его в групповой чат (обяз.)
               'EVENT_BOT_DELETE'      => $handlerBackUrl,
               // Ссылка на обработчик события удаление бота со стороны клиента (обяз.)
               'PROPERTIES'            => array( // Личные данные чат-бота (обяз.)
                  'NAME'              => 'Докладун',
                  // Имя бота (обязательное одно из полей NAME или LAST_NAME)
                  'LAST_NAME'         => '',
                  // Фамилия бота (обязательное одно из полей NAME или LAST_NAME)
                  'COLOR'             => 'AQUA',
                  // Цвет бота для мобильного приложения RED,  GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
                  'EMAIL'             => 'no@mail.com',
                  // Емейл для связи
                  'PERSONAL_BIRTHDAY' => '2016-03-23',
                  // День рождения в формате YYYY-mm-dd
                  'WORK_POSITION'     => 'Докладываю о делах',
                  // Занимаемая должность, используется как описание бота
                  'PERSONAL_WWW'      => '',
                  // Ссылка на сайт
                  'PERSONAL_GENDER'   => 'M',
                  // Пол бота, допустимые значения M -  мужской, F - женский, пусто если не требуется указывать
                  'PERSONAL_PHOTO'    => 'iVBORw0KGgoAAAANSUhEUgAAADoAAAA6CAYAAADhu0ooAAAACXBIWXMAAAsTAAALEwEAmpwYAAAKT2lDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVNnVFPpFj333vRCS4iAlEtvUhUIIFJCi4AUkSYqIQkQSoghodkVUcERRUUEG8igiAOOjoCMFVEsDIoK2AfkIaKOg6OIisr74Xuja9a89+bN/rXXPues852zzwfACAyWSDNRNYAMqUIeEeCDx8TG4eQuQIEKJHAAEAizZCFz/SMBAPh+PDwrIsAHvgABeNMLCADATZvAMByH/w/qQplcAYCEAcB0kThLCIAUAEB6jkKmAEBGAYCdmCZTAKAEAGDLY2LjAFAtAGAnf+bTAICd+Jl7AQBblCEVAaCRACATZYhEAGg7AKzPVopFAFgwABRmS8Q5ANgtADBJV2ZIALC3AMDOEAuyAAgMADBRiIUpAAR7AGDIIyN4AISZABRG8lc88SuuEOcqAAB4mbI8uSQ5RYFbCC1xB1dXLh4ozkkXKxQ2YQJhmkAuwnmZGTKBNA/g88wAAKCRFRHgg/P9eM4Ors7ONo62Dl8t6r8G/yJiYuP+5c+rcEAAAOF0ftH+LC+zGoA7BoBt/qIl7gRoXgugdfeLZrIPQLUAoOnaV/Nw+H48PEWhkLnZ2eXk5NhKxEJbYcpXff5nwl/AV/1s+X48/Pf14L7iJIEyXYFHBPjgwsz0TKUcz5IJhGLc5o9H/LcL//wd0yLESWK5WCoU41EScY5EmozzMqUiiUKSKcUl0v9k4t8s+wM+3zUAsGo+AXuRLahdYwP2SycQWHTA4vcAAPK7b8HUKAgDgGiD4c93/+8//UegJQCAZkmScQAAXkQkLlTKsz/HCAAARKCBKrBBG/TBGCzABhzBBdzBC/xgNoRCJMTCQhBCCmSAHHJgKayCQiiGzbAdKmAv1EAdNMBRaIaTcA4uwlW4Dj1wD/phCJ7BKLyBCQRByAgTYSHaiAFiilgjjggXmYX4IcFIBBKLJCDJiBRRIkuRNUgxUopUIFVIHfI9cgI5h1xGupE7yAAygvyGvEcxlIGyUT3UDLVDuag3GoRGogvQZHQxmo8WoJvQcrQaPYw2oefQq2gP2o8+Q8cwwOgYBzPEbDAuxsNCsTgsCZNjy7EirAyrxhqwVqwDu4n1Y8+xdwQSgUXACTYEd0IgYR5BSFhMWE7YSKggHCQ0EdoJNwkDhFHCJyKTqEu0JroR+cQYYjIxh1hILCPWEo8TLxB7iEPENyQSiUMyJ7mQAkmxpFTSEtJG0m5SI+ksqZs0SBojk8naZGuyBzmULCAryIXkneTD5DPkG+Qh8lsKnWJAcaT4U+IoUspqShnlEOU05QZlmDJBVaOaUt2ooVQRNY9aQq2htlKvUYeoEzR1mjnNgxZJS6WtopXTGmgXaPdpr+h0uhHdlR5Ol9BX0svpR+iX6AP0dwwNhhWDx4hnKBmbGAcYZxl3GK+YTKYZ04sZx1QwNzHrmOeZD5lvVVgqtip8FZHKCpVKlSaVGyovVKmqpqreqgtV81XLVI+pXlN9rkZVM1PjqQnUlqtVqp1Q61MbU2epO6iHqmeob1Q/pH5Z/YkGWcNMw09DpFGgsV/jvMYgC2MZs3gsIWsNq4Z1gTXEJrHN2Xx2KruY/R27iz2qqaE5QzNKM1ezUvOUZj8H45hx+Jx0TgnnKKeX836K3hTvKeIpG6Y0TLkxZVxrqpaXllirSKtRq0frvTau7aedpr1Fu1n7gQ5Bx0onXCdHZ4/OBZ3nU9lT3acKpxZNPTr1ri6qa6UbobtEd79up+6Ynr5egJ5Mb6feeb3n+hx9L/1U/W36p/VHDFgGswwkBtsMzhg8xTVxbzwdL8fb8VFDXcNAQ6VhlWGX4YSRudE8o9VGjUYPjGnGXOMk423GbcajJgYmISZLTepN7ppSTbmmKaY7TDtMx83MzaLN1pk1mz0x1zLnm+eb15vft2BaeFostqi2uGVJsuRaplnutrxuhVo5WaVYVVpds0atna0l1rutu6cRp7lOk06rntZnw7Dxtsm2qbcZsOXYBtuutm22fWFnYhdnt8Wuw+6TvZN9un2N/T0HDYfZDqsdWh1+c7RyFDpWOt6azpzuP33F9JbpL2dYzxDP2DPjthPLKcRpnVOb00dnF2e5c4PziIuJS4LLLpc+Lpsbxt3IveRKdPVxXeF60vWdm7Obwu2o26/uNu5p7ofcn8w0nymeWTNz0MPIQ+BR5dE/C5+VMGvfrH5PQ0+BZ7XnIy9jL5FXrdewt6V3qvdh7xc+9j5yn+M+4zw33jLeWV/MN8C3yLfLT8Nvnl+F30N/I/9k/3r/0QCngCUBZwOJgUGBWwL7+Hp8Ib+OPzrbZfay2e1BjKC5QRVBj4KtguXBrSFoyOyQrSH355jOkc5pDoVQfujW0Adh5mGLw34MJ4WHhVeGP45wiFga0TGXNXfR3ENz30T6RJZE3ptnMU85ry1KNSo+qi5qPNo3ujS6P8YuZlnM1VidWElsSxw5LiquNm5svt/87fOH4p3iC+N7F5gvyF1weaHOwvSFpxapLhIsOpZATIhOOJTwQRAqqBaMJfITdyWOCnnCHcJnIi/RNtGI2ENcKh5O8kgqTXqS7JG8NXkkxTOlLOW5hCepkLxMDUzdmzqeFpp2IG0yPTq9MYOSkZBxQqohTZO2Z+pn5mZ2y6xlhbL+xW6Lty8elQfJa7OQrAVZLQq2QqboVFoo1yoHsmdlV2a/zYnKOZarnivN7cyzytuQN5zvn//tEsIS4ZK2pYZLVy0dWOa9rGo5sjxxedsK4xUFK4ZWBqw8uIq2Km3VT6vtV5eufr0mek1rgV7ByoLBtQFr6wtVCuWFfevc1+1dT1gvWd+1YfqGnRs+FYmKrhTbF5cVf9go3HjlG4dvyr+Z3JS0qavEuWTPZtJm6ebeLZ5bDpaql+aXDm4N2dq0Dd9WtO319kXbL5fNKNu7g7ZDuaO/PLi8ZafJzs07P1SkVPRU+lQ27tLdtWHX+G7R7ht7vPY07NXbW7z3/T7JvttVAVVN1WbVZftJ+7P3P66Jqun4lvttXa1ObXHtxwPSA/0HIw6217nU1R3SPVRSj9Yr60cOxx++/p3vdy0NNg1VjZzG4iNwRHnk6fcJ3/ceDTradox7rOEH0x92HWcdL2pCmvKaRptTmvtbYlu6T8w+0dbq3nr8R9sfD5w0PFl5SvNUyWna6YLTk2fyz4ydlZ19fi753GDborZ752PO32oPb++6EHTh0kX/i+c7vDvOXPK4dPKy2+UTV7hXmq86X23qdOo8/pPTT8e7nLuarrlca7nuer21e2b36RueN87d9L158Rb/1tWeOT3dvfN6b/fF9/XfFt1+cif9zsu72Xcn7q28T7xf9EDtQdlD3YfVP1v+3Njv3H9qwHeg89HcR/cGhYPP/pH1jw9DBY+Zj8uGDYbrnjg+OTniP3L96fynQ89kzyaeF/6i/suuFxYvfvjV69fO0ZjRoZfyl5O/bXyl/erA6xmv28bCxh6+yXgzMV70VvvtwXfcdx3vo98PT+R8IH8o/2j5sfVT0Kf7kxmTk/8EA5jz/GMzLdsAAAAgY0hSTQAAeiUAAICDAAD5/wAAgOkAAHUwAADqYAAAOpgAABdvkl/FRgAAEdVJREFUeNq8m3uMHVd9xz/nNzP37tvetdfe9dtxnDghIbHJgxClBAnSJKVVGqw0gfJHoU0aiiqBVLWVqoqC1AdSVQlVbXkLSEmQg4oSi4hCWgihhEfiuiHNy3HsrF9rr9f73nvvzPxO/5gzM2fm7iKiBkba3bv3zpxzfuf8Ht/f9/e7JnrkgEUoLgsYQFFEQUWKjxUF3P8K6j4Q/zlVRMQbBwQlm0Td3dkARgUVb8xiDveOUk7gX+p+iXjr0GIUVfdaQBXEeKvWYlQF70Z/DnG3K5p9oIq450w2Q3GvKRbsfisYze4zKEa9MYuptfhfVUHculSzWTV7rd6mKG4N6paOZnNK9l6+3lC9xSHZYpB8Z9wy853JTzo/SSm3Qd0N/kkU96o4wQV/PvG2N9tCKQ/MO//8rKQYuvwEN362W+UB2VxrEMSCUFks3mSKiHrjOcUVyfesEDBffKGAUm5W8aQ4DZF80eJWLsWGFWorUo4n+RLVqWQ5T65hxQa7963bKSOlSkpxoxtQyY/cDamlgognR3ESIsWi84WWwktpBm4n87HQUrXVvS/iaYfnM2wulrvB1nyGpfacZ2+ZpgkhWup0vl/l0ZMdfS5ZvvhcUyTbPeMLL/miPHtQz8q911ROo9Qq3ySMp6o2V1mtPmdy31T7379HEIOK77N876bFenL1U8nt3jkhyed2n/tmoJ6MgIpmzwvO2+YHq8XGSu1EK2N4Xth6KlpssFMUzwKzuRRCVUuX58dzSs59505GRFEFYwxxmkCSQKIQBBCGhKFgCp9bDSfinYYbtFi50XKjxDmtFCDuQJKQBgFIQBBFiDH+rmR+QGquQTMtLaJH5hx8+9NKjKyebLnwxKaA4evX30S8/3189JLLQBMS6+5ys4ovsFKEC/WdhPo2n522BUjafHDHbmbueC8/fsethFFI6uxfvaAoUoY2deu1ArYSV+l2AHn8VF/gPH5pqS+3bxjnzs3bCSXg76/cR3+jCZoUOqb+5PmpOsclWtVJ8eZBQS2QKJ/bdz1rGg2uHRnlQ9t3Z85NSicntfidvzY1K5QK+FAXfrUMtqJepMvdvjuG2J8A+I3RjZCkxenlKlgGQM9fe146DzP58RgRsCl712+ojN/WBLAF+qr6APHCHwVAAW+6Uockv91zQp4DUN/mhB9cmKKdJMVg9+7YDaliSSkduBSqlKAkqSVOU+I086FWtXAguUJatZDEfGD7roqgD04cAwlKr1zGRoqQqeXb2dTqK6kPuaScUijDsJZoRFUxErC0tMD3p6eKhdwwvI6+vj5ULakqSZoS25i00yFZXsJ22libZquxMbbTIWm3SDvLpGmH1FpShdRaCELu2LC5GPvM8hJzi/OVOK1o7TRqYMVzv2EVjZSQzbfHXGCjLmhaCMUQS8CDJ4/xzg1jAPRFEfuGhnny7CnCIOCG4XW8feMmbhsdY1f/IENhSJijIGvpqHK+0+Hw3AUeOnmch08cp5OmYA3r+vrYMtBfrP+BiWMQRgRBUMEE6qJAhrAogIqI52sAEx38mvXjiuZ42LlmrdhvNbjHNmYobDB7+3uK97507BWem5nmDy/ew46+fl7v9eT5c3z4Z4e4Zs1avrDvrcX7+773LQ5dmCaKIi978QNmDlvLEGaLMAkmOnjAFu5X5OcuonACTrnT1IIm/Pfbb+Oq4RGstVhreSMuiyWQ7PSmWsuMPvZvEAqRhAVMzeOxr6nSNY5vzjnAzj/UVYT0oIeoIGIgSfnp7PQbKmQWHkwx5mOTZyDulEDBRQCpO02tYVwvzJTQ08tCjFRhHNRgIJkX1STlg9t28Ztjm99QIYsNd4JeMjAAYtBUUWurAMOzucrJeuHLVJRVpBrkfRPIY2qeQAskccyHd17Mp/Zdx/pGk1/mde3wOl699U6wljRNMKYkRWwlilZBg9SRkSpe8C6T6Aqg98Bckigf3LqDv3vT1fQ4O/plX9v6+nnuHbeBhUTTLA3QkqnwjbNCCLijFi3SDCkQjEiJYEpsnwmvxnLLuvV8/PKrfmVC5teewTU8dM0NEKekmhbJfOGc8tiqHirULHZIgT29ZEKds0GrOZBVZaMIH9l9OWPNntfpXLKMZ6Wf4h732n+vft21eTv3bNsBcYpa6xFhTg7Et8SCWZA6yVbNl0vyS4BElfdvu4hbRsdWF8gTIGcfxOFXYwwG6KRpRfDiHvc6/7uS0NZavrD3OoIwLE5V0Squr6QRjhyzDvEU5utjRqfK1gHzPc0+PrRz96oC+n9PLC3yxPmzfP/8Wf7rwjQT7RaxKolaUiwBhsAYIhE2NRpct3aYG0ZGedeGcXb29UNNWD98NSTgn6/cy73P/AgjAcb6iZCXCZGDHsGEBw9YsxIXWou8sSp/sn0Xf3vF3lVPcTHu8MmXn+fTE8eYnD6XDRQ1IIggClkxf7IWUoWkA50YDKxZu457Nm3mr/ZcyYaevkpszIU2xiAPfwUaTaIw6AI1dRkKQX1YUXJMpUMKrOWHN72Lq9esXVHIP3j6KT736otZmtbby8cvvYIdPX08Pn2WLx09AlFEIB7j5xYUawpxzK3jW7hn01YmO20+8dLzzM/NApb9uy7hi3uvZyBqdAl83+Ef89lXjxBGDXBmsRKSs4AJHzlg8QhfswIMtMCNA4P8x03v6hJyqtXiLU9+h4m5GYgisHD2lt9itLc8iU+88DP+8vnDhI1m12Lidpt7d+7m03uvK95bjmO2Pn6Q861lUGWop5cnbnwHV60ZqcT6lxfm2fP4o0jQRAJTcXzFiZYkmWbMOYLxaEilREqJplw7NLyibb7v0FNMzM1img0QQyMIKkIC3D46Bs52Cyo0Vxur3O6yH5wN9kYRO/oHQAKIIuZaLW5/6omuTb5kcAiJmqhRrwpQZSy0RAGOk3UgQYUKr5uFWcve9aNdQs6223z73CREIaEJQKGTpBxbmK/c9+UTx8HmiXtWC/E51389NZGvHoDFdpuX5ubAGAIMhCGn5mY4MjfbBQhuGFqb2bhQ4f198CBAWOFyKky9R3yoZZ9TG//qi0L6gpClVos4ykGysvNb3+D9O3axrXeAb06e4tDUJPT0uDFNxgflJGcQcOD4UXbNTHP35m1Mtlt8/vjRzGAkyJLwNAEMG3p6KydqreWdoxv5wdlJiKIqP1zDwWGVyKpkoOWdNmWspxsgRBLwnzfezB8dfobD8xeIk05GfaYJX3nxuUw9HU1Ju4UFUisgrtaWp0mp5ejUWf767JlMfcMg89SiRI0GuwdH+OSeKxlqNKqZiTG8aWiNh+LUI6y1Ul4JKQpJWq9/lVeq9AfhijZ63fB6fnLzLVxotTkft5lPYjrW0rIWY8EaaGIIjcECoUBkhFShYxUDpFhaVrPUjOz+ZmDolYCNzR6GPRSmNUJuU08fpGkB3HPCIKdFcuY/NPWktca/iFuIWSWNwlqMCMM9TYZ7fklZjAMLtmaf1lr6o9CBizzjkkqNtYCCWqsbqMfF+OC4penKiKgrvdNV2Yn6/7/wM8ZgvBjs22mc2m46tlaQsj6XXqm85DSlOF0PhOk4/rkUS+4cVhO6vkhZIV779/u0zUr35feeaS9lSbl6z2uVYTCFtopX45Qqs56B35BXFudXZQF8NmC1E1xNkJX+1oWsb5x4p/vszAXH9VLhe+vPS/2oqZWFVDPV+ebk6VUFTa0lWeWnk6YOzGc0iP+TpCkY0/VXbckLJ2maeWufmFMt7PbhUychkMopVx0Nrj5aLUx2gWJFCQLhJ1OTKwoaW+XBkxM8tzCHWktgDOPNXnYPDADwyuIiZ9stMDAcRlw+OMR4Ty+T7RavLC7Q0pTAGAbDkPWNzLtOddrMJXGG1QwExrCnf4gbR9bRDMLMTIBzrRaH5i+AhGVF24N/uSwZYPAbHGr5aPHSwA9nL/D0zAXesrYKBac6Hf7x2BGenc9Qy/pGkw9s28mbhzLw/6OZab504hhTnTaXDgzx+auu5bLBIVILf/bCs7y4MM/aqMHdm7Zy7/YMfX33+DkeOjXBTNzJ7MsY9g6t5aF9b2W8WaZuv3foR6BKIKGXFpV2Kl4FLytBi6DVlNwrBmW/YhNy4OTxrhNd32jwxzt3eyV4VkwKVvpcbcbYR8Yw1uxhtNFktNFkrNlDZExhEh1Vfn/rTtY3ygzm66cm+ObJ4xmwcPyRahUkFPUfgSC4+3c+ZkzZJ1TYgMmKs8Zk6hwEwrm4w6+NrGejF8ADY7hyaA3Pzc/ywuI8aqGVpkzHHZ6ZvcB3p87y2vKys1llPkk43W5xcPI0T89O09KsFhoaQ0OEI4sLfPvcJC8tLhA75HTHxk18/NIrCBwWfmVxgfsOPcWUZiS3YEAMxtm+kBWji0YnYwirRJFU0FEB9p3wLy/M89VTE/zN0NouPmj/+BYeO3eGtqYcnpvl6NIiFlhIEtouBs8lCd84c5LvTE2ykCQspFklbilN+N70OZ6dn8UCF+IOS+6zpgj7x7dUAMujk6d4ud0myG3TqyLnElhVr6FLsj4j311LHTPWYtlXT01w48h63r1hvPL+/vEt/Hhmmk8dO0JLU1qdboCh1jKXxMwlcZdqLyQJC14JMr/u23YR+8e3FP+fbi3z5YnXXMLvcUQqVUYBqbBGknvYrC6pXdXnSuxDmVxe4l+OH+WlFeLq/dt3cefY5qpnN4beIKA/CImMvC7kd+fYZu73aqSxKp+dOMrLy3NubX4LkFeMz1NOj4wPgvfe9THjSk4ZsWWwmul3Fx2JBSMcXVqkpcrbhtfRG5R8zXDU4OL+QabjDs8vzGOA0UaT64dHuHpoGDEwHWd10Fzl+4OQdY0GkQiptUV/yp1jm/nTXXvYMzDoEhzL106f4BMv/S/LasEYrM0Qmao6sGIxRjJOyWHwXIYguPuuj2FMVk/RjHTyvFIhqHqOyRjDMzMztDTl2rUjFWHHmj3sWzNMYAwvLMxzzdph/mL35bxnfAuNIODQ3EyhogNhyM3rRvnt8S3s7OtnKm7T0ZT7t++qCNlR5YGTr/HnL/4Ps50kYxSwWAvWGMQarFiX+dnM3KypEHGhg/WVbrCiabEG2Kn0ASr/dPwIy5rwkZ2XcEn/YPHszr5+PnnZm3nb8DpOtJbZ2tvHUBixo7ePPm9TRqIG+zdt4ddHxzjbbrOlp4eLevu5w1P/M+0Wn5s4yj8cfYnFOKk1YDneWSQj3L2ep7zIlGczYaUTS3xGskxdpTCAiovDonxx4lVOLC9x3/ZdvHvDpoqN5Qs+2W5xsrXMxPISQ0FUaMD23n42NXvpC0K29wZ89KJLC94I4N+nzvCZ40d57NzpQt3V9SUWJW2n7EZKTCsitWxTMNEjB2zJoHgFVtcH6J+quMal8rBLGLCx2cPvbt7OPZu2ccXgml+8VOH5gDwp+Nn8LA+eeo0HTh5nst2qBjI1LrmuteBJN/PnF05NdPCAxW+RkTrHWy2Xq/rUaDcffWn/IO/euIlbR8e4aWT09ZX1p8/x2LkzHJw8xYsreHVrs1Sw0g1alDer+Lzs1c16c03wSNbDIIAVjxPNi77uYetRiap50WZ14NcQ4a1r13HNmhGuHFrDxf0DbO3pY8QR0dNxh4nWEkcWF3h2bpafzk7z1Mx5Oqsk4b4iqmvVKzmDMryI3x7uusLUgIkePWDV1pJcrbXq5eV+8drQnQ0bq/yc4tcbfqmu0FdXS+Yra9XcaRXn6fXaetmMFpRJ1bhzs87i1q9O0KJNqILcpPqdANGydyEHFFlzoBYNgvmDeReX1NBRSWWUr62VFapH3RVSy//36E3RA6jqC1unXaSrSVl8B2S9doaSMpQV+R6plNKLloiaMKb4UbVZRuEVDl4nEZg9lzc8SrUj32rZR78StyQGMK753tQdgXTnkvX/6zHLVJTGnaJaj5Xz6SqXH3obYLs2Iq+7SqlJHjeUN2h2MwZeiw4gajy076dllTPJdN641Cf/6oelntSX7c+Vvviu1vF8tw0YQdUWsxgXK4vyiJpKNVsqX4eRwmYrRSa/6UjU7wvW4kM/XfM9XdEMrNSYCKr98/WviqzEGRep4UpdJLVuGPGRWfVrKWVVTsqG5+KLCNWvtPzfAOI42kZvxsE0AAAAAElFTkSuQmCC',
                  // Аватар бота - base64
               ),
            ), $_REQUEST["auth"]);
            // save params
            $appsConfig[$_REQUEST['auth']['application_token']] = array(
               'BOT_ID'      => $result['result'],
               'LANGUAGE_ID' => $_REQUEST['data']['LANGUAGE_ID'],
            );
            saveParams($appsConfig);
            // write debug log
            // writeToLog($result, 'ReportBot register');
         }
      }
   }
}
/**
 * Save application configuration.
 *
 * @param $params
 *
 * @return bool
 */
function saveParams($params) {
   $config = "<?php\n";
   $config .= "\$appsConfig = " . var_export($params, true) . ";\n";
   $config .= "?>";
   $configFileName = '/config_' . trim(str_replace('.', '_', $_REQUEST['auth']['domain'])) . '.php';
   file_put_contents(__DIR__ . $configFileName, $config);
   return true;
}
/**
 * Send rest query to Bitrix24.
 *
 * @param       $method - Rest method, ex: methods
 * @param array $params - Method params, ex: array()
 * @param array $auth   - Authorize data, ex: array('domain' => 'https://test.bitrix24.com', 'access_token' => '7inpwszbuu8vnwr5jmabqa467rqur7u6')
 *
 * @return mixed
 */
function restCommand($method, array $params = array(), array $auth = array()) {
   $queryUrl  = 'https://' . $auth['domain'] . '/rest/' . $method;
   $queryData = http_build_query(array_merge($params, array('auth' => $auth['access_token'])));
   // writeToLog(array('URL' => $queryUrl, 'PARAMS' => array_merge($params, array("auth" => $auth["access_token"]))), 'ReportBot send data');
   $curl = curl_init();
   curl_setopt_array($curl, array(
      CURLOPT_POST           => 1,
      CURLOPT_HEADER         => 0,
      CURLOPT_RETURNTRANSFER => 1,
      CURLOPT_URL            => $queryUrl,
      CURLOPT_POSTFIELDS     => $queryData,
   ));
   $result = curl_exec($curl);
   curl_close($curl);
   $result = json_decode($result, 1);
   return $result;
}
/**
 * Write data to log file.
 *
 * @param mixed  $data
 * @param string $title
 *
 * @return bool
 */
function writeToLog($data, $title = '') {
   $log = "\n------------------------\n";
   $log .= date("Y.m.d G:i:s") . "\n";
   $log .= (strlen($title) > 0 ? $title : 'DEBUG') . "\n";
   $log .= print_r($data, 1);
   $log .= "\n------------------------\n";
   file_put_contents(__DIR__ . '/imbot.log', $log, FILE_APPEND);
   return true;
}
/**
 * Формируем отчет по команде
 *
 * @param      string $text строка, которую отправил юзер
  * @param      int $user идентификатор пользователя, который нам написал
 *
 * @return     array
 */
function getAnswer($command = '', $user) {

   switch (strtolower($command)) {
       case 'что горит':
           $arResult = b24BadTasks($user);
           break;
       default:
          $arResult = array(
            'title' => 'Туплю-с',
            'report'  => 'Не соображу, что вы хотите узнать. А может вообще не умею...',
         );
   }

   return $arResult;
}

function b24BadTasks ($user) {
   $tasks = restCommand('task.item.list', 
      array(
         'ORDER' => array('DEADLINE' => 'desc'),
         'FILTER' => array('RESPONSIBLE_ID' => $user, '<DEADLINE' => date("Y-m-d")),
         'PARAMS' => array(),
         'SELECT' => array()
      ), 
      $_REQUEST["auth"]);
   
   if (count($tasks['result']) > 0) {
      $arTasks = array();
      foreach ($tasks['result'] as $id => $arTask) {
         $arTasks[] = array(
            'LINK' => array(
               'NAME' => $arTask['TITLE'],
               'LINK' => 'https://'.$_REQUEST['auth']['domain'].'/company/personal/user/'.$arTask['RESPONSIBLE_ID'].'/tasks/task/view/'.$arTask['ID'].'/'
            )
         );
         $arTasks[] = array(
            'DELIMITER' => array(
               'SIZE' => 400,
               'COLOR' => '#c6c6c6'
            )
         );
      }
      $arReport = array(
         'title' => 'Да, кое-какие задачи уже пролетели, например:',
         'report'  => '',
         'attach' => $arTasks
      );
   }
   else {
      $arReport = array(
         'title' => 'Шикарно работаете!',
         'report'  => 'Нечем даже огорчить - ни одной просроченной задачи',
      );
   }
   return $arReport;
}

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

Создание нового приложения чат-бота доступно как «для личного пользования», так и в кабинете для публикации всем пользователям Битрикс24 через Маркет.

Примечание: Для чат-ботов не является обязательным использование сертификата https, но крайне рекомендуется из-за возможной передачи конфиденциальных данных клиента. При этом само приложение должно быть в кодировке UTF-8.

Запуск чат-бота на своем портале

Вы уже сейчас можете взять код примера чат-бота, выложить на своем сервере и запустить чат-бота на своем портале, не публикуя его через Маркет. Для этого в Битрикс24 есть возможность устанавливать локальные приложения:

  • В разделе левого меню Приложения 1 нужно нажать кнопку Добавить приложение 2:

    Нажмите на рисунок, чтобы увеличить

  • Далее выбираем Другое 3:

    Нажмите на рисунок, чтобы увеличить

  • И затем сценарий Локальное приложение 4:

    Нажмите на рисунок, чтобы увеличить

  • Выбираем тип Серверное приложение. Указываем название бота, а называться он у нас будет «Докладун». Включаем опцию Использует только API и даем приложению права доступа:
    - Веб-мессенджер (im) - без этого права невозможна передача сообщений пользователю,
    - Создание и управление Чат-ботами (imbot) – без этих прав приложение не сможет зарегистрировать чат-бота,
    - Задачи (task) и Задачи (расширенные права) (task_extended) – без этих прав приложение не сможет сформировать отчет по задачам, чтобы сообщить о них через чат-бота пользователю:

    Нажмите на рисунок, чтобы увеличить

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

  • Если бот создаётся для коробочной версии Битрикс24, то есть не используется опция Использует только API, то нужно использовать тип приложения Статичное и обязательное поле Архив с вашим приложением (zip) для указания пути к файлу-инсталлеру.

Собственно, уже все - в общем чате появится сообщение о том, что к порталу присоединился новый пользователь: чатбот по имени «Докладун». Мы можем открыть с ним чат, нажать на ссылку «Что горит?» и получить свой список просроченных задач.

Примечание: Другой пример - ЭхоБот, с большим количеством функций и постоянно обновляемый можно скачать c сервиса GitHub здесь.



Пример создания чат-бота для Открытых линий

Особые требования

Cоздание чат-бота для Открытых линий аналогично созданию обычного чат-бота, за исключением нескольких примечаний:

  1. При создании чат-бота для Открытых линий в imbot.register в параметр TYPE нужно передать O.
  2. Если необходимо расширить возможности уже существующего чат-бота, то нужно передать новый ключ OPENLINE => Y, тогда чат-бот будет работать в гибридном режиме.

    Внимание! В гибридном режиме чат-бот должен корректно обрабатывать ситуацию, когда его приглашают и общаются в групповом, персональном и чате открытых линий. Для этого нужно во всех входящих событиях (ONIMBOTMESSAGEADD, ONIMBOTJOINCHAT) проверять параметр CHAT_ENTITY_TYPE, для Открытых линий он должен быть CHAT_ENTITY_TYPE => LINES.

Во всем остальном, это привычный и уже знакомый чат-бот.

Для более тесной интеграции с Открытыми линиями необходимо иметь права доступа на scope imopenlines.

Имея такие права, будут доступны команды:


Примечание. Для чат-ботов не является обязательным использование сертификата https, но крайне рекомендуется из-за возможной передачи конфиденциальных данных клиента. При этом само приложение должно быть в кодировке UTF-8.

Скачать пример чат-бота для Открытых линий

В качестве примера чат-бота для открытых линий мы подготовили чат-бот ITR Bot. Cкачать его можно:

  • c сервиса GitHub (itr.php).
  • или взять в продукте «Битрикс24 в коробке» тут: \Bitrix\ImBot\Bot\OpenlinesMenuExample.

Данный чат-бот выступает в качестве первой линии поддержки - сначала все сообщения будут поступать к нему, а только потом сотрудникам в очередь через промежуток времени, который указан в настройках открытой линии. Также в него добавлен класс для построения многоуровневого меню в чатах.

Запуск на своём портале

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

  • В разделе левого меню Приложения 1 нужно нажать Разработчикам 2 и выбрать Другое 3:

    Нажмите на рисунок, чтобы увеличить

  • Затем использовать сценарий Локальное приложение 4:

    Нажмите на рисунок, чтобы увеличить

  • Выбираем тип Серверное приложение. Можно сменить название бота вместо «Локальное приложение». Включаем опцию Использует только API и даем приложению права доступа, как минимум на Создание и управление Чат-ботами (без этих прав приложение не сможет зарегистрировать чат-бота), а также на Открытые линии (без этих прав приложение не сможет работать с открытыми линиями).

    Нажмите на рисунок, чтобы увеличить

  • Поскольку наш скрипт написан таким образом, что является обработчиком всех событий, то в форме приложения мы укажем обе ссылки на один и тот же URL.
  • Нажмите кнопку Сохранить. Появятся дополнительные поля: Код приложения (client_id) и Ключ приложения (client_secret):

    Нажмите на рисунок, чтобы увеличить

  • Скопируйте данные из этих полей и [dw]вставьте в файл itr.php[/dw][di][/di].
  • В настройках бота нажмите Переустановить. Теперь он готов к работе.
  • Обратите внимание, данный бот не публикует сообщения о том, что его пригласили на портале. Но после установки он будет доступен в настройках открытых линий, где нужно выбрать его ответственным и указать через какое время переводить разговор от чат-бота в очередь:

    Примечание. Клиент может переключиться на оператора раньше, отправив сообщение 0 (цифра "ноль") или выбрав пункт меню 0. Wait operator answer. Вообще, пользователь может нажать на 0 при любом чат-боте и пользователь будет перенаправлен на оператора, обрабатывать дополнительно это не требуется.

  • На примере показан диалог - сначала отвечает ITR Bot, клиент кликает в меню по пунктам, далее очередь переходит на оператора (клиент выбрал пункт меню 0. Wait operator answer):

  • Настроить собственное меню в боте ITR Bot можно в методе itrRun.
    /**
     * Run ITR menu
     *
     * @param $portalId
     * @param $dialogId
     * @param $userId
     * @param string $message
     * @return bool
     */
    function itrRun($portalId, $dialogId, $userId, $message = '')
    {
    	if ($userId <= 0)
    		return false;
    
    	$menu0 = new ItrMenu(0);
    	$menu0->setText('Main menu (#0)');
    	$menu0->addItem(1, 'Text', ItrItem::sendText('Text message (for #USER_NAME#)'));
    	$menu0->addItem(2, 'Text without menu', ItrItem::sendText('Text message without menu', true));
    	$menu0->addItem(3, 'Open menu #1', ItrItem::openMenu(1));
    	$menu0->addItem(0, 'Wait operator answer', ItrItem::sendText('Wait operator answer', true));
    
    	$menu1 = new ItrMenu(1);
    	$menu1->setText('Second menu (#1)');
    	$menu1->addItem(2, 'Transfer to queue', ItrItem::transferToQueue('Transfer to queue'));
    	$menu1->addItem(3, 'Transfer to user', ItrItem::transferToUser(1, false, 'Transfer to user #1'));
    	$menu1->addItem(4, 'Transfer to bot', ItrItem::transferToBot('marta', true, 'Transfer to bot Marta', 'Marta not found :('));
    	$menu1->addItem(5, 'Finish session', ItrItem::finishSession('Finish session'));
    	$menu1->addItem(6, 'Exec function', ItrItem::execFunction(function($context){
    		$result = restCommand('imbot.message.add', Array(
    			"DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
    			"MESSAGE" => 'Function executed (action)',
    		), $_REQUEST["auth"]);
    		writeToLog($result, 'Exec function');
    	}, 'Function executed (text)'));
    	$menu1->addItem(9, 'Back to main menu', ItrItem::openMenu(0));
    
    	$itr = new Itr($portalId, $dialogId, 0, $userId);
    	$itr->addMenu($menu0);
    	$itr->addMenu($menu1);
    	$itr->run(prepareText($message));
    
    	return true;
    }
    


Пример создания канала поддержки

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

Для этого необходимо:

  1. Перейти в раздел Контакт-центр и подключить канал коммуникации Битрикс24.Network:

  2. После подключения вам будет доступна форма настроек подключения к Битрикс24.Network:

    • Обязательно заполните поля Название, Краткое описание и установите Аватар - это поможет клиентам легче вас найти.
    • Приветственное сообщение будет автоматически отправлено, как только пользователь перейдет в вашу Открытую линию Битрикс24.Network:

    • Обратите внимание на галочку Доступен в поиске: если вы хотите организовать закрытую линию поддержки, вам необходимо выключить этот пункт.

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

      Если опция Доступен в поиске включена, то вашу открытую линию можно будет найти по названию в поиске Бизнес-чата портала, точно также, как и пользователя Битрикс24.Network.

  3. Создать новую или выбрать действующую открытую линию технической поддержки по вашему продукту:


Чтобы вашим пользователям было удобно, можно с помощью Rest-команды imopenlines.network.join автоматически подключать вашу открытую линию к ним на портал:

$result = restCommand('imopenlines.network.join', Array(

    'CODE' => 'a588e1a88baaf301b9d0b0b33b1eefc2b' // код для поиска со страницы коннекторов

), $_REQUEST["auth"]);

После установки Открытой линии, вы можете написать клиенту приветственное сообщение с помощью Rest-команды imopenlines.network.message.add:

Спасибо за установку, будем рады помочь, если будут вопросы - пишите в этот чат. Хорошего дня! :)

Примечание: Функция restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk. Также возможно открыть такой канал поддержки через JavaScript-метод BX24.im.openMessenger.



Возможные типы чат-ботов Битрикс24

Для более четкого понимания, что могут делать чат-боты на платформе Битрикс24, приведем видео-примеры возможностей уже готовых чат-ботов. Типы чат-ботов приведены условно, вы можете создать чат-бота, который может сочетать 2 или 3 типа.

Личный помощник

  • Марта («1С-Битрикс») - ваш личный помощник. она помогает искать ответы на вопросы, напоминает о встречах, с ней можно поиграть в «Крестики-нолики», и она готова просто поговорить.
  • Справочная система

  • Реквизиты контрагента («1С-Битрикс») - ищет по базе ФНС и выдает необходимую информацию.
  • Поиск24 (cтудия «G-Tech») - ваш личный поисковый робот. Ищет в Яндексе и выводит 5 самых точных ответов.
  • Для специальных задач

  • Support Bot («1С-Битрикс») - внутренний чат-бот для быстрого доступа к тикет-системе «Битрикс24».
  • Работа с сервисами

  • OCR Bot (First Open Systems) - распознает сканы любых документов и сохраняет их в RTF.
  • Переводчик (PWEB) - помогает переводить тексты с одного языка на другой. Поддерживает перевод на 63 языка.
  • Работа с открытыми линиями

  • Чат-бот для Открытых линий («1С-Битрикс») сможет выступить помощником при первом контакте с пользователем или помогать вам посреди диалога.
  • Для развлечений

  • Андрейка (PWEB) - мастер на анекдоты. Поддерживает диалог анекдотами и смешными цитатами.
  • Giphy («1С-Битрикс») - поиск по большой библиотеке анимированных GIF-файлов, что позволяет легко найти необходимое изображение и поделиться им с коллегами.

Примечание: Полный список чат-ботов для платформы Битрикс24 можно увидеть в одноименном разделе Магазина приложений Битрикс24.



Сообщения

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

Форматирование

Сообщение можно форматировать, добавлять полужирный шрифт, перечеркивать и вставлять цитаты. В уроке приводятся команды пользователя, внешний вид и REST API для форматирования сообщений чата.

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


Коды форматирования

Если в чат отправить данное сообщение:

[B]полужирный[/B] текст
[U]подчеркнутый[/U] текст
[I]наклонный текст[/I] текст
[S]перечеркнутый[/S] текст

То оно отобразится таким образом:

Форматирование с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[B]полужирный[/B] текст
[U]подчеркнутый[/U] текст
[I]наклонный текст[/I] текст
[S]перечеркнутый[/S] текст",
), $_REQUEST["auth"]);


Перенос строки

Перенос строки осуществляется добавлением в текст символов:

[BR]
# BR # (без пробелов)
\n

Любой из этих кодов, сформирует перенос строки:

Перенос строки с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "Первая строка[BR]Вторая строка",
), $_REQUEST["auth"]);


Цитирование

Цитирование текста можно сделать двумя способами:

>>первая строка цитаты
>>вторая строка цитаты

------------------------------------------------------
Дмитрий Власов [08.04.2016 13:06:49]
Привет всем
------------------------------------------------------

Вид цитирования будет немного отличаться - во втором случае будет указан автор и время написания цитаты:

Цитирование с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => ">>первая строка цитаты
>>вторая строка цитаты

------------------------------------------------------
Дмитрий Власов [08.04.2016 13:06:49]
Привет всем
------------------------------------------------------",
), $_REQUEST["auth"]);


Ссылки

Любая ссылка в тексте автоматически станет кликабельной. Если по адресу ссылки есть «богатое форматирование», то ссылка автоматически его подхватит:

Ссылки с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "http://bitrix24.ru",
), $_REQUEST["auth"]);

Примечание: «Богатое форматирование» можно отключить, передав ключ 'URL_PREVIEW' => 'N' при создании сообщения:
restCommand('imbot.message.add', Array(
"DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
"MESSAGE" => "http://bitrix24.ru",
'URL_PREVIEW' => 'N' 
), $_REQUEST["auth"]);


Если вы отправите ссылку на картинку https://files.shelenkov.com/bitrix/images/mantis.jpg (окончание ссылки должно быть .png, .jpg, .gif), то она автоматически преобразуется в изображение:


Вы можете сформировать ссылку самостоятельно через код URL - [URL=http://bitrix24.ru]Ссылка на Битрикс24[/URL]:

Формирование ссылки с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[URL=http://bitrix24.ru]Ссылка на Битрикс24[/URL]",
), $_REQUEST["auth"]);

По аналогии с кодом URL, есть специальные коды на ссылки внутри мессенджера.

  • [USER=5]Марта[/USER] - ссылка на пользователя.
  • [CALL=84012334455]позвонить[/CALL] - кнопка для осуществления звонка через Битрикс24.
  • [CHAT=12]ссылка на чат[/CHAT] - ссылка на чат.

Форматирование специальных кодов с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[USER=5]Марта[/USER]
[CALL=84012334455]позвонить[/CALL]
[CHAT=12]ссылка на чат[/CHAT]",
), $_REQUEST["auth"]);


Отступы

Чтобы сделать отступы в сообщении, укажите символ табуляции:

Отступы с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "
Отступ
   Отступ
      Отступ",
), $_REQUEST["auth"]);


Активные ссылки (команды)

Если вы хотите, чтобы по клику на ссылку пользователь отправил какой-то текст, используйте тег SEND:

[send=текст]название кнопки[/send] - мгновенная отправка текста боту.

С помощью такого тега, вы сможете заставить пользователя отправить команду вашего бота, но существует более предпочтительный способ - Набираемые клавиатуры

Активные ссылки (команды) с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[send=текст]название кнопки[/send] - мгновенная отправка текста боту",
), $_REQUEST["auth"]);

Если необходимо, чтобы пользователь что-то дописал к команде, используйте код PUT:

[put=/search]Введите строку поиска[/put]

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

Отправка команды бота с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[put=/search]Введите строку поиска[/put]",
), $_REQUEST["auth"]);


Иконки

Добавление своей иконки в сообщение производится отправкой кода:

[icon=http://files.shelenkov.com/images/unicorn.png size=30 title=Единорог]

Иконка отобразится таким образом:

Также после этого иконка будет добавлена в набор смайлов Бизнес-чата. Удалить иконку из набора можно, нажав правой кнопкой мыши на иконке в наборе и выбрав Удалить.

Обязательным свойством является указание пути до картинки (без пробелов).

Доступны дополнительные атрибуты:

  • title - заголовок;
  • height - высота;
  • width - ширина;
  • size - высота и ширина;

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

Добавление своей иконки с помощью rest-api:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[icon=http://files.shelenkov.com/images/unicorn.png size=30 title=Единорог]",
), $_REQUEST["auth"]);

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



Вложения

Вложения можно применять к любым сообщениям (пользователя или бота) и уведомлениям в рамках мессенджера.



Как использовать вложения

Вы собираете объект Вложение и передаете его в метод отправки сообщения в ключ ATTACH (это может быть полная или сокращенная форма вложения).


Полная версия объекта ATTACH

JavaScript:

	ATTACH: {
	   ID: 1,
	   COLOR: "#29619b",
	   BLOCKS: [
		  {...},
		  {...},
	   ]
	}

PHP:

"ATTACH" => Array(
   "ID" => 1,
   "COLOR" => "#29619b",
   "BLOCKS" => Array(
      array(...),
      array(...),
   )
)

Ключи массива:

  • ID - идентификатор блока.
  • COLOR - отвечает за цветовое выделение вложения. По умолчанию цвет вложения назначается в цвет чата получателя (или если это уведомление в цвет текущего пользователя), Данный ключ можно не задавать, если не требуется.
  • BLOCKS должен содержать блоки разметки, которые мы рассмотрим чуть ниже.

Пример:

JavaScript:

BX24.callMethod('imbot.message.add', {
    DIALOG_ID: 'chat20921',
    MESSAGE: 'Message from bot',
    ATTACH: {
		   ID: 1,
		   COLOR: "#29619b",
		   BLOCKS: [
			{LINK: {
				NAME: "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
				DESC: "Необходимо реализовать к релизу!",
				LINK: "https://api.bitrix24.com/"
			}},
			{IMAGE: {
				NAME: "Пример реализации",
				LINK: "http://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
			}}
		   ]
		}
}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "Message with attach",
   "ATTACH" => Array(
      "ID" => 1,
      "COLOR" => "#29619b",
      "BLOCKS" => Array(
         Array("LINK" => Array(
            "NAME" => "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
            "DESC" => "Необходимо реализовать к релизу!",
            "LINK" => "https://api.bitrix24.com/"
         )),
         Array("IMAGE" => Array(
            "NAME" => "Пример реализации",
            "LINK" => "http://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
         ))
      )
   )
), $_REQUEST["auth"]);


Краткая версия объекта ATTACH

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

JavaScript:

	ATTACH: [
	  {...},
	  {...},
   ]

PHP:

"ATTACH" => Array(
   array(...),
   array(...),
)

В отличие от полного варианта, на первом уровне сразу указываются блоки разметки, без объявления ключа BLOCKS

Пример:

JavaScript:

BX24.callMethod('imbot.message.add', {
    DIALOG_ID: 'chat20921',
    MESSAGE: 'Message from bot',
    ATTACH: [
		{LINK: {
			NAME: "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
			DESC: "Необходимо реализовать к релизу!",
			LINK: "https://api.bitrix24.com/"
		}},
		{IMAGE: {
			NAME: "Пример реализации",
			LINK: "http://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
		}}
	]
		
}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "Message from bot",
   "ATTACH" => Array(
      Array("LINK" => Array(
         "NAME" => "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
         "DESC" => "Необходимо реализовать к релизу!",
         "LINK" => "https://api.bitrix24.com/"
      )),
      Array("IMAGE" => Array(
         "NAME" => "Пример реализации",
         "LINK" => "http://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
      ))
   )
), $_REQUEST["auth"]);

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

Обратите внимание: из-за сложности структуры, вложения автоматически не добавляются при отправке в XMPP, почту или в виде PUSH-уведомления на телефон.



Коллекции блоков


Блок пользователя (USER)


Блок со ссылками (LINK)


Блок с текстом (MESSAGE)


Блок c разделителем (DELIMITER)


Блок для построения строк и колонок (GRID)

  1. Блочное построение (BLOCK)

  2. Строчное построение (LINE)

  3. Построение в виде двух колонок (COLUMN)


Блок c изображениями (IMAGE)


Блок с файлами (FILE)



Блок пользователя


USER - вывод блока с аватаром и именем пользователя.

Поля AVATAR (аватар) и LINK (ссылка) не являются обязательными.

Пример:

JavaScript:

{USER: {
	NAME: "Иван Иванов",
	AVATAR: "https://files.shelenkov.com/bitrix/images/avatar.png",
	LINK: "https://shelenkov.com"
}},

PHP:

Array("USER" => Array(
   "NAME" => "Иван Иванов",
   "AVATAR" => "https://files.shelenkov.com/bitrix/images/avatar.png",
   "LINK" => "https://shelenkov.com/",
)),

Вместо ключа LINK можно использовать и ссылки на сущности:

  • CHAT_ID - для указания ссылки на чат;
  • BOT_ID - для указания ссылки на бота;
  • USER_ID - для указания ссылки на пользователя.


Блок со ссылками


LINK - вывод блока с ссылкой на ресурс, описанием и картинкой-пояснением. Этот блок используется при автоматическом создании «богатых ссылок».

Поля DESC (описание) и PREVIEW (картинка) не являются обязательными полями.

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

Пример:

JavaScript:

{LINK: {
	PREVIEW: "https://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
	WIDTH: 1000,
	HEIGHT: 638,
	NAME: "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
	DESC: "Необходимо реализовать к релизу!",
	LINK: "https://api.bitrix24.com/",
}},

PHP:

Array("LINK" => Array(
   "PREVIEW" => "https://dev.1c-bitrix.ru/bitrix/templates/1c-bitrix-new/images/logo.png",
   "WIDTH" => "1000",
   "HEIGHT" => "638",
   "NAME" => "Тикет #12345: новое API для модуля \"Веб-мессенджер\"",
   "DESC" => "Необходимо реализовать к релизу!",
   "LINK" => "https://api.bitrix24.com/"
)),

Вместо ключа LINK можно использовать и ссылки на сущности:

  • CHAT_ID => 1 - для указания ссылки на чат;
  • USER_ID => 1 - для указания ссылки на пользователя.


Блок c текстом


MESSAGE - вывод простого текста без форматирования.

Пример:

JavaScript:

	{MESSAGE: "API будет доступно в обновлении [B]im 16.0.0[/B]"},

PHP:

	Array("MESSAGE" => "API будет доступно в обновлении [B]im 16.0.0[/B]"),

В тексте доступны bb-коды: USER, CHAT, SEND, PUT, CALL, BR, B, U, I, S, URL.



Блок c разделителем


DELIMITER - вывод разделителя, можно задать цвет и размер.

Поля COLOR (цвет) и SIZE (размер) не являются обязательными полями.

Пример:

JavaScript:

{DELIMITER: {SIZE: 200, COLOR: "#c6c6c6"}},

PHP:

Array("DELIMITER" => Array(
   'SIZE' => 200,
   'COLOR' => "#c6c6c6"
)),


Блок для построения строк и колонок

GRID - существует три представления блока: блочное, строчное и в виде 2х колонок.

Внимание Во всех 3-х представлениях смешивать элементы в рамках одной записи нельзя. Если нужно одновременно использовать блоки разного типа, нужно создавать новый блок:

Пример JavaScript

Пример PHP

Для всех видов блоков для построения строк и колонок доступны дополнительные ключи:

  • COLOR - цвет значения;
  • CHAT_ID - значение станет ссылкой на чат в веб-мессенджере;
  • USER_ID - значение станет ссылкой на пользователя в веб-мессенджере;
  • LINK - значение станет ссылкой.
  • Для ключа VALUE доступны bb-коды: USER, CHAT, SEND, PUT, CALL, BR, B, U, I, S, URL.

Блочное представление

"DISPLAY" => "BLOCK" - данные идут друг под другом.

Доступен ключ WIDTH для указания ширины блока (в пикселях).

Пример:

JavaScript:

{GRID: [
	{
		NAME: "Описание",
		VALUE: "Требуется реализовать возможность добавлять структурированные сущности в сообщения и уведомления мессенджера.",
		DISPLAY: "BLOCK",
		WIDTH: 250
	},
	{
		NAME: "Категория",
		VALUE: "Пожелания",
		DISPLAY: "BLOCK",
		WIDTH: 100
	},
]},

PHP:

Array("GRID" => Array(
    Array(
        "NAME" => "Описание",
        "VALUE" => "Требуется реализовать возможность добавлять структурированные сущности в сообщения и уведомления мессенджера.",
        "DISPLAY" => "BLOCK",
        "WIDTH" => "250"
    ),
    Array(
        "NAME" => "Категория",
        "VALUE" => "Пожелания",
        "DISPLAY" => "BLOCK"
    ),
)),


Строчное представление

"DISPLAY" => "LINE" - каждый блок идет друг за другом пока не закончится доступное место, после чего переносится на новую строку.

Доступен ключ WIDTH для указания ширины блока (в пикселях).

Пример:

JavaScript:

{GRID: [
	{
		NAME: "Приоритет",
		VALUE: "Высокий",
		COLOR: "#ff0000",
		DISPLAY: "LINE",
		WIDTH: 250
	},
	{
		NAME: "Категория",
		VALUE: "Пожелания",
		DISPLAY: "LINE",
	},
]},

PHP:

Array("GRID" => Array(
   Array(
      "NAME" => "Приоритет",
      "VALUE" => "Высокий",
      "COLOR" => "#ff0000",
      "DISPLAY" => "LINE",
       "WIDTH" => "250"
   ),
   Array(
      "NAME" => "Категория",
      "VALUE" => "Пожелания",
      "DISPLAY" => "LINE"
   ),
)), 



Представление в виде двух колонок

"DISPLAY" => "COLUMN" - построение в виде двух колонок.

Доступен ключ WIDTH для указания ширины первой колонки (в пикселях).

Начиная с 22 версии REST, в представлении в виде двух колонок можно не передавать один из обязательных параметров NAME или VALUE:
  • если не передать VALUE, то NAME будет на всю ширину таблицы;
  • если не передать NAME, то VALUE будет на всю ширину колонки.

Пример результата:

Пример:

JavaScript:

{GRID: [
	{
		NAME: "Приоритет",
		VALUE: "Высокий",
		DISPLAY: "COLUMN",
	},
	{
		NAME: "Категория",
		VALUE: "Пожелания",
		DISPLAY: "COLUMN",
	},
]},

PHP:

Array("GRID" => Array(
    Array(
        "NAME" => "Приоритет",
        "VALUE" => "Высокий",
        "DISPLAY" => "COLUMN"
        "WIDTH" => "250"
    ),
    Array(
        "NAME" => "Категория",
        "VALUE" => "Пожелания",
        "DISPLAY" => "COLUMN"
    ),
)),


Блок c изображениями


IMAGE - блок с изображениями.

Рекомендуется заполнять поле PREVIEW с указанием уменьшенной копии изображения, если поле не заполнено используется LINK.

Поля NAME (название) и PREVIEW (картинка-превью) не являются обязательными.

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

Пример:

JavaScript:

{IMAGE: {
	NAME: "Это Mantis",
	LINK: "https://files.shelenkov.com/bitrix/images/mantis.jpg",
	PREVIEW: "https://files.shelenkov.com/bitrix/images/mantis.jpg",
	WIDTH: 1000,
	HEIGHT: 638,
}},

PHP:

Array("IMAGE" => Array(
    Array(
        "NAME" => "Это Mantis",
        "LINK" => "https://files.shelenkov.com/bitrix/images/mantis.jpg",
        "PREVIEW" => "https://files.shelenkov.com/bitrix/images/mantis.jpg",
        "WIDTH" => "1000",
        "HEIGHT" => "638"
    )
)),


Блок с файлами


FILE - отображает форматированную ссылку для загрузки файла.

Размер файла необходимо указывать в байтах.

Поля NAME (название файла), SIZE (размер файла) не являются обязательными.

Пример:

JavaScript:

{FILE: {
	NAME: "mantis.jpg",
	LINK: "https://files.shelenkov.com/bitrix/images/mantis.jpg",
	SIZE: 1500000,
}},

PHP:

Array("FILE" => Array(
    Array(
        "NAME" => "mantis.jpg",
        "LINK" => "https://files.shelenkov.com/bitrix/images/mantis.jpg",
        "SIZE" => "1500000"
    )
)),


Конструктор, примеры

Объект Вложение является конструктором, вы можете «собрать» его так, как вам требуется, используя доступные блоки. Порядок добавления блоков имеет значение.


«Баг-трекер»

JavaScript:

BX24.callMethod('imbot.message.add', {
    DIALOG_ID: 'chat20921',
    MESSAGE: 'Message from bot',
    ATTACH: [
       {USER: {
            NAME: "Уведомления Mantis",
            AVATAR: "http://files.shelenkov.com/bitrix/images/mantis2.jpg",
            LINK: "http://shelenkov.com/",
        }},
        {LINK: {
            NAME: "Открыть Mantis из внешней сети",
            LINK: "http://shelenkov.com/",
        }},
        {DELIMITER: {
            SIZE: 200,
            COLOR: "#c6c6c6"
        }},
        {GRID: [
            {
                NAME: "Проект",
                VALUE: "BUGS",
                DISPLAY: "LINE",
                WIDTH: 100
            },
            {
                NAME: "Категория",
                VALUE: "im",
                DISPLAY: "LINE",
                WIDTH: 100
            },
            {
                NAME: "Сводка",
                VALUE: "Требуется реализовать возможность добавлять структурированные сущности в сообщения и уведомления мессенджера.",
                DISPLAY: "BLOCK"
            },
        ]},
        {DELIMITER: {
            SIZE: 200,
            COLOR: "#c6c6c6"
        }},
        {GRID: [
            {
                NAME: "Новое обращение",
                VALUE: "",
                DISPLAY: "ROW",
                WIDTH: 100
            },
            {
                NAME: "Назначено",
                VALUE: "Шеленков Евгений",
                DISPLAY: "ROW",
                WIDTH: 100
            },
            {
                NAME: "Дедлайн",
                VALUE: "04.11.2015 17:50:43",
                DISPLAY: "ROW",
                WIDTH: 100
            },
        ]},
   ]
}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "У вас новое уведомление",
   "ATTACH" => Array(
      Array("USER" => Array(
         "NAME" => "Уведомления Mantis",
         "AVATAR" => "http://files.shelenkov.com/bitrix/images/mantis2.jpg",
         "LINK" => "http://shelenkov.com/",
      )),
      Array("LINK" => Array(
         "NAME" => "Открыть Mantis из внешней сети",
         "LINK" => "http://shelenkov.com/",
      )),
      Array("DELIMITER" => Array(
         'SIZE' => 200,
         'COLOR' => "#c6c6c6"
      )),
      Array("GRID" => Array(
         Array(
            "NAME" => "Проект",
            "VALUE" => "BUGS",
            "DISPLAY" => "LINE",
            "WIDTH" => 100
         ),
         Array(
            "NAME" => "Категория",
            "VALUE" => "im",
            "DISPLAY" => "LINE",
            "WIDTH" => 100
         ),
         Array(
            "NAME" => "Сводка",
            "VALUE" => "Требуется реализовать возможность добавлять структурированные сущности в сообщения и уведомления мессенджера.",
            "DISPLAY" => "BLOCK"
         ),
      )),
      Array("DELIMITER" => Array(
         'SIZE' => 200,
         'COLOR' => "#c6c6c6"
      )),
      Array("GRID" => Array(
         Array(
            "NAME" => "Новое обращение",
            "VALUE" => "",
            "DISPLAY" => "ROW",
            "WIDTH" => 100
         ),
         Array(
            "NAME" => "Назначено",
            "VALUE" => "Шеленков Евгений",
            "DISPLAY" => "ROW",
            "WIDTH" => 100
         ),
         Array(
            "NAME" => "Дедлайн",
            "VALUE" => "04.11.2015 17:50:43",
            "DISPLAY" => "ROW",
            "WIDTH" => 100
         ),
      )),
   )
), $_REQUEST["auth"]);


«Информационный листок»

JavaScript:

BX24.callMethod('imbot.message.add', {
        DIALOG_ID: 'chat20921',
    MESSAGE: 'У вас новое уведомление',
    ATTACH: {
		ID: 1,
		COLOR: "#29619b",
		BLOCKS: [
			{MESSAGE: "Коллеги, обновление [b]im 16.0.0[/b] проверено и готово к выгрузке.[BR] Необходимо поставить тег.[BR] В обновление больше не подкладываем."},
			{IMAGE: {LINK: "http://files.shelenkov.com/bitrix/images/win.jpg"}}
		]
	}
}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "У вас новое уведомление",
   "ATTACH" => Array(
      Array("MESSAGE" => "Коллеги, обновление [b]im 16.0.0[/b] проверено и готово к выгрузке.[BR] Необходимо поставить тег.[BR] В обновление больше не подкладываем."),
      Array("IMAGE" => Array(
         "LINK" => "http://files.shelenkov.com/bitrix/images/win.jpg",
      )),
   )
), $_REQUEST["auth"]);


Работа с клавиатурами

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

Как клавиатуру добавить к чат-боту

Клавиатура – это часть сообщения, при создании сообщения нужно добавить ключ KEYBOARD и передать параметры.

Методы, которые поддерживают клавиатуру:

Рассмотрим на примере это сообщение:

restCommand('imbot.command.answer', Array(
   "COMMAND_ID" => $command['COMMAND_ID'],
   "MESSAGE_ID" => $command['MESSAGE_ID'],
   "MESSAGE" => "Hello! My name is EchoBot :)[br] I designed to answer your questions!",
   "KEYBOARD" => Array(
      Array(
        "TEXT" => "Bitrix24",
        "LINK" => "http://bitrix24.com",
        "BG_COLOR" => "#29619b",
        "TEXT_COLOR" => "#fff",
        "DISPLAY" => "LINE",		
      ),
      Array(
        "TEXT" => "BitBucket",
        "LINK" => "https://bitbucket.org/Bitrix24com/rest-bot-echotest",
        "BG_COLOR" => "#2a4c7c",
        "TEXT_COLOR" => "#fff",
        "DISPLAY" => "LINE",
      ),
      Array("TYPE" => "NEWLINE"), // перенос строки
      Array("TEXT" => "Echo", "COMMAND" => "echo", "COMMAND_PARAMS" => "test from keyboard", "DISPLAY" => "LINE"),
      Array("TEXT" => "List", "COMMAND" => "echoList", "DISPLAY" => "LINE"),
      Array("TEXT" => "Help", "COMMAND" => "help", "DISPLAY" => "LINE"),
   )
), $_REQUEST["auth"]);

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

Клавиатура – это набор кнопок, каждая кнопка может состоять из следующих ключей:

  • TEXT – текст кнопки;
  • LINK – ссылка;
  • COMMAND – команда, которая будет отправлена боту;
  • COMMAND_PARAMS – параметры для команды;
  • BG_COLOR – цвет кнопки;
  • BLOCK – если указать Y, то после клика на одну кнопку клавиатура будет блокироваться. Клавиатуру блокируют только кнопки, которые отправляют ajax боту (учтите, что ссылки на внешние ресурсы LINK и мгновенные действия ACTION не блокируют клавиатуру). Блокировка нужна для ограничения выполнения ajax-команд из-за их асинхронности и времени ожидания: после нажатия кнопки клавиатура блокируется и ожидается реакция с бэкенда Битрикс24, чтобы пользователь не нажал вторую кнопку и т. д. Бэкенд обрабатывает команды и принимает решение, разблокировать ли клавиатуру, создав новую, или же скрыть её;
  • DISABLED – если указать Y, то данная кнопка не будет кликабельной;
  • TEXT_COLOR – цвет текста;
  • DISPLAY – тип кнопки. Если указан тип BLOCK, то на одной строчке может быть только эта кнопка. Если указан тип LINE, то кнопки будут выстроены друг за другом;
  • WIDTH – ширина кнопки. Обратите внимание, для максимального удобства набор кнопок в одну линию не рекомендуется делать более 225 пикселей, это максимальная ширина на мобильном устройстве.
  • APP_ID – идентификатор установленного приложения для чата.
  • APP_PARAMS – параметры для запуска приложения для чата.
  • ACTION – действие, может быть одно из следующих типов (REST ревизии 28):
    • PUT – вставить в поле ввода.
    • SEND – отправить текст.
    • COPY – копировать текст в буфер обмена.
    • CALL – позвонить.
    • DIALOG – открыть указанный диалог.
  • ACTION_VALUE – значение, для каждого типа означает свое (REST ревизии 28):
    • PUT – текст, который будет вставлен в поле ввода.
    • SEND – текст, который будет отправлен.
    • COPY – текст, который будет скопирован в буфер обмена.
    • CALL – номер телефона в международном формате.
    • DIALOG – идентификатор диалога, это может быть ID пользователя, либо ID чата в формате chatXXX.

Обязательными полями является TEXT и либо поле LINK, либо поле COMMAND.

Если указан ключ LINK, то кнопка становится внешней ссылкой. Если указаны поля COMMAND и COMMAND_PARAMS, то кнопка является действием и отправляет команду чат-боту, не публикуя ее в чат.

Если указаны поля APP_ID и APP_PARAMS, то кнопка откроет окно с приложением для чата.

Если необходимо сделать две строки с кнопками в ряд, то для их разделения нужно добавить кнопку со следующим содержимым: "TYPE" => "NEWLINE".

Обработка команд чат-ботом

Для обработки нажатия кнопок клавиатуры, используются команды.

  1. Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register (чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом "HIDDEN" => "Y").

    В кнопке указывается следующие ключи:

    "COMMAND" => "page", // команда, которая будет отправлена чат-боту 
    "COMMAND_PARAMS" => "1", // параметры для команды
    
  2. Нажатие на кнопку сгенерирует событие ONIMCOMMANDADD.

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

  4. Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT - это специальный ключ, описывающий в каком контексте была вызвана команда:
    • если команду написал пользователь самостоятельно, там будет TEXTAREA;
    • если команда пришла из клавиатуры, то будет KEYBOARD;
    • если команда пришла из контекстного меню, то будет MENU.

Готовый пример, можно посмотреть в обновленной версии ЭхоБота (bot.php).

Обработка открытия приложения для чата

Приложение для чата, запускаемые из контекстного меню, работают по принципам Контекстного приложения.

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

  1. EchoBot
    Постраничная навигация, кнопки при вызове команды «Помощь»

  2. Марта
    Просто напишите марте Поиграй со мной!. Клавиатура используется как игровое поле:

  3. Giphy
    Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему:



Работа с контекстным меню

Контекстное меню

Контекстное меню позволит пользователю взаимодействовать с чат-ботом или приложением для чата из контекстного меню сообщения.

Как добавить свои пункты в контекстное меню

Контекстное меню – это часть сообщения, при создании сообщения нужно добавить ключ MENU и передать параметры.

Методы, которые поддерживают контекстное меню:

Рассмотрим на примере это сообщение:

restCommand('im.message.add', Array(
   "DIALOG_ID" => 12,
   "MESSAGE" => "Hello! Message with context menu!",
   "MENU" => Array(
      Array(
        "TEXT" => "Bitrix24",
        "LINK" => "http://bitrix24.com",
      ),
      Array(
         "TEXT" => "Echo", 
         "COMMAND" => "echo", 
         "COMMAND_PARAMS" => "test from keyboard"
      ),
      Array(
         "TEXT" => "Open app", 
         "APP_ID" => "12", 
         "APP_PARAMS" => "TEST"
      ),
   )
), $_REQUEST["auth"]);

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

Контекстное меню - это набор кнопок, каждая кнопка может состоять из следующих ключей:

  • TEXT - текст кнопки;
  • LINK - ссылка;
  • COMMAND - команда, которая будет отправлена боту;
  • COMMAND_PARAMS - параметры для команды;
  • APP_ID - идентификатор установленного приложения для чата.
  • APP_PARAMS - параметры для запуска приложения для чата.
  • DISABLED - если указать Y, то данная кнопка не будет кликабельной.
  • ACTION - действие, может быть одно из следующих типов (REST ревизии 28):
    • PUT - вставить в поле ввода.
    • SEND - отправить текст.
    • COPY - копировать текст в буфер обмена.
    • CALL - позвонить.
    • DIALOG - открыть указанный диалог.
  • ACTION_VALUE - значение, для каждого типа означает свое (REST ревизии 28):
    • PUT - текст, который будет вставлен в поле ввода.
    • SEND - текст, который будет отправлен.
    • COPY - текст, который будет скопирован в буфер обмена.
    • CALL - номер телефона в международном формате.
    • DIALOG - идентификатор диалога, это может быть ID пользователя, либо ID чата в формате chatXXX.

Обязательными полями является TEXT и либо поле LINK, либо поле COMMAND.

Если указан ключ LINK, то кнопка становится внешней ссылкой. Если указаны поля COMMAND и COMMAND_PARAMS, то кнопка является действием и отправляет команду чат-боту, не публикуя ее в чат. Доступно с 26 версии ревизии API (версии платформы).

Если указаны поля APP_ID и APP_PARAMS, то кнопка откроет окно с приложением для чата.

Если необходимо сделать две строки с кнопками в ряд, то для их разделения нужно добавить кнопку со следующим содержимым: "TYPE" => "NEWLINE".

Обработка команд чат-ботом

Для обработки нажатия кнопок клавиатуры и пунктов меню, используются команды.

  1. Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register (чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом "HIDDEN" => "Y").

    В кнопке указывается следующие ключи:

    "COMMAND" => "page", // команда, которая будет отправлена чат-боту 
    "COMMAND_PARAMS" => "1", // параметры для команды
    
  2. Нажатие на кнопку создаст событие ONIMCOMMANDADD.

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

  4. Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT - это специальный ключ, описывающий в каком контексте была вызвана команда:
    • если команду написал пользователь самостоятельно, там будет TEXTAREA;
    • если команда пришла из клавиатуры, то будет KEYBOARD;
    • если команда пришла из контекстного меню, то будет MENU.


Обработка открытия приложения для чата

Приложение для чата, запускаемые из контекстного меню, работают по принципам Контекстного приложения.



Bot API

Для работы с Bot API при создании приложения (или загрузке новой версии) нужно указать scope: imbot (Создание и управление чат-ботами).



Работа с чат-ботами

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


МетодОписание метода
imbot.register Регистрация чат-бота.
imbot.unregister Удаление чат-бота из системы.
imbot.update Обновление данных бота.
imbot.bot.list Получение доступных чат-ботов.

Примечания:

Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

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



imbot.register

Регистрация чат-бота

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

Примечания:

Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

Для работы через Вебхуки вам необходимо во все методы передавать параметр CLIENT_ID. Такой код должен быть уникален для каждого чат-бота.

Вызов метода

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

    'CODE' => 'newbot', // Строковой идентификатор бота, уникальный в рамках вашего приложения (обяз.)
    'TYPE' => 'B', // Тип, B – чат-бот, ответы поступают сразу, O – чат-бот для Открытых линий, S – чат-бот с повышенными привилегиями (supervisor)
    'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик событий, поступивших от сервера - см. Обработчики событий ниже (обяз).
    'OPENLINE' => 'Y', // Включение режима поддержки Открытых линий, можно не указывать, если TYPE = 'O'
    'CLIENT_ID' => '', // строковый идентификатор, используется только в режиме Вебхуков
    'PROPERTIES' => Array( // Личные данные чат-бота (обяз.)
        'NAME' => 'NewBot', // Имя чат-бота (обязательное одно из полей NAME или LAST_NAME)
        'LAST_NAME' => '', // Фамилия (обязательное одно из полей NAME или LAST_NAME)
        'COLOR' => 'GREEN', // Цвет для мобильного приложения RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
        'EMAIL' => 'test@test.ru', // E-mail для связи. НЕЛЬЗЯ использовать e-mail, дублирующий e-mail реальных пользователей
        'PERSONAL_BIRTHDAY' => '2016-03-11', // День рождения в формате YYYY-mm-dd
        'WORK_POSITION' => 'Лучший сотрудник', // Занимаемая должность, используется как описание чат-бота
        'PERSONAL_WWW' => 'http://test.ru', // Ссылка на сайт
        'PERSONAL_GENDER' => 'F', // Пол, допустимые значения M – мужской, F – женский, пусто, если не требуется указывать
        'PERSONAL_PHOTO' => '/* base64 image */', // Аватар - base64
    )

), $_REQUEST["auth"]);

Обязательные поля:

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

Числовой идентификатор созданного бота BOT_ID или ошибка.

Обработчики событий

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

'EVENT_MESSAGE_ADD' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события отправки сообщения чат-боту
'EVENT_WELCOME_MESSAGE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат
'EVENT_BOT_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события удаления чат-бота со стороны клиента
'EVENT_MESSAGE_UPDATE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события изменения
'EVENT_MESSAGE_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события удаления сообщений

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

Rest API - События установки и обновления

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

Код Описание
EVENT_MESSAGE_ADD_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_WELCOME_MESSAGE_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_BOT_DELETE_ERROR Ссылка обработчик события невалидная или не указана.
CODE_ERROR Не указан строковый идентификатор.
NAME_ERROR Не указано одно из обязательных полей NAME или LAST_NAME.
WRONG_REQUEST Что-то пошло не так.
MAX_COUNT_ERROR Достигнуто максимальное количество зарегистрированных ботов для одного приложения.

Чат-бот с повышенными привилегиями (supervisor) получает доступ ко всем сообщениям в чатах, где он состоит (ко всем, если его пригласили с доступом к истории, и к новым, если доступ к истории ему не доступен).

Для его создания в методе imbot.register в поле TYPE укажите тип S.

Обратите внимание, если это не требуется логикой вашего приложения, то рекомендуется отвечать боту на сообщения пользователя только при упоминании этого чат-бота. Проверить это можно по полю TO_USER_ID, которое будет передано в событие.

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

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

Максимальное количество ботов для одного приложения: 5.



imbot.unregister

Удаление чат-бота из системы

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

Примечание:

Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

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

Вызов метода

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

    'BOT_ID' => 39 // числовой идентификатор бота
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков

), $_REQUEST["auth"]);

Внимание! Все чаты один-на-один данного чат-бота с пользователями будут утеряны.

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

true или ошибка.

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

Rest API - События установки и обновления

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

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


imbot.update

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

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

Примечания:

Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

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

Вызов метода

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

    'BOT_ID' => 39, // Идентификатор чат-бота, которого нужно изменить (обяз.)
    'CLIENT_ID' => '', // строковый идентификатор чат-бота, используется только в режиме Вебхуков
    'FIELDS' => Array( // Данные для обновления (обяз.)
        'CODE' => 'newbot', // Строковой идентификатор чат-бота, уникальный в рамках вашего приложения 
        'EVENT_HANDLER' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик событий, поступивших от сервера - см. Обработчики событий ниже (обяз).
        'PROPERTIES' => Array( // Обязательное при обновлении данных бота
            'NAME' => 'UpdatedBot', // Имя чат-бота 
            'LAST_NAME' => '', // Фамилия чат-бота 
            'COLOR' => 'MINT', // Цвет чат-бота для мобильного приложения RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME,  BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
            'EMAIL' => 'test2@test.ru', // E-mail для связи
            'PERSONAL_BIRTHDAY' => '2016-03-12', // День рождения в формате YYYY-mm-dd
            'WORK_POSITION' => 'Мой второй бот', // Занимаемая должность, используется как описание чат-бота
            'PERSONAL_WWW' => 'http://test2.ru', // Ссылка на сайт
            'PERSONAL_GENDER' => 'M', // Пол бота, допустимые значения M  - мужской, F - женсикй, пусто, если не требуется указывать
            'PERSONAL_PHOTO' => '/* base64 image */', // Аватар чат-бота - base64
        )
    )

), $_REQUEST["auth"]);

Обязательные поля:

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

true или ошибка.

Обработчики событий

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

'EVENT_MESSAGE_ADD' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события отправки сообщения чат-боту
'EVENT_WELCOME_MESSAGE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат
'EVENT_BOT_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события удаления чат-бота со стороны клиента
'EVENT_MESSAGE_UPDATE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события изменения
'EVENT_MESSAGE_DELETE' => 'http://www.hazz/chatApi/event.php', // Ссылка на обработчик события подписки на события удаления сообщений

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

Rest API - События установки и обновления

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

Код Описание
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
EVENT_MESSAGE_ADD_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_WELCOME_MESSAGE_ERROR Ссылка обработчик события невалидная или не указана.
EVENT_BOT_DELETE_ERROR Ссылка обработчик события невалидная или не указана.
NAME_ERROR Не указано одно из обязательных полей NAME или LAST_NAME чат- бота.
WRONG_REQUEST Что-то пошло не так.

Метод imbot.update больше не поддерживает изменение полей TYPE и OPENLINE (im 17.5.10).



imbot.bot.list

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

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

Примечания:

Для работы ботов должен быть обеспечен доступ к marta.bitrix.info с портала или сайта.

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

Вызов метода

$result = restCommand('imbot.bot.list', Array(
), $_REQUEST["auth"]);

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

Массив массивов, содержащий данные по чат-ботам:



Сервис Giphy

[ICO_NEW data-adding-timestamp="1702313533"]

Сервис Giphy – онлайн-база данных и поисковая система, которая позволяет пользователям искать и делиться анимированными файлами GIF.


МетодОписание метода
imbot.Giphy.list Получение списка GIF-картинок по строке.
imbot.Giphy.listPopular Получение популярных GIF-картинок. Возвращает 15 GIF-картинок.


[/ICO_NEW]

imbot.Giphy.list

[ICO_NEW data-adding-timestamp="1702313607"]

Получение списка GIF-картинок по строке


Параметры

Параметр Пример Обязат. Описание Ревизия
filter 32
filter.search 'test' Да Строка, по которой ищем GIF-картинки. 32
limit 15 Нет Сколько GIF-картинок получить. 32
offset 15 Нет Смещение. 32

Связанные P&P события

Нет

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

JavaScript

BX.rest.callMethod('imbot.Giphy.list', {
	filter: {search: 'test'}
})
	.then(result => console.log(result.data()))
	.catch(result => console.error(result.error()))
;

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

[
	{
		"preview": "https://media4.giphy.com/media/gw3IWyGkC0rsazTi/200w_d.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200w_d.webp&ct=g",
		"original": "https://media4.giphy.com/media/gw3IWyGkC0rsazTi/200.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media0.giphy.com/media/yNs2a0jRkYxy6191B2/200w_d.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200w_d.webp&ct=g",
		"original": "https://media0.giphy.com/media/yNs2a0jRkYxy6191B2/200.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media2.giphy.com/media/3o8dFjB7T9lNldqliM/200w_d.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200w_d.webp&ct=g",
		"original": "https://media2.giphy.com/media/3o8dFjB7T9lNldqliM/200.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media0.giphy.com/media/xT1XGWGd90BrYwnTl6/200w_d.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200w_d.webp&ct=g",
		"original": "https://media0.giphy.com/media/xT1XGWGd90BrYwnTl6/200.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media4.giphy.com/media/8FNlmNPDTo2wE/200w_d.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200w_d.webp&ct=g",
		"original": "https://media4.giphy.com/media/8FNlmNPDTo2wE/200.webp?cid=b7142cb9hgdk6b19hsx8g5powaqrznauiaw5mc0uhjmpc4uu&rid=200.webp&ct=g"
	},
		...
]

Описание ключей:


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



[/ICO_NEW]

imbot.Giphy.listPopular

[ICO_NEW data-adding-timestamp="1702313675"]

Получение популярных GIF-картинок. Возвращает 15 GIF-картинок


Параметры

Нет

Связанные P&P события

Нет

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

JavaScript

BX.rest.callMethod('imbot.Giphy.listPopular', {})
	.then(result => console.log(result.data()))
	.catch(result => console.error(result))
;

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

[
	{
		"preview": "https://media0.giphy.com/media/KT38VKe0p2aM35i7HS/200w_d.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200w_d.webp&ct=g",
		"original": "https://media0.giphy.com/media/KT38VKe0p2aM35i7HS/200.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media3.giphy.com/media/uUP7F5A1rQR9uKls9P/200w_d.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200w_d.webp&ct=g",
		"original": "https://media3.giphy.com/media/uUP7F5A1rQR9uKls9P/200.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media3.giphy.com/media/r7I5UK3W25OIyAlsrc/200w_d.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200w_d.webp&ct=g",
		"original": "https://media3.giphy.com/media/r7I5UK3W25OIyAlsrc/200.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media1.giphy.com/media/3o7TKoWXm3okO1kgHC/200w_d.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200w_d.webp&ct=g",
		"original": "https://media1.giphy.com/media/3o7TKoWXm3okO1kgHC/200.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200.webp&ct=g"
	},
	{
		"preview": "https://media2.giphy.com/media/9GIFGeuuinRxgEj7Zq/200w_d.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200w_d.webp&ct=g",
		"original": "https://media2.giphy.com/media/9GIFGeuuinRxgEj7Zq/200.webp?cid=b7142cb9xia5p36zjc2wowjrd10gh7hfpt4eirrcrzhps7z7&rid=200.webp&ct=g"
	},
		...
]

Описание ключей:


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

Ошибки с серверной стороны. Это стандартные ошибки модуля «микросервис», среди которых есть:



[/ICO_NEW]

Работа с чатами

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


МетодОписание метода
imbot.chat.user.list Получение списка участников.
imbot.chat.user.add Приглашение участников.
imbot.chat.user.delete Исключение участников.
imbot.chat.leave Выход чат-бота из указанного чата.
imbot.chat.updateTitle Обновление заголовка чата.
imbot.chat.updateColor Обновление цвета чата.
imbot.chat.updateAvatar Обновление аватара чата.
imbot.chat.add Создание чата от лица чат-бота.
imbot.chat.get Получение идентификатора чата.
imbot.chat.setOwner Смена владельца чата от лица чат-бота.
imbot.dialog.get Получение информации о диалоге.


imbot.chat.user.list

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

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

Вызов метода

$result = restCommand('imbot.chat.user.list', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один

), $_REQUEST["auth"]);

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

Массив идентификаторов участников или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата


imbot.chat.user.add

Приглашение участников

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

Вызов метода

$result = restCommand('imbot.chat.user.add', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'USERS' => Array(3,4) // Идентификаторы новых пользователей
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
WRONG_REQUEST У вас недостаточно прав для добавления участника в чат или участник уже состоит в чате.


imbot.chat.user.delete

Исключение участников

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

Вызов метода

$result = restCommand('imbot.chat.user.delete', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'USER_ID' => 4 // Идентификатор исключаемого пользователя
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
USER_ID_EMPTY Не передан идентификатор пользователя.
WRONG_REQUEST У вас недостаточно прав для добавления участника в чат или участник уже состоит в чате.


imbot.chat.leave

Выход чат-бота из указанного чата

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

Вызов метода

$result = restCommand('imbot.chat.leave', Array(

   'CHAT_ID' => 13 // Идентификатор чата, из которого выйти
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
ACCESS_ERROR У вас недостаточно прав для отправки статуса в этот чат.
BOT_ID_ERROR Чат-бот не найден.


imbot.chat.updateTitle

Обновление заголовка чата

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

Вызов метода

$result = restCommand('imbot.chat.updateTitle', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'TITLE' => 'Новое имя для чата' // Новый заголовок
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
TITLE_EMPTY Не передан новый заголовок чата.
WRONG_REQUEST Заголовок уже установлен или указанный чат не существует.


imbot.chat.updateColor

Обновление цвета чата

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

Вызов метода

$result = restCommand('imbot.chat.updateColor', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'COLOR' => 'MINT' // Цвет чата для мобильного приложения - RED,  GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один 

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
WRONG_COLOR Цвет не входит в список доступных цветов.
WRONG_REQUEST Цвет уже установлен или указанный чат не существует.


imbot.chat.updateAvatar

Обновление аватара чата

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

Вызов метода

$result = restCommand('imbot.chat.updateAvatar', Array(

   'CHAT_ID' => 13 // идентификатор чата
   'AVATAR' => '/* base64 image */' // Изображение в формате base64
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос, можно не указывать, если чат-бот всего один   

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
AVATAR_ERROR Передан не корректный формат изображения.
WRONG_REQUEST Чат не существует.


imbot.chat.add

Создание чата от лица чат-бота

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

Вызов метода

$result = restCommand('imbot.chat.add', Array(

   'TYPE' => 'CHAT' // OPEN - открытый для вступления чат, CHAT – обычный чат по приглашениям, по умолчанию CHAT
   'TITLE' => 'Мой новый закрытый чат', // Заголовок 
   'DESCRIPTION' => 'Очень важные события', // Описание 
   'COLOR' => 'PINK', // Цвет для мобильного приложения - RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN,  AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
   'MESSAGE' => 'Добро пожаловать!', // Первое приветственное сообщение в чате
   'USERS' => Array(1,2), // Участники (обяз.)
   'AVATAR' => '/* base64 image */', // Аватар в base64 формате
   'ENTITY_TYPE' => 'CHAT', // Идентификатор произвольной сущности (например CHAT, CRM, OPENLINES, CALL и тд), может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE
   'ENTITY_ID' => 13, // Числовой идентификатор сущности, может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE
   'OWNER_ID' => 39, // Идентификатор владельца. Можно не указывать, если вы создаете чат под нужным пользователем
   'BOT_ID' => 39, // Идентификатор бота, от которого идет запрос. Можно не указывать, если он всего один

), $_REQUEST["auth"]);
Обязательные поля: USERS (участники чата).

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

Числовой идентификатор CHAT_ID или ошибка.

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

Код Описание
USERS_EMPTY Не переданы участники чата.
WRONG_REQUEST Что-то пошло не так.


imbot.chat.get

Получение идентификатора чата

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

Вызов метода

$result = restCommand('imbot.chat.get', Array(

   'ENTITY_TYPE' => 'OPEN', // Идентификатор произвольной сущности (например CHAT, CRM, OPENLINES, CALL и тд), может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE (обяз.)
   'ENTITY_ID' => 13, // Числовой идентификатор сущности, может быть использован для поиск чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE (обяз.)
   'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос. Можно не указывать, если чат-бот всего один
   
), $_REQUEST["auth"]);

Обязательные поля:

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

Возвращает идентификатор чата CHAT_ID или null.



imbot.chat.setOwner

Смена владельца чата от лица чат-бота

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

Вызов метода

$result = restCommand('imbot.chat.setOwner', Array(

   'CHAT_ID' => 13 // Идентификатор чата
   'USER_ID' => '2' // Идентификатор нового владельца
   'BOT_ID' => 39, // Идентификатор бота, от которого идет запрос. Можно не указывать, если он всего один.  

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
USER_ID_EMPTY Не передан идентификатор нового владельца.
WRONG_REQUEST Метод вызван не владельцем чата или указанный пользователь не является участником чата.


imbot.dialog.get

Получение информации о диалоге

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 24

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat29
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
24

Вызов метода

JavaScript

BX24.callMethod('imbot.dialog.get', {
	DIALOG_ID: 'chat29'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('imbot.dialog.get', Array(
	'DIALOG_ID': 'chat29'
), $_REQUEST["auth"]);

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

{
    "result": 
  {
    "id": "21191",
    "title": "Мятный чат №3",
    "owner": "2",
    "extranet": false,
    "avatar": "",
    "color": "#4ba984",
    "type": "chat",
    "entity_type": "",
    "entity_data_1": "",
    "entity_data_2": "",
    "entity_data_3": "",
    "date_create": "2017-10-14T12:15:32+02:00",
    "message_type": "C"
  }
}

Описание ключей:


Пример ответа при возникновения ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:


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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу

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



Работа с сообщениями

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


МетодОписание метода
imbot.message.add Отправка сообщения от чат-бота.
imbot.message.update Отправка изменения сообщения чат-бота.
imbot.message.delete Удаление сообщения чат-бота.
imbot.message.like Установка «Мне нравится».
imbot.chat.sendTyping Отправка сообщения «Чат-бот пишет сообщение...».

Обратите внимание! Данные методы работы с сообщениями обычно применяются, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.



imbot.message.add

Отправка сообщения от чат-бота

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

Примечание: Данный метод работы с сообщениями обычно применяется, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.

Вызов метода

$result = restCommand('imbot.message.add', Array(

    'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос; можно не указывать, если чат-бот всего один
    'DIALOG_ID' => 1, // Идентификатор диалога; это либо USER_ID пользователя, либо chatXX - где XX идентификатор чата, передается в событии ONIMBOTMESSAGEADD и ONIMJOINCHAT
    'MESSAGE' => 'answer text', // Тест сообщения
    'ATTACH' => '', // Вложение, необязательное поле
    'KEYBOARD' => '', // Клавиатура, необязательное поле
    'MENU' => '', // Контекстное меню, необязательное поле 
    'SYSTEM' => 'N', // Отображать сообщения в виде системного сообщения, необязательное поле, по умолчанию 'N'
    'URL_PREVIEW' => 'Y' // Преобразовывать ссылки в rich-ссылки, необязательное поле, по умолчанию 'Y'

), $_REQUEST["auth"]);

Вы можете публиковать сообщение от имени бота в приватные диалоги (будут показаны как системное сообщение). Для этого вместо DIALOG_ID укажите FROM_USER_ID и TO_USER_ID.

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

Идентификатор сообщения MESSAGE_ID или ошибка.

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

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

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


imbot.message.update

Отправка изменения сообщения чат-бота

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

Примечание: Данный метод работы с сообщениями обычно применяется, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.

Вызов метода

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

    'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос; можно не указывать, если бот всего один
    'MESSAGE_ID' => 1, // Идентификатор сообщения
    'MESSAGE' => 'answer text', // Текст сообщения, необязательное поле, если передать пустое значение - сообщение будет удалено
    'ATTACH' => '', // Вложение, необязательное поле
    'KEYBOARD' => '', // Клавиатура, необязательное поле
    'MENU' => '', // Контекстное меню, необязательное поле 
    'URL_PREVIEW' => 'Y' // Преобразовывать ссылки в rich-ссылки, необязательное поле

), $_REQUEST["auth"]);

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

true или ошибка.

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

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

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


imbot.message.delete

Удаление сообщения чат-бота

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

Примечание: Данный метод работы с сообщениями обычно применяется, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.

Вызов метода

$result = restCommand('imbot.message.delete', Array(

    'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос; можно не указывать, если бот всего один
    'MESSAGE_ID' => 1, // Идентификатор сообщения
    'COMPLETE' => 'N', //  Если сообщение нужно удалить полностью, без следов, то необходимо указать Y (необязательный параметр)

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Чат-бот не принадлежит этому приложению. Работать можно только с чат-ботами, установленными в рамках приложения.
MESSAGE_ID_ERROR Не передан идентификатор сообщения.
CANT_EDIT_MESSAGE У вас нет доступа к этому сообщению.


imbot.message.like

Установка «Мне нравится»

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

Примечание: Данный метод работы с сообщениями обычно применяется, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.

Вызов метода

$result = restCommand('imbot.message.like', Array(

    'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос; можно не указывать, если чат-бот всего один
    'MESSAGE_ID' => 1, // Идентификатор сообщения (любое сообщение, отправленное в личных диалогах или в групповых чатах, где присутствует чат-бот)
    'ACTION' => 'auto' // Действие, связанное с методом: plus - поставит метку «Мне нравится»; minus - снимет метку «Мне нравится»; auto - автоматически вычислит, нужно поставить или снять метку. Если не указывать, будет работать в режиме auto

), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Чат-бот не принадлежит этому приложению. Работать можно только с чат-ботами, установленными в рамках приложения.
MESSAGE_ID_ERROR Не передан идентификатор сообщения.
WITHOUT_CHANGES После вызова состояние статуса «Мне нравится» не изменилось.


imbot.chat.sendTyping

Отправка сообщения «Чат-бот пишет сообщение...»

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

Примечание: Данный метод работы с сообщениями обычно применяется, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие ONIMBOTMESSAGEADD.

Вызов метода

$result = restCommand('imbot.chat.sendTyping', Array(

    'BOT_ID' => 39, // Идентификатор чат-бота, от которого идет запрос; можно не указывать, если бот всего один
    'DIALOG_ID' => 1, // Идентификатор диалога, это либо USER_ID пользователя, либо chatXX - где XX идентификатор чата, передается в событии ONIMBOTMESSAGEADD и ONIMJOINCHAT

), $_REQUEST["auth"]);

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

true или ошибка.

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

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

Код Описание
BOT_ID_ERROR Чат-бот не найден.
DIALOG_ID_EMPTY Не передан идентификатор диалога.


Команды

Команды бывают общими и локальными:

Общие

Пример «Команды и активные ссылки»

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

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


МетодОписание метода
imbot.command.register Регистрация команды для обработки чат-ботом.
imbot.command.unregister Удаление обработки команды.
imbot.command.update Обновление данных в команде.
imbot.command.answer Публикация ответа на команду.

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



imbot.command.register

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

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

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

Вызов метода

$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 или ошибка.

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

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

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

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

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



imbot.command.unregister

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

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

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

Вызов метода

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

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

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

true или ошибка.

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

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


imbot.command.update

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

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

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

Вызов метода

$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"]);

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

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

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

true или ошибка.

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

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


imbot.command.answer

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

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

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

Вызов метода

$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 Что-то пошло не так.


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

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

Событие на установку приложения 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__].



Cобытие, возникающее при отправке сообщения
ONIMBOTMESSAGEADD

[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 // Сообщение
    [MESSAGE_ORIGINAL] => [USER=39]NewBot[/USER] test3 // Оригинальное сообщение с BB-кодом чат-бота (параметр доступен только в групповых чатах)
    [FROM_USER_ID] => 1 // Идентификатор пользователя отправившего сообщение
    [TO_USER_ID] => 1 // Идентификатор бота или пользователя: в диалоге "один-на-один" это будет идентификатор бота, а в групповом чате - идентификатор пользователя, кому направлено обращение. Если указано 0 - значит всем участникам чата
    [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.
)


Cобытие, возникающее при редактировании сообщения
ONIMBOTMESSAGEUPDATE

[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 // Сообщение
    [MESSAGE_ORIGINAL] => [USER=39]NewBot[/USER] test3 // Оригинальное сообщение с BB-кодом чат-бота (параметр доступен только в групповых чатах)
    [FROM_USER_ID] => 1 // Идентификатор пользователя отправившего сообщение
    [TO_USER_ID] => 1 // Идентификатор бота или пользователя: в диалоге "один-на-один" это будет идентификатор бота, а в групповом чате - идентификатор пользователя, кому направлено обращение. Если указано 0 - значит всем участникам чата
    [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.
)


Cобытие, возникающее при удалении сообщения
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 // Код чат-бота


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

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

Файл с комментариями и аватаркой доступны в репозитории GitHub

Полный список методов и событий Bot API

Работа с чат-ботами

МетодОписание метода
imbot.register Регистрация чат-бота.
imbot.unregister Удаление чат-бота из системы.
imbot.update Обновление данных бота.
imbot.bot.list Получение доступных чат-ботов.


Работа с чатами

МетодОписание метода
imbot.chat.user.list Получение списка участников.
imbot.chat.user.add Приглашение участников.
imbot.chat.user.delete Исключение участников.
imbot.chat.leave Выход чат-бота из указанного чата.
imbot.chat.updateTitle Обновление заголовка чата.
imbot.chat.updateColor Обновление цвета чата.
imbot.chat.updateAvatar Обновление аватара чата.
imbot.chat.add Cоздание чата от лица чат-бота.
imbot.chat.get Получение идентификатора чата.
imbot.chat.setOwner Cмена владельца чата от лица чат-бота.
imbot.dialog.get Получение информации о диалоге.


Работа с сообщениями

МетодОписание метода
imbot.message.add Отправка сообщения от чат-бота.
imbot.message.update Отправка изменения сообщения чат-бота.
imbot.message.delete Удаление сообщения чат-бота.
imbot.message.like Установка «Мне нравится».
imbot.chat.sendTyping Отправка сообщения «Чат-бот пишет сообщение...».


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

МетодОписание метода
imbot.command.register Регистрация команды для обработки чат-ботом.
imbot.command.unregister Удаление обработки команды.
imbot.command.update Обновление данных в команде.
imbot.command.answer Публикация ответа на команду.


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

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


Chat API

Для работы с Chat API при создании приложения (или загрузке новой версии) нужно указать scope: im (Чат и уведомления).



Версия платформы

im.revision.get – получение информации о ревизиях API

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

Параметры

Нет.

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

JavaScript

BX24.callMethod('im.revision.get', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.revision.get', Array(
), $_REQUEST["auth"]);

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

{    
	"result": {
		"rest": 18,
		"web": 117,
		"mobile": 9,
	}
}

Описание ключей:


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



Работа с чатами

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


МетодОписание метода
im.chat.add Создание чата.
im.chat.user.list Получение списка участников.
im.chat.user.add Приглашение участников.
im.chat.user.delete Исключение участников.
im.chat.leave Покинуть чат.
im.chat.updateTitle Обновление заголовка чата.
im.chat.updateColor Обновление цвета чата.
im.chat.updateAvatar Обновление аватара чата.
im.chat.setOwner Смена владельца чата.
im.chat.get Получение идентификатора чата.
im.chat.mute Отключение уведомлений в чате.


im.chat.add

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
TYPE CHAT Нет Тип чата OPEN | CHAT
(OPEN - открытый для вступления чат, CHAT - обычный чат по приглашениям, по-умолчанию CHAT)
18
TITLE Мой новый закрытый чат Нет Заголовок чата 18
DESCRIPTION Очень важный чат Нет Описание чата 18
COLOR PINK Нет Цвет чата для мобильного приложения: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE 18
MESSAGE Добро пожаловать в чат Нет Первое приветственное сообщение в чате 18
USERS Array(1,2) Да Участники чата 18
AVATAR base64 image Нет Аватар чата в base64 формате 18
ENTITY_TYPE CHAT Нет Идентификатор сущности, может быть использован для поиска по этому полю и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE 18
ENTITY_ID 13 Нет Числовой идентификатор сущности, может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE 18
OWNER_ID 39 Нет Идентификатор владельца чата. Можно не указывать, владельцем будет тот, от кого идёт запрос. 18


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

PHP

$result = restCommand('im.chat.add', Array(

   'TYPE' => 'CHAT',
   'TITLE' => 'Мой новый закрытый чат',
   'DESCRIPTION' => 'Очень важный чат',
   'COLOR' => 'PINK',
   'MESSAGE' => 'Добро пожаловать в чат',
   'USERS' => Array(1,2), 
   'AVATAR' => 'base64 image',
   'ENTITY_TYPE' => 'CHAT',
   'ENTITY_ID' => 13,
   'OWNER_ID' => 39,

), $_REQUEST["auth"]);

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

{
	"result": 123
}


Пример ответа при возникновении ошибки

{
    "error": "USERS_EMPTY",
    "error_description": "Не переданы участники чата"
}

Описание ключей:

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

Код Описание
USERS_EMPTY Не переданы участники чата
WRONG_REQUEST Что-то пошло не так


im.chat.user.list

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18


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

PHP

$result = restCommand('im.chat.user.list', Array(

   'CHAT_ID' => 13

), $_REQUEST["auth"]);

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

{
	"result": [1,2]
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата, либо передан неверный идентификатор.


im.chat.user.add

Приглашение участников

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18
USERS Array(3,4) Да Идентификаторы новых пользователей 18
HIDE_HISTORY N Нет Отображение истории переписки для пользователя, которого добавляют в чат этим методом. Y/N - по умолчанию N. Если передать Y то новый пользователь не будет видеть историю. 18

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

PHP

$result = restCommand('im.chat.user.add', Array(

   'CHAT_ID' => 13,
   'USERS' => Array(3,4)
   'HIDE_HISTORY' => N,

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
WRONG_REQUEST У вас недостаточно прав для добавления участника в чат или участник уже состоит в чате


im.chat.user.delete

Исключение участников

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18
USER_ID 4 Да Идентификатор исключаемого пользователя 18

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

PHP

$result = restCommand('im.chat.user.delete', Array(

   'CHAT_ID' => 13,
   'USER_ID' => 4

), $_REQUEST["auth"]);

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

{
	"result": true
}

Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
USER_ID_EMPTY Не передан идентификатор пользователя
WRONG_REQUEST У вас недостаточно прав для добавления участника в чат или участник уже состоит в чате


im.chat.leave

Покинуть чат

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18


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

PHP

$result = restCommand('im.chat.leave', Array(

   'CHAT_ID' => 13

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
WRONG_REQUEST Вы не состоите в этом чате


im.chat.updateTitle

Обновление заголовка чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Нет Идентификатор чата 18
TITLE Новое имя для чата Нет Новый заголовок 18


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

PHP

$result = restCommand('im.chat.updateTitle', Array(

   'CHAT_ID' => 13,
   'TITLE' => 'Новое имя для чата'

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
TITLE_EMPTY Не передан новый заголовок чата
WRONG_REQUEST Заголовок уже установлен или указанный чат не существует


im.chat.updateColor

Обновление цвета чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18
COLOR MINT Да Цвет чата для мобильного приложения (RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE) 18


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

PHP

$result = restCommand('im.chat.updateColor', Array(

   'CHAT_ID' => 13,
   'COLOR' => 'MINT'

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
WRONG_COLOR Цвет не входит в список доступных цветов
WRONG_REQUEST Цвет уже установлен или указанный чат не существует


im.chat.updateAvatar

Обновление аватара чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18
AVATAR /* base64 image */ Да Изображение в формате base64 18


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

PHP

$result = restCommand('im.chat.updateAvatar', Array(

   'CHAT_ID' => 13,
   'AVATAR' => '/* base64 image */'

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
AVATAR_ERROR Передан не корректный формат изображения
WRONG_REQUEST Чат не существует


im.chat.setOwner

Смена владельца чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Да Идентификатор чата 18
USER_ID 2 Да Идентификатор нового владельца чата 18


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

PHP

$result = restCommand('im.chat.setOwner', Array(

   'CHAT_ID' => 13,
   'USER_ID' => '2'

), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
USER_ID_EMPTY Не передан идентификатор нового владельца чата
WRONG_REQUEST Метод вызван не владельцем чата или указанный пользователь не является участником чата


im.chat.get

Получение идентификатора чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
ENTITY_TYPE CRM - для CRM,
[dw]LINES[/dw][di]Со стороны оператора[/di] или [dw]LIVECHAT[/dw][di]Со стороны пользователя[/di] - для открытых линий
Да Идентификатор сущности. Может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE 18
ENTITY_ID LEAD|13 - для CRM,
facebook|2|1647215182041969|862 - для [dw]открытых линий[/dw][di]ENTITY_ID совпадает с USER_CODE из сессии.[/di]
Да Числовой идентификатор сущности. Может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE 18


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

PHP

$result = restCommand('im.chat.get', Array(

   'ENTITY_TYPE' => 'CRM',
   'ENTITY_ID' => 'LEAD|13',
   
), $_REQUEST["auth"]);

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

{
	"result": 10
}
Результат выполнения: возвращает идентификатор чата CHAT_ID или null.


im.chat.mute

Отключение уведомлений в чате

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 17 Да Идентификатор чата 19
MUTE Y Да Отключить или включить уведомления - Y|N 19


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

JavaScript

BX24.callMethod('im.chat.mute', {
	'CHAT_ID': 17,
	'MUTE': 'Y'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.chat.mute', Array(
	'CHAT_ID' => 17,
	'MUTE' => 'Y'
), $_REQUEST["auth"]);

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

{
	"result": true
}


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата


Работа с диалогами


МетодОписание метода
im.dialog.messages.get Получение списка последних сообщений в чате.
im.dialog.read Изменение факта прочтения сообщений: все сообщения до указанного (включая само сообщение) помечаются как прочитанные.
im.dialog.unread Изменение факта прочтения сообщений: все сообщения после указанного (включая само сообщение) помечаются как непрочитанные.

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

Методы, указанные с использованием javascript-метода BX24.callMethod:

МетодОписание метода
im.dialog.users.list Получение информации об участниках чата (поддерживается пагинация).
im.dialog.writing Отправка статуса «вам пишут...».
im.dialog.read.all Установка метки «прочитано» для всех диалогов.


im.dialog.messages.get

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat29
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
19
LAST_ID 28561624 Нет Идентификатор последнего загруженного сообщения 19
FIRST_ID 454322 Нет Идентификатор первого загруженного сообщения 19
LIMIT 20 Нет Ограничение на выборку сообщений в диалоге 19

Обратите внимание! Из-за потенциально большого обьема данных, этот метод не поддерживает стандартную постраничную навигацию Bitrix24 Rest Api.



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

JavaScript

BX24.callMethod('im.dialog.messages.get', {
	DIALOG_ID: 'chat29'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.dialog.messages.get', Array(
	'DIALOG_ID': 'chat29'
), $_REQUEST["auth"]);

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

{
    "result": {
        "messages": [
          {
            "id": 28561624,
            "chat_id": 29,
            "author_id": 1,
            "date": "2018-01-29T16:58:47+03:00",
            "text": "http://yandex.ru",
            "params": {
              "URL_ID": [
                5
              ],
              "URL_ONLY": "Y",
              "ATTACH": [
                {
                  "ID": "5",
                  "BLOCKS": [
                    {
                      "RICH_LINK": [
                        {
                          "NAME": "яндекс",
                          "LINK": "http://yandex.ru/",
                          "DESC": "Найдется все",
                          "PREVIEW": "https://yastatic.net/morda-logo/i/share-logo-ru.png"
                        }
                      ]
                    }
                  ],
                  "COLOR": "transparent"
                }
              ]
            }
          },
          {
            "id": 28561623,
            "chat_id": 29,
            "author_id": 28,
            "date": "2018-01-29T16:43:38+03:00",
            "text": "",
            "params": {
              "FILE_ID": [
                540
              ]
            }
          },
          {
            "id": 28561622,
            "chat_id": 29,
            "author_id": 1,
            "date": "2018-01-29T16:43:12+03:00",
            "text": "Работает да :) :)",
            "params": {
              "IS_EDITED": "Y"
            }
          },
          {
            "id": 28561618,
            "chat_id": 29,
            "author_id": 0,
            "date": "2018-01-25T15:15:22+03:00",
            "text": "Евгений Шеленков изменил тему чата на \"Большой чат\"",
            "params": null
          },
        ],
        "users": [
          {
            "id": 1,
            "name": "Евгений Шеленков",
            "first_name": "Евгений",
            "last_name": "Шеленков",
            "work_position": "",
            "color": "#df532d",
            "avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
            "gender": "M",
            "birthday": "",
            "extranet": false,
            "network": false,
            "bot": false,
            "connector": false,
            "external_auth_id": "default",
            "status": "online",
            "idle": false,
            "last_activity_date": "2018-01-29T17:35:31+03:00",
            "mobile_last_date": false,
            "departments": [
              50
            ],
            "absent": false,
            "phones": {
              "work_phone": "",
              "personal_mobile": "",
              "personal_phone": ""
            }
          },
          {
            "id": 28,
            "name": "Иван Елпидин",
            "first_name": "Иван",
            "last_name": "Елпидин",
            "work_position": "менеджер",
            "color": "#728f7a",
            "avatar": "http://192.168.2.232/upload/resize_cache/main/8b8/100_100_2/26.jpg",
            "gender": "M",
            "birthday": "26-01",
            "extranet": false,
            "network": false,
            "bot": false,
            "connector": false,
            "external_auth_id": "default",
            "status": "online",
            "idle": false,
            "last_activity_date": false,
            "mobile_last_date": false,
            "departments": [
              58
            ],
            "absent": false,
            "phones": {
              "work_phone": "8 (495) 222-33-55",
              "personal_mobile": "8 (495) 123-55-65",
              "personal_phone": ""
            }
          },
        ],
        "files": [
            {
                "id": 540,
                "chatId": 29,
                "date": "2018-01-29T16:43:39+03:00",
                "type": "image",
                "preview": "",
                "name": "1176297_698081120237288_696773366_n.jpeg",
                "size": 55013,
                "image": {
                    "width": 960,
                    "height": 640
                },
                "status": "done",
                "progress": 100,
                "authorId": 1,
                "authorName": "Евгений Шеленков",
                "urlPreview": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/show.file.php?fileId=540&preview=Y&fileName=1176297_698081120237288_696773366_n.jpeg",
                "urlShow": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/show.file.php?fileId=540&fileName=1176297_698081120237288_696773366_n.jpeg",
                "urlDownload": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/download.file.php?fileId=540"
            }
        ],
        "chat_id": 29
    }
}

Описание ключей:

Описание дополнительных параметров:



Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу


im.dialog.read

Изменение факта прочтения сообщений: все сообщения до указанного (включая само сообщение) помечаются как прочитанные

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat29
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
21
MESSAGE_ID 12 Да Идентификатор последнего прочитанного сообщения в диалоге 21


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

JavaScript

BX24.callMethod('im.dialog.read', {
  'DIALOG_ID': chat29,
  'MESSAGE_ID': 12,
}, function(result){
  if(result.error())
  {
    console.error(result.error().ex);
  }
  else
  {
    console.log(result.data());
  }
});

PHP

$result = restCommand('im.dialog.read', Array(
  'DIALOG_ID' => chat29,
  'MESSAGE_ID' => 12,  
), $_REQUEST["auth"]);

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

{
    "result": 
    {
        dialogId: "chat76", 
        chatId: 76, 
        counter: 1, 
        lastId: 6930
    }
} 

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

{
 "result": false
}


Пример ответа при возникновении ошибки

{
    "error": "MESSAGE_ID_ERROR",
    "error_description": "Message ID can't be empty"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Указан некорректный идентификатор сообщения
DIALOG_ID_EMPTY Указан некорректный идентификатор диалога


im.dialog.unread

Изменение факта прочтения сообщений: все сообщения после указанного (включая само сообщение) помечаются как непрочитанные

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat29
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
21
MESSAGE_ID 12 Да Идентификатор первого непрочитанного диалога 21


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

JavaScript

BX24.callMethod('im.dialog.unread', {
  'DIALOG_ID': chat29,
  'MESSAGE_ID': 12,
}, function(result){
  if(result.error())
  {
    console.error(result.error().ex);
  }
  else
  {
    console.log(result.data());
  }
});

PHP

$result = restCommand('im.dialog.unread', Array(
  'DIALOG_ID' => chat29,
  'MESSAGE_ID' => 12,  
), $_REQUEST["auth"]);

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

{
  "result": true
} 


Пример ответа при возникновении ошибки

{
    "error": "MESSAGE_ID_ERROR",
    "error_description": "Message ID can't be empty"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Указан некорректный идентификатор сообщения
DIALOG_ID_EMPTY Указан некорректный идентификатор диалога


im.dialog.get

Получение информации о диалоге

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat29
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
24


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

JavaScript

BX24.callMethod('im.dialog.get', {
	DIALOG_ID: 'chat29'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.dialog.get', Array(
	'DIALOG_ID': 'chat29'
), $_REQUEST["auth"]);

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

{
    "result": 
  {
    "id": "21191",
    "title": "Мятный чат №3",
    "owner": "2",
    "extranet": false,
    "avatar": "",
    "color": "#4ba984",
    "type": "chat",
    "entity_type": "",
    "entity_data_1": "",
    "entity_data_2": "",
    "entity_data_3": "",
    "date_create": "2017-10-14T12:15:32+02:00",
    "message_type": "C"
  }
}

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу


im.dialog.users.list

Получение информации об участниках чата (поддерживается пагинация)

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat74 Да Идентификатор диалога. Формат:
  • chatXXX – чат получателя, если сообщение для чата
  • или
  • XXX – идентификатор получателя, если сообщение для приватного диалога
30
SKIP_EXTERNAL N Нет Пропустить всех системных пользователей - 'Y'|'N' (по умолчанию 'N') 30
SKIP_EXTERNAL_EXCEPT_TYPES 'bot, email' Нет Строка с теми типами системных пользователей, которых нужно оставить в выборке 30


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

JavaScript

B24.callMethod(
  'im.dialog.users.list',
  {
    DIALOG_ID: 'chat74',
    SKIP_EXTERNAL: 'Y'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

[
  {
    "id": 1019,
    "active": true,
    "name": "alexa shasha",
    "first_name": "alexa",
    "last_name": "shasha",
    "work_position": "",
    "color": "#df532d",
    "avatar": "",
    "gender": "M",
    "birthday": "",
    "extranet": false,
    "network": false,
    "bot": false,
    "connector": false,
    "external_auth_id": "default",
    "status": "online",
    "idle": false,
    "last_activity_date": "2021-10-30T11:24:12+02:00",
    "mobile_last_date": "2021-10-20T13:02:33+02:00",
    "absent": false,
    "departments": [
      1
    ],
    "phones": false
  },
  {
    "id": 1,
    "active": true,
    "name": "Алексей Шахворостов",
    "first_name": "Алексей",
    "last_name": "Шахворостов",
    "work_position": "",
    "color": "#df532d",
    "avatar": "",
    "gender": "M",
    "birthday": "",
    "extranet": false,
    "network": false,
    "bot": false,
    "connector": false,
    "external_auth_id": "default",
    "status": "online",
    "idle": false,
    "last_activity_date": "2021-10-30T13:36:34+02:00",
    "mobile_last_date": "2021-10-27T16:39:26+02:00",
    "absent": false,
    "departments": [
      1
    ],
    "phones": false
  }
]

Описание ключей:


Пример ответа при возникновении ошибки

{
  "error":"DIALOG_ID_EMPTY",
  "error_description":"Dialog ID can\u0027t be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Параметр DIALOG_ID не задан или не соответствует формату
ACCESS_ERROR Текущий пользователь не имеет прав доступа к данным


im.dialog.writing

Отправка статуса «вам пишут...»

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID 13 Да Идентификатор диалога. Формат:
  • chatXXX – чат получателя, если сообщение для чата
  • или
  • XXX – идентификатор получателя, если сообщение для приватного диалога
30


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

JavaScript

B24.callMethod(
  'im.dialog.writing',
  {},
  function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

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

true

Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Параметр DIALOG_ID не передан либо не соответствует формату XXX
CHAT_ID_EMPTY Параметр DIALOG_ID не передан либо не соответствует формату chatXXX
ACCESS_ERROR У пользователя нет прав на данный чат


im.dialog.read.all

Установка метки «прочитано» для всех диалогов

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметры не передаются.

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

JavaScript

B24.callMethod(
  'im.dialog.read.all',
  {
  },
  res => console.log(res.data())
)

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

true


Работа с сообщениями


МетодОписание метода
im.message.add Отправка сообщения в чат.
im.message.update Отправка изменения сообщения чат-бота.
im.message.delete Удаление сообщения чат-бота.
im.message.like Установка «Мне нравится».

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

Методы, указанные с использованием javascript-метода BX24.callMethod:

МетодОписание метода
im.message.command Использование команды бота.
im.message.share Создание новых сущностей по сообщению в чате: новый чат, задача, пост в Новостях, событие в календаре.


im.message.add

Отправка сообщения в чат

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat13
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
18
MESSAGE Текст сообщения Да Текст сообщения 18
SYSTEM N Нет Отображать сообщения в виде системного сообщения или нет, необязательное поле, по умолчанию 'N' 18
ATTACH Нет Вложение 18
URL_PREVIEW Y Нет Преобразовывать ссылки в rich-ссылки, необязательное поле, по умолчанию 'Y' 18
KEYBOARD Нет Клавиатура 18
MENU Нет Контекстное меню 18


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

PHP

$result = restCommand('im.message.add', Array(

    'DIALOG_ID' => 'chat13',
    'MESSAGE' => 'Текст сообщения',
    'SYSTEM' => 'N',
    'ATTACH' => '',
    'URL_PREVIEW' => 'Y',
    'KEYBOARD' => '',
    'MENU' => '',

), $_REQUEST["auth"]);

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

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



Пример ответа при возникновении ошибки

{
    "error": "USER_ID_EMPTY",
    "error_description": "Идентификатор получателя не задан в случае отправки сообщения в чат один-на-один"
}

Описание ключей:

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

Код Описание
USER_ID_EMPTY Идентификатор получателя не задан в случае отправки сообщения в чат один-на-один
CHAT_ID_EMPTY Идентификатор чата получателя не задан в случае отправки сообщения в чат
ACCESS_ERROR Недостаточно прав для отправки сообщения
MESSAGE_EMPTY Не передан текст сообщения
ATTACH_ERROR Весь переданный объект вложения не прошел валидацию
ATTACH_OVERSIZE Превышен максимально допустимый размер вложения (30 Кб)
KEYBOARD_ERROR Весь переданный объект клавиатуры не прошел валидацию
KEYBOARD_OVERSIZE Превышен максимально допустимый размер клавиатуры (30 Кб)
MENU_ERROR Весь переданный объект меню не прошел валидацию
MENU_OVERSIZE Превышен максимально допустимый размер меню (30 Кб)
PARAMS_ERROR Что-то пошло не так


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

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

im.message.update

Отправка изменения сообщения чат-бота

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
MESSAGE_ID 1 Да Идентификатор сообщения 18
MESSAGE Текст сообщения Нет Текст сообщения. Если передать пустое значение, то сообщение будет удалено 18
ATTACH Нет Вложение 18
URL_PREVIEW Y Нет Преобразовывать ссылки в rich-ссылки 18
KEYBOARD Нет Клавиатура 18
MENU Нет Контекстное меню 18

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

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



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

PHP

$result = restCommand('im.message.update', Array(

    'MESSAGE_ID' => 1,
    'MESSAGE' => 'Текст сообщения',
    'ATTACH' => '',
    'URL_PREVIEW' => 'Y',
    'KEYBOARD' => '',
    'MENU' => '',

), $_REQUEST["auth"]);

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

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



Пример ответа при возникновении ошибки

{
    "error": "MESSAGE_ID_ERROR",
    "error_description": "Не передан идентификатор сообщения"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Не передан идентификатор сообщения
CANT_EDIT_MESSAGE У вас нет доступа к этому сообщению или время на его модификацию истекло (после публикации прошло более 3-х суток)
ATTACH_ERROR Весь переданный объект вложения не прошел валидацию
ATTACH_OVERSIZE Превышен максимально допустимый размер вложения (30 Кб)
KEYBOARD_ERROR Весь переданный объект клавиатуры не прошел валидацию
KEYBOARD_OVERSIZE Превышен максимально допустимый размер клавиатуры (30 Кб)
MENU_ERROR Весь переданный объект меню не прошел валидацию
MENU_OVERSIZE Превышен максимально допустимый размер меню (30 Кб)


im.message.delete

Удаление сообщения чат-бота

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
MESSAGE_ID 1 Да Идентификатор сообщения 18


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

PHP

$result = restCommand('im.message.delete', Array(

    'MESSAGE_ID' => 1,

), $_REQUEST["auth"]);

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

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



Пример ответа при возникновении ошибки

{
    "error": "MESSAGE_ID_ERROR",
    "error_description": "Не передан идентификатор сообщения"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Не передан идентификатор сообщения
CANT_EDIT_MESSAGE У вас нет доступа к этому сообщению


im.message.like

Установка «Мне нравится»

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
MESSAGE_ID 1 Да Идентификатор сообщения (любое сообщение, отправленное в личных диалогах или в групповых чатах, где присутствует чат-бот) 18
ACTION auto Нет Действие, связанное с методом: plus - поставит метку «Мне нравится»; minus - снимет метку «Мне нравится»; auto - автоматически вычислит, нужно поставить или снять метку. Если не указывать, будет работать в режиме auto 18


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

PHP

$result = restCommand('im.message.like', Array(

    'MESSAGE_ID' => 1,
    'ACTION' => 'auto',

), $_REQUEST["auth"]);

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

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



Пример ответа при возникновении ошибки

{
    "error": "MESSAGE_ID_ERROR",
    "error_description": "Не передан идентификатор сообщения"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Не передан идентификатор сообщения
WITHOUT_CHANGES После вызова состоянии статуса «Мне нравится» не изменилось


im.message.command

Использование команды бота

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
MESSAGE_ID 278 Да Идентификатор сообщения с возможностью отдать команду боту 30
BOT_ID 1 Да Идентификатор бота в чате 30
COMMAND 'KEYBOARD' Да Команда, которую должен выполнить бот 30
COMMAND_PARAMS 'stop' Да Параметры команды 30

Необходимо передавать сообщение, в котором есть выбор команд бота.


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

JavaScript

B24.callMethod(
  'im.message.command',
  {
    MESSAGE_ID: 278,
    BOT_ID: 1,
    COMMAND: 'KEYBOARD',
    COMMAND_PARAMS: 'stop'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

true

Пример ответа при возникновении ошибки

{
  "error":"PARAMS_ERROR",
  "error_description":"Incorrect params"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Параметр MESSAGE_ID не задан или не является числом
BOT_ID_ERROR Параметр BOT_ID не задан или не является числом
COMMAND_ERROR Параметр COMMAND не задан
PARAMS_ERROR Параметр COMMAND_PARAMS не задан или не соответствует параметру команды бота


im.message.share

Создание новых сущностей по сообщению в чате: новый чат, задача, пост в Новостях, событие в календаре

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
MESSAGE_ID 289 Да Идентификатор сообщения, по которому будет создана новая сущность 30
DIALOG_ID 'chat74' Да Идентификатор диалога. Формат:
  • chatXXX – чат получателя, если сообщение для чата
  • или
  • XXX – идентификатор получателя, если сообщение для приватного диалога
30
TYPE 'TASK' Да Тип создаваемой сущности:
  • 'CHAT' – по сообщению будет создан новый чат
  • 'TASK' – по сообщению будет создана задача
  • 'POST' – по сообщению будет создан пост в Новостях
  • 'CALEND' – по сообщению будет создано событие в календаре
30

Необходимо передавать сообщение, в котором есть выбор команд бота.


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

JavaScript

B24.callMethod(
  'im.message.share',
  {
    MESSAGE_ID: 289,
    DIALOG_ID: 'chat74',
    TYPE: 'CHAT',
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

true

Пример ответа при возникновении ошибки

{
  "error":"PARAMS_ERROR",
  "error_description":"Incorrect params"
}

Описание ключей:

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

Код Описание
MESSAGE_ID_ERROR Параметр MESSAGE_ID не задан или не является числом
DIALOG_ID_EMPTY Параметр DIALOG_ID не задан или не соответствует формату
ACCESS_ERROR Текущий пользователь не имеет прав доступа к чату или диалогу
PARAMS_ERROR Параметр TYPE не задан или не соответвует имеющимся


Работа с файлами

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


МетодОписание метода
im.disk.folder.get Получение информации о папке хранения файлов для чата.
im.disk.file.commit Публикация загруженного файла в чат.
im.disk.file.delete Удаление файлов внутри папки чата.
im.disk.file.save Сохранение файла в свой Битрикс24.Диск.


im.disk.folder.get

Получение информации о папке хранения файлов для чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 17 Да Идентификатор чата 18


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

JavaScript

BX24.callMethod('im.disk.folder.get', {
	'CHAT_ID': 17,
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.disk.folder.get', Array(
	'CHAT_ID' => 17,
), $_REQUEST["auth"]);

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

{
	"result": {
		ID: 127
	}
}   


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу
INTERNAL_ERROR Ошибка сервера, обратитесь в техническую поддержку


im.disk.file.commit

Публикация загруженного файла в чат

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 17 Да Идентификатор чата 18
UPLOAD_ID 213 Да* Идентификатор загруженного файла через методы модуля DISK 18
DISK_ID 112 Да* Идентификатор файла, доступного из локального диска 18
MESSAGE Важный документ Нет Описание файла будет опубликовано в чате 18
SILENT_MODE N Нет Параметр для чата Открытых линий, обозначает, будет ли отправлена информация о файле клиенту или нет 18

Обратите внимание! Файл должен быть предварительно загружен через метод disk.folder.uploadfile.



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

JavaScript

BX24.callMethod('im.disk.file.commit', {
	'CHAT_ID': 17,
	'UPLOAD_ID': 112,
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.disk.file.commit', Array(
	'CHAT_ID' => 17,
	'UPLOAD_ID' => 112,
), $_REQUEST["auth"]);

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

{
	"result": true
} 


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу
FILES_ERROR Не переданы идентификатор файлов


im.disk.file.delete

Удаление файлов внутри папки чата

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 17 Да Идентификатор чата 18
DISK_ID 112 Да Идентификатор файла 18


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

JavaScript

BX24.callMethod('im.disk.file.delete', {
	'CHAT_ID': 17,
	'DISK_ID': 112,
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.disk.file.delete', Array(
	'CHAT_ID' => 17,
	'DISK_ID' => 112,
), $_REQUEST["auth"]);

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

{
	"result": true
} 


Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата
FILE_ID_EMPTY Не передан идентификатор файла


im.disk.file.save

Сохранение файла в свой Битрикс24.Диск

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DISK_ID 112 Да Идентификатор файла 21


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

JavaScript

BX24.callMethod('im.disk.file.save', {
  'DISK_ID': 112,
}, function(result){
  if(result.error())
  {
    console.error(result.error().ex);
  }
  else
  {
    console.log(result.data());
  }
});

PHP

$result = restCommand('im.disk.file.save', Array(
  'DISK_ID' => 112,
), $_REQUEST["auth"]);

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

{
  "result": {
    "folder": {"id": 130, "name": "Сохраненные файлы"},
    "file": {"id": 578, "name": "image.png"}
  }
}


Пример ответа при возникновении ошибки

{
  "error": "FILE_ID_EMPTY",
  "error_description": "File ID can't be empty"
}

Описание ключей:

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

Код Описание
FILE_SAVE_ERROR Файл не удалось сохранить
FILE_ID_EMPTY Не передан идентификатор файла


Работа с пользователями

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


МетодОписание метода
im.user.get Получение данных о пользователе.
im.user.list.get Получение данных о пользователях.
im.user.status.get Получение информации об установленном статусе пользователя.
im.user.status.set Установка статуса пользователя.
im.user.status.idle.start Установка автоматического статуса «Отошел».
im.user.status.idle.end Отключение автоматического статуса «Отошел».


im.user.get

Получение данных о пользователе

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
ID 5 Нет Идентификатор пользователя 18
AVATAR_HR N Нет Генерировать аватар в высоком разрешении 18


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

JavaScript

BX24.callMethod('im.user.get', {ID: 5}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.get', Array(
	'ID' => 5,
), $_REQUEST["auth"]);	

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

{
	"result": {
		"id": 5,
		"name": "Евгений Шеленков",
		"first_name": "Евгений",
		"last_name": "Шеленков",
		"work_position": "",
		"color": "#df532d",
		"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
		"gender": "M",
		"birthday": "",
		"extranet": false,
		"network": false,
		"bot": false,
		"connector": false,
		"external_auth_id": "default",
		"status": "online",
		"idle": false,
		"last_activity_date": "2018-01-29T17:35:31+03:00",
		"desktop_last_date": false,
		"mobile_last_date": false,
		"departments": [
		  50
		],
		"absent": false,
		"phones": {
		  "work_phone": "",
		  "personal_mobile": "",
		  "personal_phone": ""
		}
	}
}   

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "ID_EMPTY",
    "error_description": "User ID can't be empty"
}

Описание ключей:

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

Код Описание
ID_EMPTY Не передан идентификатор пользователя
USER_NOT_EXISTS Пользователь с указанным идентификатором не найден
ACCESS_DENIED Текущий пользователь не имеет прав доступа к данным


im.user.list.get

Получение данных о пользователях

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
ID [4,5] Да Идентификаторы пользователей 19
AVATAR_HR N Нет Генерировать аватар в высоком разрешении 19


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

JavaScript

BX24.callMethod('im.user.list.get', {ID: [4,5]}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.list.get', Array(
	'ID' => [4,5],
), $_REQUEST["auth"]);	

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

{
	"result": {
		4: null,
		5: {
			"id": 5,
			"name": "Евгений Шеленков",
			"first_name": "Евгений",
			"last_name": "Шеленков",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"desktop_last_date": false,
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false,
			"phones": {
			  "work_phone": "",
			  "personal_mobile": "",
			  "personal_phone": ""
			}
		}
	}
} 

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "INVALID_FORMAT",
    "error_description": "A wrong format for the ID field is passed"
}

Описание ключей:

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

Код Описание
INVALID_FORMAT Не передан идентификатор пользователя


im.user.status.get

Получение информации об установленном статусе пользователя

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

Параметры

Нет

Вызов метода

JavaScript

BX24.callMethod('im.user.status.get', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.status.get', Array(
), $_REQUEST["auth"]);

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

{
	"result": "dnd"
}

Описание результата:


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



im.user.status.set

Установка статуса пользователя

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
STATUS online Да Новый статус пользователя 18

Доступны следующие статусы:



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

JavaScript

BX24.callMethod('im.user.status.set', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.status.set', Array(
), $_REQUEST["auth"]);

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

{
  "result": true
}


im.user.status.idle.start

Установка автоматического статуса «Отошел»

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
AGO 10 Нет Сколько минут назад отошел 18


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

JavaScript

BX24.callMethod('im.user.status.idle.start', {
	'AGO': 10
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.status.idle.start', Array(
	'AGO' => 10
), $_REQUEST["auth"]);

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

{
  "result": true
}


im.user.status.idle.end

Отключение автоматического статуса «Отошел»

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

Параметры

Нет

Вызов метода

JavaScript

BX24.callMethod('im.user.status.idle.end', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.status.idle.start', Array(
), $_REQUEST["auth"]);	

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

{
  "result": true
}

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



Работа с подразделениями

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

Примечание: Методы im.department.* доступны только для [ds]интранет-пользователей[/ds][di] В Битрикс24 различают два вида пользователей:

интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);

экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).

Подробнее о возможностях интранет и экстранет пользователей...[/di].


МетодОписание метода
im.department.get Получение данных о подразделении.
im.department.colleagues.list Получение списка пользователей, состоящих в вашем отделе.
im.department.managers.get Получение списка руководителей подразделений.
im.department.employees.get Получение списка сотрудников в подразделении.


im.department.get

Получение данных о подразделении

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Примечание: Метод im.department.get доступен только для [ds]интранет-пользователей[/ds][di] В Битрикс24 различают два вида пользователей:

интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);

экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).

Подробнее о возможностях интранет и экстранет пользователей...[/di].

Параметры

Параметр Пример Обязат. Описание Ревизия
ID [51] Да Идентификаторы подразделений 18
USER_DATA N Нет Подгружать данные о пользователях 18


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

JavaScript

BX24.callMethod('im.department.get', {ID: [51]}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.department.get', Array(
	'ID' => [51],
), $_REQUEST["auth"]);	

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

{
	"result": [
		{
			"id": 51,
			"name": "Московский филиал",
			"full_name": "Московский филиал / Битрикс"
			"manager_user_id": 11,
		}
	]
}    

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "INVALID_FORMAT",
    "error_description": "A wrong format for the ID field is passed"
}

Описание ключей:

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

Код Описание
INVALID_FORMAT Передан некорректный формат идентификаторов


im.department.colleagues.list

Получение списка пользователей, состоящих в вашем отделе

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Примечание: Метод im.department.colleagues.list доступен только для [ds]интранет-пользователей[/ds][di] В Битрикс24 различают два вида пользователей:

интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);

экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).

Подробнее о возможностях интранет и экстранет пользователей...[/di].

Параметры

Параметр Пример Обязат. Описание Ревизия
USER_DATA N Нет Подгружать данные о пользователях 19
OFFSET 0 Нет Смещение выборки пользователей 19
LIMIT 10 Нет Лимит выборки пользователей 19


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

JavaScript

BX24.callMethod('im.department.colleagues.list', {USER_DATA: 'Y'}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
		console.log('total', result.total());
	}
});

PHP

$result = restCommand('im.department.colleagues.list', Array(
	'USER_DATA' => 'Y'
), $_REQUEST["auth"]);	

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

При опции USER_DATA = N:

{
	"result": [1],
	"total": 1
}    

При опции USER_DATA = Y:

{    
	"result": [
		{
			"id": 1,
			"name": "Евгений Шеленков",
			"first_name": "Евгений",
			"last_name": "Шеленков",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"desktop_last_date": false,
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false,
			"phones": {
			  "work_phone": "",
			  "personal_mobile": "",
			  "personal_phone": ""
			}
		}
	],
	"total": 1
}     

Описание ключей:



im.department.managers.get

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Примечание: Метод im.department.managers.get доступен только для [ds]интранет-пользователей[/ds][di] В Битрикс24 различают два вида пользователей:

интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);

экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).

Подробнее о возможностях интранет и экстранет пользователей...[/di].

Параметры

Параметр Пример Обязат. Описание Ревизия
ID [105] Да Идентификаторы подразделений 19
USER_DATA N Нет Подгружать данные о пользователях 19


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

JavaScript

BX24.callMethod('im.department.managers.get', {USER_DATA: 'Y'}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
	}
});

PHP

$result = restCommand('im.department.managers.get', Array(
	'USER_DATA' => 'Y'
), $_REQUEST["auth"]);

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

При опции USER_DATA = N:

{
	"result": {
		105: [1]
	},
}    

При опции USER_DATA = Y:

{    
	"result": {
		105: {
			"id": 1,
			"name": "Евгений Шеленков",
			"first_name": "Евгений",
			"last_name": "Шеленков",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"desktop_last_date": false,
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false,
			"phones": {
			  "work_phone": "",
			  "personal_mobile": "",
			  "personal_phone": ""
			}
		}
	}
}       

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "ID_EMPTY",
    "error_description": "Department ID can't be empty"
}

Описание ключей:

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

Код Описание
ID_EMPTY Не передан список идентификаторов


im.department.employees.get

Получение списка сотрудников в подразделении

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Примечание: Метод im.department.employees.get доступен только для [ds]интранет-пользователей[/ds][di] В Битрикс24 различают два вида пользователей:

интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);

экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).

Подробнее о возможностях интранет и экстранет пользователей...[/di].

Параметры

Параметр Пример Обязат. Описание Ревизия
ID [105] Да Идентификаторы подразделений 19
USER_DATA N Нет Подгружать данные о пользователях 19


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

JavaScript

BX24.callMethod('im.department.employees.get', {USER_DATA: 'Y'}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
	}
});

PHP

$result = restCommand('im.department.employees.get', Array(
	'USER_DATA' => 'Y'
), $_REQUEST["auth"]);	

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

При опции USER_DATA = N:

{
	"result": {
		105: [1]
	}
}    

При опции USER_DATA = Y:

{    
	"result": {
		105: {
			"id": 1,
			"name": "Евгений Шеленков",
			"first_name": "Евгений",
			"last_name": "Шеленков",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"desktop_last_date": false,
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false,
			"phones": {
			  "work_phone": "",
			  "personal_mobile": "",
			  "personal_phone": ""
			}
		}
	}
}       

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "ID_EMPTY",
    "error_description": "Department ID can't be empty"
}

Описание ключей:

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

Код Описание
ID_EMPTY Не передан список идентификаторов


Работа с поиском

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


МетодОписание метода
im.search.user.list Поиск пользователей.
im.search.chat.list Поиск чатов.
im.search.department.list Поиск подразделений.
im.search.last.get Получение списка элементов последнего поиска.
im.search.last.add Добавление элемента истории последнего поиска.
im.search.last.delete Удаление элемента истории последнего поиска.


im.search.user.list

Поиск пользователей

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
FIND Евгений Да Поисковая фраза 19
BUSINESS N Нет Поиск среди бизнес пользователей 19
AVATAR_HR N Нет Генировать аватар в высоком разрешении 19
OFFSET 0 Нет Смещение выборки пользователей 19
LIMIT 10 Нет Лимит выборки пользователей 19


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

JavaScript

BX24.callMethod('im.search.user.list', {
	FIND: 'Евгений'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
		console.log('total', result.total());
	}
});

PHP

$result = restCommand('im.search.user.list', Array(
	'FIND' => 'Евгений'
), $_REQUEST["auth"]);	

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

{    
	"result": {
		1: {
			"id": 1,
			"name": "Евгений Шеленков",
			"first_name": "Евгений",
			"last_name": "Шеленков",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"desktop_last_date": false,
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false
		}
	},
	"total": 1
}      

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "FIND_SHORT",
    "error_description": "Too short a search phrase."
}

Описание ключей:

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

Код Описание
FIND_SHORT Слишком короткая поисковая фраза, поиск осуществляется от трех символов.


im.search.chat.list

Поиск чатов

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
FIND Мятный Да Поисковая фраза 19
OFFSET 0 Нет Смещение выборки пользователей 19
LIMIT 10 Нет Лимит выборки пользователей 19


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

JavaScript

BX24.callMethod('im.search.chat.list', {
	FIND: 'Мятный'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
		console.log('total', result.total());
	}
});

PHP

$result = restCommand('im.search.chat.list', Array(
	'FIND' => 'Мятный'
), $_REQUEST["auth"]);

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

{    
	"result": {
		21191:  {
			"id": 21191,
			"title": "Мятный чат №3",
			"owner": 2,
			"extranet": false,
			"avatar": "",
			"color": "#4ba984",
			"type": "chat",
			"entity_type": "",
			"entity_data_1": "",
			"entity_data_2": "",
			"entity_data_3": "",
			"date_create": "2017-10-14T12:15:32+02:00",
			"message_type": "C"
		}
	},
	"total": 1
}    

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "FIND_SHORT",
    "error_description": "Too short a search phrase."
}

Описание ключей:

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

Код Описание
FIND_SHORT Слишком короткая поисковая фраза, поиск осуществляется от трех символов.


im.search.department.list

Поиск подразделений

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
FIND Московский Да Поисковая фраза 19
USER_DATA N Нет Подгружать данные о пользователях 19
OFFSET 0 Нет Смещение выборки пользователей 19
LIMIT 10 Нет Лимит выборки пользователей 19


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

JavaScript

BX24.callMethod('im.search.department.list', {
	FIND: 'Московский'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log('users', result.data());
		console.log('total', result.total());
	}
});

PHP

$result = restCommand('im.search.department.list', Array(
	'FIND' => 'Московский'
), $_REQUEST["auth"]);	

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

{    
	"result": [
		{
			id: 51,
			name: "Московский филиал",
			full_name: "Московский филиал / Битрикс",
			manager_user_id: 11
		}
	],
	"total": 1
}             

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "FIND_SHORT",
    "error_description": "Too short a search phrase."
}

Описание ключей:

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

Код Описание
FIND_SHORT Слишком короткая поисковая фраза, поиск осуществляется от трех символов.


im.search.last.get

Получение списка элементов последнего поиска

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
SKIP_OPENLINES N Нет Пропускать чаты открытых линий 18
SKIP_CHAT N Нет Пропускать чаты 18
SKIP_DIALOG N Нет Пропускать диалоги один-на-один 18


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

JavaScript

BX24.callMethod('im.search.last.get', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.business.list', Array(
), $_REQUEST["auth"]);	
{    
	"result": [
		{
			"id": 1,
			"type": "user",
			"title": "Евгений Шеленков",
			"avatar": {
				"url": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
				"color": "#df532d"
			}
			"user": {
				"id": 1,
				"name": "Евгений Шеленков",
				"first_name": "Евгений",
				"last_name": "Шеленков",
				"work_position": "",
				"color": "#df532d",
				"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/shelenkov.png",
				"gender": "M",
				"birthday": "",
				"extranet": false,
				"network": false,
				"bot": false,
				"connector": false,
				"external_auth_id": "default",
				"status": "online",
				"idle": false,
				"last_activity_date": "2018-01-29T17:35:31+03:00",
				"desktop_last_date": false,
				"mobile_last_date": false,
				"departments": [
				  50
				],
				"absent": false,
				"phones": {
				  "work_phone": "",
				  "personal_mobile": "",
				  "personal_phone": ""
				}
			}
		}
	]
}              

Описание ключей:



im.search.last.add

Добавление элемента истории последнего поиска

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat17
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
18


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

JavaScript

BX24.callMethod('im.search.last.add', {
	'DIALOG_ID': 'chat17'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.search.last.add', Array(
	'DIALOG_ID' => 'chat17'
), $_REQUEST["auth"]);	

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

{
	"result": true
}          


Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога.


im.search.last.delete

Удаление элемента истории последнего поиска

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat17
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
18


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

JavaScript

BX24.callMethod('im.search.last.delete', {
	'DIALOG_ID': 'chat17'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.search.last.delete', Array(
	'DIALOG_ID' => 'chat17'
), $_REQUEST["auth"]);

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

{
	"result": true
}        


Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога.


Работа со списком последних чатов


МетодОписание метода
im.recent.get Список последних диалогов пользователя.
im.recent.pin Закрепление диалога в избранном.
im.recent.hide Удаление диалога из списка последних чатов.

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

Методы, указанные с использованием javascript-метода BX24.callMethod:

МетодОписание метода
im.recent.unread Установка метки «не прочитан» на чат или диалог.
im.recent.list Получение списка последних диалогов пользователя (с поддержкой пагинации).


im.recent.get

Список последних диалогов пользователя

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
SKIP_OPENLINES N Нет Пропускать чаты открытых линий 18
SKIP_CHAT N Нет Пропускать чаты 18
SKIP_DIALOG N Нет Пропускать диалоги один-на-один 18
LAST_UPDATE 2019-07-11T10:45:31+02:00 Нет Ограничение выборки для минимизации переданных данных, дата в формате ATOM 23
ONLY_OPENLINES N Нет Выборка только чатов открытых линий 29
LAST_SYNC_DATE 2019-07-11T10:45:31+02:00 Нет Дата предыдущей выборки для загрузки изменений, произошедших в списке с этого времени. Выборка возвращает данные не старше 7 дней. Дата в формате ATOM 29


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

JavaScript

BX24.callMethod('im.recent.get', {
	'SKIP_OPENLINES': 'Y'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.user.status.idle.start', Array(
	'SKIP_OPENLINES' => 'Y'
), $_REQUEST["auth"]);

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

{
	"result": [
		{
			"id": "1",
		 	"type": "user",
		 	"avatar": {
				"url": "http://www.hazz/upload/resize_cache/main/1af/100_100_2/1464255149.png",
				"color": "#df532d"
		  	},
			"title": "Евгений Шеленков",
			"message": {
				"id": "30468",
				"text": "1",
				"file": false,
				"attach": false,
				"author_id": "1"
			},
			"counter": "3",
			"date": "2017-10-17T11:12:56+02:00",
			"user": {
				"id": "1",
				"name": "Евгений Шеленков",
				"first_name": "Евгений",
				"last_name": "Шеленков",
				"work_position": "ИТ-специалист",
				"color": "#df532d",
				"avatar": "http://www.hazz/upload/resize_cache/main/1af/100_100_2/1464255149.png",
				"gender": "M",
				"birthday": false,
				"extranet": false,
				"network": false,
				"bot": false,
				"connector": false,
				"external_auth_id": "default",
				"status": "online",
				"idle": false,
				"last_activity_date": "2017-10-17T11:16:01+02:00",
				"mobile_last_date": "2017-05-26T12:04:58+02:00",
				"absent": "2017-11-01T00:00:00+02:00"
			}
		},
		{
			"id": "chat21191",
			"type": "chat",
			"avatar": {
				"url": "",
				"color": "#4ba984"
			},
			"title": "Мятный чат №3",
			"message": {
				"id": "30467",
				"text": "Разрешение на обновление Битрикс24 получено от [Вложение]",
				"file": false,
				"attach": true,
				"author_id": "2"
			},
			"counter": "0",
			"date": "2017-10-17T10:38:20+02:00",
			"chat": {
				"id": "21191",
				"title": "Мятный чат №3",
				"owner": "2",
				"extranet": false,
				"avatar": "",
				"color": "#4ba984",
				"type": "chat",
				"entity_type": "",
				"entity_data_1": "",
				"entity_data_2": "",
				"entity_data_3": "",
				"date_create": "2017-10-14T12:15:32+02:00",
				"message_type": "C"
			}
		}
	]
}       

Описание ключей:



im.recent.pin

Закрепление диалога в избранном

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat17
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
19
PIN Y Нет Закрепить или открепить диалог 19


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

JavaScript

BX24.callMethod('im.recent.pin', {
	'DIALOG_ID': 'chat17'
	'PIN': 'Y'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.recent.pin', Array(
	'DIALOG_ID' => 'chat17',
	'PIN' => 'Y'
), $_REQUEST["auth"]);	

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

{
	"result": true
}      


Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:


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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога.


im.recent.hide

Удаление диалога из списка последних чатов

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID chat17
или
256
Да Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
18


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

JavaScript

BX24.callMethod('im.recent.hide', {
	'DIALOG_ID': 'chat17'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.recent.hide', Array(
	'DIALOG_ID' => 'chat17'
), $_REQUEST["auth"]);	

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

{
	"result": true
}  


Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:


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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога.


im.recent.unread

Установка метки «не прочитан» на чат или диалог

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
DIALOG_ID 'chat74' Да Идентификатор диалога. Формат:
  • chatXXX – чат получателя, если сообщение для чата
  • или
  • XXX – идентификатор получателя, если сообщение для приватного диалога
30
ACTION 'Y' Нет Поставить|снять метку «не прочитан» на диалог - 'Y'|'N' 30


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

JavaScript

B24.callMethod(
  'im.recent.unread',
  {
    DIALOG_ID: 'chat74',
    ACTION: 'Y'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

true //если удалось поставить|снять метку

Пример ответа при возникновении ошибки

{
  "error":"DIALOG_ID_EMPTY",
  "error_description":"Dialog ID can\u0027t be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан параметр DIALOG_ID или он не соответствует формату


im.recent.list

Получение списка последних диалогов пользователя (с поддержкой пагинации)

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
SKIP_OPENLINES 'Y' Нет Пропускать чаты открытых линий 30
SKIP_DIALOG 'N' Нет Пропускать диалоги "один на один" 30
SKIP_CHAT 'Y' Нет Пропускать чаты 30
LAST_MESSAGE_DATE '2021-10-30' Нет Дата из последнего элемента предыдущей выборки 30


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

JavaScript

B24.callMethod(
  'im.recent.list',
  {
    LAST_MESSAGE_DATE: '2021-10-30'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

{
  "items": [
    {
      "id": "chat71",
      "chat_id": 71,
      "type": "chat",
      "avatar": {
        "url": "",
        "color": "#8474c8"
      },
      "title": "Фиолетовый гость №3 - Открытая линия 2",
      "message": {
        "id": 267,
        "text": "Отправлена форма \"Форма контактных данных для открытых линий\" [Вложение]",
        "file": false,
        "author_id": 0,
        "attach": true,
        "date": "2021-10-27T18:20:45+02:00",
        "status": "received"
      },
      "counter": 3,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-27T18:20:45+02:00",
      "chat": {
        "id": 71,
        "name": "Фиолетовый гость №3 - Открытая линия 2",
        "owner": 0,
        "extranet": false,
        "avatar": "",
        "color": "#8474c8",
        "type": "lines",
        "entity_type": "LINES",
        "entity_id": "livechat|2|70|2016",
        "entity_data_1": "N|NONE|0|N|N|7|1635351612|0|0|0",
        "entity_data_2": "",
        "entity_data_3": "",
        "mute_list": [],
        "manager_list": [],
        "date_create": "2021-10-27T18:20:12+02:00",
        "message_type": "L"
      },
      "lines": {
        "id": 7,
        "status": 5,
        "date_create": "2021-10-27T18:20:12+02:00"
      },
      "user": {
        "id": 0
      },
      "options": []
    },
    {
      "id": "chat69",
      "chat_id": 69,
      "type": "chat",
      "avatar": {
        "url": "",
        "color": "#3e99ce"
      },
      "title": "Синий гость №3 - Открытая линия 2",
      "message": {
        "id": 258,
        "text": "Отправлена форма \"Форма контактных данных для открытых линий\" [Вложение]",
        "file": false,
        "author_id": 0,
        "attach": true,
        "date": "2021-10-27T18:16:22+02:00",
        "status": "received"
      },
      "counter": 3,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-27T18:16:22+02:00",
      "chat": {
        "id": 69,
        "name": "Синий гость №3 - Открытая линия 2",
        "owner": 0,
        "extranet": false,
        "avatar": "",
        "color": "#3e99ce",
        "type": "lines",
        "entity_type": "LINES",
        "entity_id": "livechat|2|68|2015",
        "entity_data_1": "N|NONE|0|N|N|6|1635351343|0|0|0",
        "entity_data_2": "",
        "entity_data_3": "",
        "mute_list": [],
        "manager_list": [],
        "date_create": "2021-10-27T18:15:43+02:00",
        "message_type": "L"
      },
      "lines": {
        "id": 6,
        "status": 5,
        "date_create": "2021-10-27T18:15:43+02:00"
      },
      "user": {
        "id": 0
      },
      "options": []
    },
    {
      "id": "chat67",
      "chat_id": 67,
      "type": "chat",
      "avatar": {
        "url": "",
        "color": "#29619b"
      },
      "title": "Лазурный гость №2 - Открытая линия 2",
      "message": {
        "id": 250,
        "text": "hi",
        "file": false,
        "author_id": 2014,
        "attach": false,
        "date": "2021-10-27T17:11:36+02:00",
        "status": "received"
      },
      "counter": 5,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-27T17:11:36+02:00",
      "chat": {
        "id": 67,
        "name": "Лазурный гость №2 - Открытая линия 2",
        "owner": 0,
        "extranet": false,
        "avatar": "",
        "color": "#29619b",
        "type": "lines",
        "entity_type": "LINES",
        "entity_id": "livechat|2|66|2014",
        "entity_data_1": "N|NONE|0|N|N|5|1635346774|0|0|0",
        "entity_data_2": "",
        "entity_data_3": "",
        "mute_list": [],
        "manager_list": [],
        "date_create": "2021-10-27T16:59:34+02:00",
        "message_type": "L"
      },
      "lines": {
        "id": 5,
        "status": 5,
        "date_create": "2021-10-27T16:59:34+02:00"
      },
      "user": {
        "id": 2014,
        "active": true,
        "name": "Гость",
        "first_name": "Гость",
        "last_name": "",
        "work_position": "",
        "color": "#4ba5c3",
        "avatar": "",
        "gender": "M",
        "birthday": "",
        "extranet": true,
        "network": false,
        "bot": false,
        "connector": true,
        "external_auth_id": "imconnector",
        "status": "online",
        "idle": false,
        "last_activity_date": "2021-10-27T17:11:36+02:00",
        "mobile_last_date": false,
        "absent": false,
        "departments": [],
        "phones": false,
        "desktop_last_date": false
      },
      "options": []
    },
    {
      "id": "chat65",
      "chat_id": 65,
      "type": "chat",
      "avatar": {
        "url": "",
        "color": "#df532d"
      },
      "title": "Максим Тестер - Открытая линия 2",
      "message": {
        "id": 225,
        "text": "Создана новая сделка [Вложение]",
        "file": false,
        "author_id": 0,
        "attach": true,
        "date": "2021-10-25T14:48:28+02:00",
        "status": "received"
      },
      "counter": 6,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-25T14:48:28+02:00",
      "chat": {
        "id": 65,
        "name": "Максим Тестер - Открытая линия 2",
        "owner": 0,
        "extranet": false,
        "avatar": "",
        "color": "#df532d",
        "type": "lines",
        "entity_type": "LINES",
        "entity_id": "livechat|2|64|2011",
        "entity_data_1": "Y|DEAL|12|N|N|4|1635166080|0|0|0",
        "entity_data_2": "LEAD|0|COMPANY|0|CONTACT|9|DEAL|12",
        "entity_data_3": "",
        "mute_list": [],
        "manager_list": [],
        "date_create": "2021-10-25T14:48:00+02:00",
        "message_type": "L"
      },
      "lines": {
        "id": 4,
        "status": 5,
        "date_create": "2021-10-25T14:48:00+02:00"
      },
      "user": {
        "id": 0
      },
      "options": []
    },
    {
      "id": "chat39",
      "chat_id": 39,
      "type": "chat",
      "avatar": {
        "url": "",
        "color": "#4ba984"
      },
      "title": "Чат не для роботов",
      "message": {
        "id": 161,
        "text": "вот вопрос",
        "file": false,
        "author_id": 1,
        "attach": false,
        "date": "2021-10-08T13:19:33+02:00",
        "status": "delivered"
      },
      "counter": 0,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-08T13:19:33+02:00",
      "chat": {
        "id": 39,
        "name": "Чат не для роботов",
        "owner": 1018,
        "extranet": false,
        "avatar": "",
        "color": "#4ba984",
        "type": "chat",
        "entity_type": "",
        "entity_id": "",
        "entity_data_1": "",
        "entity_data_2": "",
        "entity_data_3": "",
        "mute_list": [],
        "manager_list": [],
        "date_create": "2021-09-27T15:57:53+02:00",
        "message_type": "C"
      },
      "user": {
        "id": 1,
        "active": true,
        "name": "Алексей Шахворостов",
        "first_name": "Алексей",
        "last_name": "Шахворостов",
        "work_position": "",
        "color": "#df532d",
        "avatar": "",
        "gender": "M",
        "birthday": "",
        "extranet": false,
        "network": false,
        "bot": false,
        "connector": false,
        "external_auth_id": "default",
        "status": "online",
        "idle": false,
        "last_activity_date": "2021-10-30T15:52:40+02:00",
        "mobile_last_date": "2021-10-27T16:39:26+02:00",
        "absent": false,
        "departments": [
          1
        ],
        "phones": false,
        "desktop_last_date": "2021-10-21T11:07:54+02:00"
      },
      "options": []
    },
    {
      "id": 1018,
      "chat_id": 28,
      "type": "user",
      "avatar": {
        "url": "",
        "color": "#df532d"
      },
      "title": "Лев Трегубов",
      "message": {
        "id": 160,
        "text": "Пуши приходят",
        "file": false,
        "author_id": 1018,
        "attach": false,
        "date": "2021-10-08T13:19:32+02:00",
        "status": "delivered"
      },
      "counter": 0,
      "pinned": false,
      "unread": false,
      "date_update": "2021-10-08T13:20:59+02:00",
      "user": {
        "id": 1018,
        "active": true,
        "name": "Лев Трегубов",
        "first_name": "Лев",
        "last_name": "Трегубов",
        "work_position": "",
        "color": "#df532d",
        "avatar": "",
        "gender": "M",
        "birthday": "",
        "extranet": false,
        "network": false,
        "bot": false,
        "connector": false,
        "external_auth_id": "default",
        "status": "online",
        "idle": false,
        "last_activity_date": "2021-10-29T16:29:17+02:00",
        "mobile_last_date": "2021-10-08T13:24:22+02:00",
        "absent": false,
        "departments": [
          1
        ],
        "phones": false,
        "desktop_last_date": "2021-10-18T16:51:09+02:00"
      },
      "options": []
    }
  ],
  "hasMore": false
}

Описание ключей:




Работа со счетчиками

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


МетодОписание
im.counters.get Получение счетчиков.


im.counters.get

Получение счетчиков

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

Параметры

Нет

Вызов метода

JavaScript

BX24.callMethod('im.counters.get', {}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.counters.get', Array(
), $_REQUEST["auth"]);	

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

{    
	"result": {
		"CHAT": {18: 1},
		"DIALOG": {1: 3, 5: 1},
		"LINES": {},
		"TYPE" {
			"ALL": 5,
			"CHAT": 1,
			"DIALOG": 4,
			"LINES": 0,
			"NOTIFY": 0
		}
	}
}   

Описание ключей:


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



Работа с уведомлениями


МетодОписание метода
im.notify.personal.add Отправка персонального уведомления.
im.notify.system.add Отправка персонального уведомления.
im.notify.delete Удаление уведомления.
im.notify.read Установка отмены о прочитанных уведомлениях.

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

Методы, указанные с использованием javascript-метода BX24.callMethod:

МетодОписание метода
im.notify.read.list «Прочтение» списка уведомлений, исключая уведомления типа CONFIRM.
im.notify.answer Ответ на уведомление, поддерживающее быстрый ответ.
im.notify.confirm Взаимодействие с кнопками нотификаций.


im.notify.personal.add

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
USER_ID 1 Да Идентификатор пользователя, кому будет адресовано уведомление 18
MESSAGE Персональное уведомление Да Текст уведомления 18
MESSAGE_OUT Текст персонального уведомления для почты Нет Текст уведомления для почты. Если не задано, то используется поле MESSAGE 18
TAG TEST Нет Тег уведомления, уникальный в рамках системы. При добавлении уведомления с существующим тегом другие уведомления будут удалены 18
SUB_TAG SUB|TEST Нет Дополнительный тег, без проверки на уникальность 18
ATTACH Нет Вложение 18

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

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



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

PHP

$result = restCommand('im.notify.personal.add', Array(

   'USER_ID' => 1,
   'MESSAGE' => 'Персональное уведомление',
   'MESSAGE_OUT' => 'Текст персонального уведомления для почты',
   'TAG' => 'TEST',
   'SUB_TAG' => 'SUB|TEST',
   'ATTACH' => ''
  
), $_REQUEST["auth"]);

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

{
	"result": 123
}
Результат выполнения: идентификатор уведомления ID или ошибка.



Пример ответа при возникновении ошибки

{
    "error": "USER_ID_EMPTY",
    "error_description": "Идентификатор получателя не задан"
}

Описание ключей:

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

Код Описание
USER_ID_EMPTY Идентификатор получателя не задан
MESSAGE_EMPTY Не передан текст сообщения
ATTACH_ERROR Весь переданный объект вложения не прошел валидацию
ATTACH_OVERSIZE Превышен максимально допустимый размер вложения (30 Кб)


im.notify.system.add

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

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
USER_ID 1 Да Идентификатор пользователя, кому будет адресовано уведомление 18
MESSAGE Системное уведомление Да Текст уведомления 18
MESSAGE_OUT Текст системного уведомления для почты Нет Текст уведомления для почты. Если не задано, то используется поле MESSAGE 18
TAG TEST Нет Тег уведомления, уникальный в рамках системы. При добавлении уведомления с существующим тегом другие уведомления будут удалены 18
SUB_TAG SUB|TEST Нет Дополнительный тег, без проверки на уникальность 18
ATTACH Array() Нет Вложение 18

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

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



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

PHP

$result = restCommand('im.notify.system.add', Array(

   'USER_ID' => 1,
   'MESSAGE' => 'Системное уведомление',
   'MESSAGE_OUT' => 'Текст системного уведомления для почты',
   'TAG' => 'TEST',
   'SUB_TAG' => 'SUB|TEST',
   'ATTACH' => Array()
  
), $_REQUEST["auth"]);

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

{
	"result": 123
}
Результат выполнения: идентификатор уведомления ID или ошибка.



Пример ответа при возникновении ошибки

{
    "error": "USER_ID_EMPTY",
    "error_description": "Идентификатор получателя не задан"
}

Описание ключей:

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

Код Описание
USER_ID_EMPTY Идентификатор получателя не задан
MESSAGE_EMPTY Не передан текст сообщения
ATTACH_ERROR Весь переданный объект вложения не прошел валидацию
ATTACH_OVERSIZE Превышен максимально допустимый размер вложения (30 Кб)


im.notify.delete

Удаление уведомления

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
ID 123 Да* Идентификатор уведомления 18
TAG TEST Да* Тег уведомления, уникальный в рамках системы. 18
SUB_TAG SUB|TEST Да* Дополнительный тег, без проверки на уникальность 18

* Указывать нужно один из трех обязательных параметров на выбор: ID (идентификатор уведомления), TAG (тег уведомления) или SUB_TAG (дополнительный тег).


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

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



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

PHP

$result = restCommand('im.notify.delete', Array(

    'ID' => 13,
    'TAG' => 'TEST',
    'SUB_TAG' => 'SUB|TEST'

), $_REQUEST["auth"]);

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

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



Пример ответа при возникновении ошибки

{
    "error": "PARAMS_ERROR",
    "error_description": "Ошибка удаления уведомления"
}

Описание ключей:

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

Код Описание
PARAMS_ERROR Ошибка удаления уведомления


im.notify.read

Установка отмены о прочитанных уведомлениях

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18

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

Параметры

Параметр Пример Обязат. Описание Ревизия
ID 17 Да Идентификатор уведомления 18
ONLY_CURRENT N Нет Прочитать только указанное уведомление 18


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

JavaScript

BX24.callMethod('im.notify.read', {
	'ID': 17,
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.notify.read', Array(
	'ID' => '17'
), $_REQUEST["auth"]);	

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

{
	"result": true
}        


im.notify.read.list

«Прочтение» списка уведомлений, исключая уведомления типа CONFIRM

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
IDS [1,2,3] Да Массив идентификаторов уведомлений 30
ACTION 'Y' Нет Отметить, как прочитанные|непрочитанные (Y|N) 30


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

JavaScript

B24.callMethod(
  'im.notify.read.list',
  {
    IDS: [1,2,3],
    ACTION: 'Y'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }

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

true

Пример ответа при возникновении ошибки

{
  "error": "PARAMS_ERROR",
  "error_description": "No IDS param or it is not an array"
}

Описание ключей:

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

Код Описание
PARAMS_ERROR Не передан параметр IDS или он не является массивом


im.notify.answer

Ответ на уведомление, поддерживающее быстрый ответ

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
ID 270 Да Идентификатор уведомления, поддерживающего быстрый ответ 30
ANSWER_TEXT 'Hello' Да Текст быстрого ответа 30


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

JavaScript

B24.callMethod(
  'im.notify.answer',
  {
    ID: 270,
    ANSWER_TEXT: 'Hello'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

{
  "result_message": [
    "Ваш ответ успешно отправлен."
  ]
}

Возвращается массив сообщений на Ваш ответ.


Пример ответа, если передать идентификатор уведомления, не поддерживающего быстрый ответ

{
  "result_message": false
}

Пример ответа при возникновении ошибки

{
  "error":"NOTIFY_ID_ERROR",
  "error_description":"Notification ID can\u0027t be empty"
}

Описание ключей:

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

Код Описание
ID_ERROR Не передан параметр ID или он не является числом
ANSWER_TEXT_ERROR Не передан параметр ANSWER_TEXT или он не является непустой строкой


im.notify.confirm

Взаимодействие с кнопками нотификаций

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 30

Параметры

Параметр Пример Обязат. Описание Ревизия
ID 288 Да Идентификатор уведомления, поддерживающего выбор ответа посредством нажатия на кнопки 30
NOTIFY_VALUE 'Y' Да Значение выбранного ответа (значение кнопки) 30

Для примера рассмотрим уведомление:


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

JavaScript

B24.callMethod(
  'im.notify.confirm',
  {
    ID: 288,
    NOTIFY_VALUE: 'Y'
  },
  res => {
    if (res.error())
    {
      console.error(result.error().ex);
    }
    else
    {
      console.log(res.data())
    }
  }
)

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

{
  "result_message": [
    "Приглашение принято"
  ]
}

Пример ответа при возникновении ошибки

{
  "error":"NOTIFY_VALUE_ERROR",
  "error_description":"Notification Value  can\u0027t be empty"
}

Описание ключей:

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

Код Описание
ID_ERROR Не передан параметр ID или он не является числом
NOTIFY_VALUE_ERROR Не указан параметр NOTIFY_VALUE или он пуст


Полный список методов Chat API

Версия платформы:

МетодОписание метода
im.revision.get Получение информации о ревизиях API.

Работа с чатами:

МетодОписание метода
im.chat.add Создание чата.
im.chat.user.list Получение списка участников.
im.chat.user.add Приглашение участников.
im.chat.user.delete Исключение участников.
im.chat.leave Покинуть чат.
im.chat.sendTyping Отправка статуса «вам пишут...».
im.chat.updateTitle Обновление заголовка чата.
im.chat.updateColor Обновление цвета чата.
im.chat.updateAvatar Обновление аватара чата.
im.chat.setOwner Смена владельца чата.
im.chat.get Получение идентификатора чата.
im.chat.mute Отключение уведомлений в чате.

Работа с диалогами:

МетодОписание метода
im.dialog.messages.get Получение списка последних сообщений в чате.
im.dialog.read Изменение факта прочтения сообщений: все сообщения до указанного (включая само сообщение) помечаются как прочитанные.
im.dialog.unread Изменение факта прочтения сообщений: все сообщения после указанного (включая само сообщение) помечаются как непрочитанные.
im.dialog.get Получение информации о диалоге.

Работа с сообщениями:

МетодОписание метода
im.message.add Отправка сообщения в чат.
im.message.update Отправка изменения сообщения чат-бота.
im.message.delete Удаление сообщения чат-бота.
im.message.like Установка «Мне нравится».

Работа с файлами:

МетодОписание метода
im.disk.folder.get Получение информации о папке хранения файлов для чата.
im.disk.file.commit Публикация загруженного файла в чат.
im.disk.file.delete Удаление файлов внутри папки чата.
im.disk.file.save Сохранение файла в свой Битрикс24.Диск.

Работа с пользователями:

МетодОписание метода
im.user.get Получение данных о пользователе.
im.user.list.get Получение данных о пользователях.
im.user.business.list Получение списка бизнес-пользователей.
im.user.status.get Получение информации об установленном статусе пользователя.
im.user.status.set Установка статуса пользователя.
im.user.status.idle.start Установка автоматического статуса «Отошел».
im.user.status.idle.end Отключение автоматического статуса «Отошел».

Работа с подразделениями:

МетодОписание метода
im.department.get Получение данных о подразделении.
im.department.colleagues.list Получение списка пользователей, состоящих в вашем отделе.
im.department.managers.get Получение списка руководителей подразделений.
im.department.employees.get Получение списка сотрудников в подразделении.

Работа с поиском:

МетодОписание метода
im.search.user.list Поиск пользователей.
im.search.chat.list Поиск чатов.
im.search.department.list Поиск подразделений.
im.search.last.get Получение списка элементов последнего поиска.
im.search.last.add Добавление элемента истории последнего поиска.
im.search.last.delete Удаление элемента истории последнего поиска.

Работа со списком последних чатов:

МетодОписание метода
im.recent.get Список последних диалогов пользователя.
im.recent.pin Закрепление диалога в избранном.
im.recent.hide Удаление диалога из списка последних чатов.

Работа со счетчиками:

МетодОписание метода
im.counters.get Получение счетчиков.

Работа с уведомлениями:

МетодОписание метода
im.notify.personal.add Отправка персонального уведомления.
im.notify.system.add Отправка персонального уведомления.
im.notify.delete Удаление уведомления.
im.notify.read Установка отмены о прочитанных уведомлениях.


Приложения для чата

Что это такое?

Важно! Описанный в данной главе формат встраивания в чат приложений на текущий момент работает корректно, однако в дальнейшем для Нового чата нужно будет встраивать приложения в формате [ds]Rest Placement[/ds][di] В Новом чате реализован единый для всего продукта Rest Placement (места для встраивания Rest-приложений).

В рамках Нового чата есть несколько точек встраивания.

Подробнее...[/di].

Приложения для чата

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

Если приложение не загрузит картинку, будет выведена служебная иконка Приложения для чата, по клику на которую будет показан текстовый вариант иконки.

Приложение для чата бывает двух типов - JS команда или IFRAME приложение.



JS команда

При нажатии на иконку будет вставлена команда для чат-бота в поле ввода, либо отправлена команда в чат, либо начнется телефонный звонок, либо откроется открытая линия поддержки.

С помощью этого формата, разработчики в своих чат-ботах могут сделать кнопку для связи с ними.

Пример такой команды для чат-бота Марта - там появится иконка для игры в крестики нолики:



IFRAME приложение

Это улучшенный формат, при нажатии на иконку, будет открыто IFRAME приложение, в котором разработчик сможет сделать все, что пожелает.

Приложение может взаимодействовать с чатом c помощью JS-команд:

Пример такой реализации вы можете увидеть на примере чат-бота GIphy:

Прочувствуйте разницу - раньше вы писали команду в виде сообщения, и GIphy выдавал вам случайную картинку по теме. Теперь вы видите то, что отправляете.


Обратите внимание, иконки умеют понимать контекст, а это значит, что приложение может отображаться только в тех чатах, в которых вам это требуется.

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

Доступные контексты: all, chat, bot, lines, user, call.

К каждому контексту можно добавить постфикс -admin - тогда иконка будет показана в нужном контексте только администраторам.



Контекстные приложения

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

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



Создание приложения

Приложения делятся на два типа: JS-команда и IFRAME-приложение.

API-методы работы:

МетодОписание метода
imbot.app.register Регистрация приложения для чата.
imbot.app.unregister Удаление приложения для чата.
imbot.app.update Обновление данных о приложении в чате.


imbot.app.register

Регистрация приложения для чата


Приложения делятся на два типа: JS-команда и IFRAME-приложение.

Вызов метода для JS-команды

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

   'BOT_ID' => 62, // Идентификатор бота владельца приложения для чата
   'CODE' => 'echo', // Код приложения для чата
   'JS_METHOD' => 'SEND', 
   'JS_PARAM' => '/help', 
   'ICON_FILE' => '/* base64 image */', // Иконка в base64
   'CONTEXT' => 'BOT', // Контекст приложения
   'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям экстранет, по умолчанию N
   'LIVECHAT_SUPPORT' => 'N', // Поддержка онлайн-чата 
   'IFRAME_POPUP' => 'N', // iframe будет открыт с возможностью перемещения внутри мессенджера, переход между диалогами не будет закрывать такое окно. 
   'LANG' => Array( // Массив переводов, желательно указывать как минимум для RU и EN
      Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot BUTTON', 'DESCRIPTION' => 'Send help command'),

   )

), $_REQUEST["auth"]);

Варианты для JS_METHOD:

Формат иконки ICON_FILE:

Контекст CONTEXT указывает, где будет доступно приложение:

К каждому контексту можно добавить постфикс -admin, тогда приложение будет доступно в нужном контексте только администраторам Битрикс24.

Вызов метода для IFRAME-приложения

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

   'BOT_ID' => 62, // Идентификатор бота владельца приложения для чата
   'CODE' => 'echo', // Код приложения для чата
   'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php', 
   'IFRAME_WIDTH' => '350', // Желаемая ширина фрейма. Минимальное значение - 250px
   'IFRAME_HEIGHT' => '150', // Желаемая высота фрейма. Минимальное значение - 50px
   'HASH' => 'd1ab17949a572b0979d8db0d5b349cd2', // Токен для доступа к вашему фрейму для проверки подписи, 32 символа. 
   'ICON_FILE' => '/* base64 image */', // Иконка в base64
   'CONTEXT' => 'BOT', // Контекст
   'HIDDEN' => 'N', // Скрытое приложение или нет
   'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям экстранет, по умолчанию N
   'LIVECHAT_SUPPORT' => 'N', // Поддержка онлайн-чата 
   'IFRAME_POPUP' => 'N', // iframe будет открыт с возможностью перемещения внутри мессенджера, переход между диалогами не будет закрывать такое окно. 
   'LANG' => Array( // Массив переводов, желательно указывать как минимум для RU и EN
      Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot IFRAME', 'DESCRIPTION' => 'Open Echobot IFRAME app', 'COPYRIGHT' => 'Bitrix24'), 
   )

), $_REQUEST["auth"]);

Обратите внимание:
  1. Хоть вы при регистрации IFRAME-приложения и задаете размеры окна, оно может быть уменьшено приложением по фактически доступным размерам. Идеальный вариант – делать таким образом, чтобы оно вписывалось в минимальные размеры и могло свободно адаптироваться к увеличению и уменьшению, это будет очень важно для мобильных устройств.
  2. Cсылка на IFRAME обязательно должна вести на сайт с активным HTTPS-сертификатом. Правила разработки IFRAME-обработчика и ограничения вы можете прочитать в документации.
  3. Обязательно используйте проверки хешей перед выполнением любых операций.
  4. Приложения доступны только после перезагрузки страницы или после служебного хита на сервер (на разных установках по разному, от 15 до 26 минут). Приложение появится мгновенно только при взаимодействии с контекстной кнопкой.
  5. В значения IFRAME_WIDTH и IFRAME_HEIGHT вы указываете желаемые значения ширины и высоты окна приложения. Окно приложения будет уменьшено до размера окна мессенджера, если окно мессенджера окажется меньше. Если же, наоборот, больше, то будут использованы желаемые размеры для приложения.
  6. В случае вызова приложения из контекста (клавиатура или меню), оно будет вызвано в контекстном режиме. В этом режиме значение IFRAME_POPUP будет игнорироваться.

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

Числовой идентификатор созданного приложения APP_ID или ошибка.

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

Код Описание
BOT_ID_ERROR Чат-бот не найден.
APP_ID_ERROR Приложение для чата не принадлежит этому rest-приложению. Работать можно только с приложениями для чата, установленными в рамках текущего rest-приложения.
IFRAME_HTTPS Ссылка на IFRAME обязательно должна быть на сайт с активным HTTPS-сертификатом.
HASH_ERROR Вы не указали хеш для приложения. Мы рекомендуем использовать уникальных хеш для каждого IFRAME и каждой установки.
PARAMS_ERROR Ошибка при указании JS-команды или IFRAME-параметров.
LANG_ERROR Не переданы языковые фразы для видимой команды.
WRONG_REQUEST Что-то пошло не так.


imbot.app.unregister

Удаление приложения для чата

Вызов метода

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

    'APP_ID' => 13, // Идентификатор команды для удаления

), $_REQUEST["auth"]);

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

true или ошибка.

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

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


imbot.app.update

Обновление данных о приложении в чате

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

Вызов метода

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

   'APP_ID' => 13, // Идентификатор чата
   'FIELDS' => Array(
      'IFRAME' => 'https://marta.bitrix.info/iframe/echo.php',
      'IFRAME_WIDTH' => '350', // Желаемая ширина фрейма. Минимальное значение - 250px
      'IFRAME_HEIGHT' => '150', // Желаемая высота фрейма. Минимальное значение - 50px
      'JS_METHOD' => 'SEND', 
      'JS_PARAM' => '/help', 
      'HASH' => 'register', // Токен для доступа к вашему фрейму, 32 символа. 
      'ICON_FILE' => '/* base64 image */', // Иконка вашего приложения - base64
      'CONTEXT' => 'BOT', // Контекст приложения
      'EXTRANET_SUPPORT' => 'N', // Доступна ли команда пользователям экстранет, по умолчанию N
      'LIVECHAT_SUPPORT' => 'N', // Поддержка онлайн-чата 
      'IFRAME_POPUP' => 'N', // iframe будет открыт с возможностью перемещения внутри мессенджера, переход между диалогами не будет закрывать такое окно
      'LANG' => Array( // Массив переводов, желательно указывать как минимум для RU и EN
         Array('LANGUAGE_ID' => 'en', 'TITLE' => 'Echobot IFRAME', 'DESCRIPTION' => 'Open Echobot IFRAME app', 'COPYRIGHT' => 'Bitrix24'), 
      )
   )
), $_REQUEST["auth"]);

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

true или ошибка.

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

Код Описание
CHAT_APP_ID_ERROR Приложение не найдено.
APP_ID_ERROR Приложение для чата не принадлежит этому rest-приложению. Работать можно только с приложениями для чата, установленными в рамках текущего rest-приложения.
IFRAME_HTTPS Ссылка на IFRAME обязательно должна быть на сайт с активным HTTPS-сертификатом.
WRONG_REQUEST Что-то пошло не так.


Контекстные приложения

О том, что такое контекст-приложения можно прочитать здесь.


Для работы с контекстом, вам необходимо выполнить несколько действий:

  1. Зарегистрировать приложение. Вы можете зарегистрировать скрытое приложение, тогда оно не будет отображаться на панели ввода текста.
  2. Отправить (или обновить) любое сообщение с прикрепленной клавиатурой или с меню.
  3. В параметрах кнопки клавиатуры или пункта меню необходимо передать идентификатор приложения.

Вызов метода:
restCommand('imbot.message.add', Array(
   "DIALOG_ID" => 2,
   "BOT_ID" => 17,
   "MESSAGE" => "Hello! My name is EchoBot :)",
   "KEYBOARD" => [{"TEXT":"Open App","APP_ID":11}],
   "MENU" => [{"TEXT":"Open App","APP_ID":11}]

), $_REQUEST["auth"]);

Кроме APP_ID, вы можете передать любую строку в параметр APP_PARAMS, при открытии вашего IFRAME данные будут переданы параметру BUTTON_PARAMS.

Правила разработки IFRAME-обработчика и ограничения вы можете прочитать в документации. При создании сообщения вы можете использовать один из двух вариантов – клавиатура (KEYBOARD) или контекстное меню (MENU).



Создание иконки Приложения для чата

При создании иконки Приложения для чата вам необходимо придерживаться нескольких простых правил:

  1. Иконка должна быть на прозрачном фоне, в формате .PNG.

  2. Размер холста: 108х66 px, левая часть используется для неактивной иконки, вторая - для отображения активной:

  3. Основная часть иконки должна быть не более 45х32 px и обязательно отцентрирована по середине каждой части:

  4. Основной цвет неактивной иконки - #b3b7bc, активной - #2fc7f7:


    Чтобы вам было проще их создать, прикладываем несколько шаблонов:

    textarea_icon_f.psd marta_icon.psd textarea_icon.psd
  5. Для загрузки картинки, при регистрации или обновлении приложения вам необходимо передавать ключ IMAGE_FILE. Значение этого ключа должно быть base64 от вашей картинки:

    'ICON_FILE' => base64_encode(file_get_contents(__DIR__.'/icon_button.png')), 
    

    Обратите внимание, вы можете и не создавать иконку для приложения, тогда оно будет сгруппировано в служебную кнопку:



Cоздание IFRAME-обработчика

IFRAME-обработчик

После регистрации приложения для чата, вам необходимо сделать IFRAME-обработчик.

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


Ваша страница будет открыта со следующими данными

Array
(
    [BOT_ID] => 17
    [BOT_CODE] => echoBot
    [APP_ID] => 11
    [APP_CODE] => echoFrame
    [DOMAIN] => https://test.bitrix24.ru
    [DOMAIN_HASH] => 0e9c40cee01d6f182e9261b38b30b5c3
    [USER_ID] => 2
    [USER_HASH] => 7e23ac8b6f6c7044076301c7f81cd745
    [DIALOG_ID] => 950
    [CONTEXT] => textarea 
    [LANG] => ru 
    [IS_CHROME] => Y 
    [MESSAGE_ID] => 12333 
    [BUTTON_PARAMS] => test
    [DIALOG_ENTITY_ID] => telegrambot|8|173633217|569
    [DIALOG_ENTITY_DATA_1] => Y|LEAD|56|N|N|1765
    [DIALOG_CONTEXT] => lines 

)

Подробнее о параметрах:

Если фрейм запущен в режиме контекста:



Взаимодействие с родительским
окном (с мессенджером)

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

Примеры реализации:

<script type="text/javascript">
   // функция инициализации коммуникации с основным окном
   function frameCommunicationInit()
   {
      if (!window.frameCommunication)
      {
         window.frameCommunication = {timeout: {}};
      }
      if(typeof window.postMessage === 'function')
      {
         window.addEventListener('message', function(event){
            var data = {};
            try { data = JSON.parse(event.data); } catch (err){}
   
            if (data.action == 'init')
            {
               frameCommunication.uniqueLoadId = data.uniqueLoadId;
               frameCommunication.postMessageSource = event.source;
               frameCommunication.postMessageOrigin = event.origin;
            }
         });
      }
   }

   // функция отправки данных в основное окно
   function frameCommunicationSend(data)
   {
      data['uniqueLoadId'] = frameCommunication.uniqueLoadId;
      var encodedData = JSON.stringify(data);
      if (!frameCommunication.postMessageOrigin)
      {
         clearTimeout(frameCommunication.timeout[encodedData]);
         frameCommunication.timeout[encodedData] = setTimeout(function(){
            frameCommunicationSend(data);
         }, 10);
         return true;
      }
      
      if(typeof window.postMessage === 'function')
      {
         if(frameCommunication.postMessageSource)
         {
            frameCommunication.postMessageSource.postMessage(
               encodedData,
               frameCommunication.postMessageOrigin
            );
         }
      }
   }
   frameCommunicationInit();
</script>

После этого вам будут доступны следующие функции:



Регистрация и безопасность

Вы можете не проверять входящие запросы, но мы настоятельно рекомендуем это делать.

На основе входящих данных вы можете реализовать необходимые проверки:

  1. Рекомендуем проверять REFERER на совпадение с указанным доменом.
  2. Рекомендуем проверять домен и хеш от него.
  3. Рекомендуем проверять пользователя и хеш от него.
  4. Используйте уникальный HASH для каждой новой регистрации.

В сочетании всех этих факторов вы сможете сделать достаточно безопасное приложение.


При регистрации команды, вы должны указать HASH-строку, которой будут подписываться домен и пользователь:

$hash = '0e9c40cee01d6f182e9261b38b30b5c3'; // hash, указанный при регистрации приложения

$check = parse_url($_GET['DOMAIN']);

// проверка на валидность указанного домена
if ($_GET['DOMAIN_HASH'] == md5($check['host'].$hash))
{
   echo 'OK';
}

// проверка на валидность указанного пользователя
if ($_GET['USER_HASH'] == md5($_GET['USER_ID'].$hash))
{
   echo 'OK';
}

// проверка на REFERER
if (strpos($_SERVER['HTTP_REFERER'], $_GET['DOMAIN'])!== 0)
{
   echo 'OK';
}

Работа в таком режиме подробно рассмотрена в демо-примере, который вы можете скачать здесь.

Приложения для Нового чата

Примечание: На текущий момент Новый чат доступен в облачной версии Битрикс24 всем партнёрам на [ds]NFR-лицензиях[/ds][di] NFR (not for resale / не для перепродажи) – бесплатная лицензия на определенный период, предназначенная для ознакомления с программой и тестовых развёртываний программы.

Подробнее... [/di].

Предыдущий формат встраивания в чат приложений был реализован ещё до создания единого для всего продукта формата Rest Placement (места для [ds]встраивания[/ds][di] Ваше приложение может добавлять функционал в специальные отведенные области стандартного интерфейса: карточки объектов CRM, различные списки элементов и т.д.

Для этого установите обработчик места встраивания при помощи placement.bind. Одно приложение может установить произвольное число обработчиков, даже для одного и того же места встраивания (например, если вам нужно добавить несколько разных операций в контекстное меню лида в CRM).

Подробнее...[/di] Rest-приложений).

После выхода формата Rest Placement разработчикам для одинаковой задачи "встроиться в продукт" нужно было изучить два разных формата реализации ([ds]старый формат[/ds][di] Разработчики могут встраиваться в Мессенджер, добавив свою иконку в панель ввода текста.

Приложение для чата бывает двух типов - JS команда или IFRAME приложение.

Подробнее...[/di] для чатов и новый – для остальных сущностей), а поддерживать в одном приложении несколько вариантов довольно сложно.

Поэтому в Новом чате, который станет доступен клиентам чуть позже в 2023 году, реализован единый для всего продукта Rest Placement.

В рамках Нового чата есть несколько точек встраивания:

Общая информация по всем точкам встраивания

Приложения для Нового чата

Все встраивания являются стандартным форматом и регистрируются с помощью метода placement.bind. Пример:

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_SIDEBAR',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/sidebar.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение в сайдбаре',
            ],
        ],
        'OPTIONS' => [
            'iconName' => 'fa-bug',
            'context' => 'USER;LINES',
            'role' => 'ADMIN',
            'extranet' => 'N',
        ]
    ]
);

Рассмотрим подробнее секцию OPTIONS:



IM_NAVIGATION

Приложение для левого меню навигации

Код встраивания: IM_NAVIGATION

По сути, это приложение внутри окружения чата без встраивания непосредственно в чат.

Параметры

Параметр Обязат. Описание
iconName Да Название класса иконки в формате Font Awesome (например, fa-cloud).
role Нет Роль пользователя, для которой доступно это приложение (по умолчанию USER). Поддерживает следующие значения доступа:
  • USER – для всех пользователей;
  • ADMIN – только для администраторов портала.
extranet Нет Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
  • N – недоступно для экстранет-пользователей;
  • Y – доступно для экстранет-пользователей.

IFRAME открывается, но в него не передаётся контекст текущего чата (т.к. навигация – это сущность вне контекста чата).

Фрейм приложения открывается в окружении чата, мимикрируя под общую сетку.

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

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_NAVIGATION',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/navigation.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение для левого меню навигации',
            ],
        ],
        'OPTIONS' => [
            'iconName' => 'fa-check',
            'role' => 'USER',
            'extranet' => 'N',
        ]
    ]
);



IM_TEXTAREA

Приложение для панели над полем ввода

Код встраивания: IM_TEXTAREA

Данный формат был и раньше – это генерация контента в момент написания сообщения.

Параметры

Параметр Обязат. Описание
iconName Да Название класса иконки в формате Font Awesome (например, fa-cloud).
context Нет Для какого типа чата встраивать приложение (по умолчанию ALL). Поддерживает множественный выбор через ; следующих значений:
  • USER – чаты всех пользователей, исключая ботов;
  • CHAT – все групповые чаты, кроме lines и crm;
  • LINES – тип чата lines (открытые линии);
  • CRM – только чаты, созданные в рамках CRM;
  • ALL – все чаты.
role Нет Роль пользователя, для которой доступно это приложение (по умолчанию USER). Поддерживает следующие значения:
  • USER – приложение доступно для всех пользователей;
  • ADMIN – приложение доступно только для администраторов портала.
color Нет Цвет. Доступны значения: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, ORANGE, MARENGO, GRAY, GRAPHITE.
width Нет Рекомендуемая ширина фрейма как в старом чате (по умолчанию 100).
height Нет Рекомендуемая высота фрейма как в старом чате (по умолчанию 100).
extranet Нет Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
  • N – приложение недоступно для экстранет-пользователей;
  • Y – приложение доступно для экстранет-пользователей.

В данном встраивании доступен текущий контекст открытия, будет передан dialogId текущего чата.

const context = BX24.placement.info().options;

Будет открыт IFRAME приложения с заданными размерами. Если вы укажете размер приложения больше, чем может быть показан, то этот размер автоматически будет уменьшен (ваше приложение должно это учитывать).

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

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_TEXTAREA',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/textarea.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение для панели над полем ввода',
            ],
        ],
        'OPTIONS' => [
            'iconName' => 'fa-bars',
            'context' => 'USER;CHAT',
            'role' => 'USER',
            'color' => 'GRAPHITE',
            'width' => '200',
            'height' => '100',
            'extranet' => 'N',
        ]
    ]
);



IM_SIDEBAR

Приложение для сайдбара

Код встраивания: IM_SIDEBAR

Можно создавать приложения, добавляющие дополнительные сценарии для чата – например, отдельный диск для чата или базу знаний.

Параметры

Параметр Обязат. Описание
iconName Да Название класса иконки в формате Font Awesome (например, fa-cloud).
context Нет Для какого типа чата встраивать приложение (по умолчанию ALL). Поддерживает множественный выбор через ; следующих значений:
  • USER – чаты всех пользователей, исключая ботов;
  • CHAT – все групповые чаты, кроме lines и crm;
  • LINES – тип чата lines (открытые линии);
  • CRM – только чаты, созданные в рамках CRM;
  • ALL – все чаты.
role Нет Роль пользователя, для которой доступно это приложение (по умолчанию USER). Поддерживает следующие значения:
  • USER – приложение доступно для всех пользователей;
  • ADMIN – приложение доступно только для администраторов портала.
color Нет Цвет. Доступны значения: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, ORANGE, MARENGO, GRAY, GRAPHITE.
extranet Нет Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
  • N – приложение недоступно для экстранет-пользователей;
  • Y – приложение доступно для экстранет-пользователей.

В данном встраивании доступен текущий контекст открытия, будет передан dialogId текущего чата.

const context = BX24.placement.info().options;

Приложение будет мимикрировать под сценарий работы сайдбара (будет открыт слайдер, повторяющий слой детали сайдбара).

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

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_SIDEBAR',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/sidebar.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение для сайдбара',
            ],
        ],
        'OPTIONS' => [
            'iconName' => 'fa-bug',
            'context' => 'USER;LINES',
            'role' => 'ADMIN',
            'color' => 'AQUA',
            'extranet' => 'N',
        ]
    ]
);



IM_CONTEXT_MENU

Приложение для открытия контекстного меню сообщения внутри чата

Код встраивания: IM_CONTEXT_MENU

Встраивание в пункт "Создать контент на основании" (аналогом является "Создать задачу” или "Создать встречу" на основании сообщения).

Параметры

Параметр Обязат. Описание
context Нет Для какого типа чата встраивать приложение (по умолчанию ALL). Поддерживает множественный выбор через ; следующих значений:
  • USER – чаты всех пользователей, исключая ботов;
  • CHAT – все групповые чаты, кроме lines и crm;
  • LINES – тип чата lines (открытые линии);
  • CRM – только чаты, созданные в рамках CRM;
  • ALL – все чаты.
role Нет Роль пользователя, для которой доступно это приложение (по умолчанию USER). Поддерживает следующие значения:
  • USER – приложение доступно для всех пользователей;
  • ADMIN – приложение доступно только для администраторов портала.
extranet Нет Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
  • N – приложение недоступно для экстранет-пользователей;
  • Y – приложение доступно для экстранет-пользователей.

В данном встраивании доступен текущий контекст открытия, будет передан dialogId текущего чата и messageId выбранного сообщения.

const context = BX24.placement.info().options;

Приложение будет открываться в стилистике слайдера (как задачи или как календарь).

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

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_CONTEXT_MENU',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/context_menu.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение для открытия контекстного меню сообщения внутри чата',
            ],
        ],
        'OPTIONS' => [
            'context' => 'USER;CHAT',
            'role' => 'USER',
            'extranet' => 'N',
        ]
    ]
);



IM_SMILES_SELECTOR

Приложение для расширения возможностей смайлов и giphy

Код встраивания: IM_SMILES_SELECTOR

Тут могут быть свои источники картинок или смайлов.

Параметры

Параметр Обязат. Описание
context Нет Для какого типа чата встраивать приложение (по умолчанию ALL). Поддерживает множественный выбор через ; следующих значений:
  • USER – чаты всех пользователей, исключая ботов;
  • CHAT – все групповые чаты, кроме lines и crm;
  • LINES – тип чата lines (открытые линии);
  • CRM – только чаты, созданные в рамках CRM;
  • ALL – все чаты.
role Нет Роль пользователя, для которой доступно это приложение (по умолчанию USER). Поддерживает следующие значения:
  • USER – приложение доступно для всех пользователей;
  • ADMIN – приложение доступно только для администраторов портала.
extranet Нет Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
  • N – приложение недоступно для экстранет-пользователей;
  • Y – приложение доступно для экстранет-пользователей.

В данном встраивании доступен текущий контекст открытия, будет передан dialogId текущего чата.

const context = BX24.placement.info().options;

Приложение отрисовывается в рамках всплывающего окна (pop up) с селектором смайлов и giphy (без возможности изменить размер).

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

CRest::call(
    'placement.bind',
    [
        'PLACEMENT' => 'IM_SMILES_SELECTOR',
        'HANDLER' => 'https://example.com/apps/immarket/handlers/smiles_selector.php',
        'LANG_ALL' => [
            'ru' => [
                'TITLE' => 'Приложение для расширения возможностей смайлов и giphy',
            ],
        ],
        'OPTIONS' => [
            'context' => 'USER;LINES',
            'role' => 'USER',
            'extranet' => 'Y',
        ]
    ]
);



Rest API

Rest API бот-платформы являются составной частью общей системы REST. Документация по всем остальным методам расположена в [ds]Документации REST API[/ds][di] Битрикс24 - программный продукт в виде облачного сервиса, а также коробочной версии, созданный компанией "1С-Битрикс". Разработчики могут создавать собственные приложения или интеграции для Битрикс24, используя открытый REST API, который работает как с облачным, так и с коробочным Битрикс24, начиная с версии 16.6.0.

Подробнее ...[/di].

Возможности Rest API

Rest API предназначено для создания приложений для облачного сервиса Битрикс24.

Rest API позволяет получить доступ и управлять такими инструментами облачного сервиса Битрикс24 как:

Для использования методов Rest API внешними приложениями приложение должно быть зарегистрировано в Маркетплейсе. В этом случае у приложения есть все необходимые данные для получения ключа OAuth 2.0.

В общем виде вызов метода REST выглядит вот так:

https://домен_Б24.bitrix24.{ru|en|de}/rest/имя_метода.транспорт?параметры_метода&auth=ключ_авторизации
где транспорт - необязательный параметр, который может иметь значения json или xml. По умолчанию - json.

Запрос может отправляться как методом GET, так и POST.

Значения параметров методов принимаются в кодировке UTF-8.

Внимание! Существует лимит на число запросов. Разрешается два запроса в секунду. Если лимит превышается, то ограничение начинает срабатывать после 50 запросов.
Для тарифа «Энтерпрайз» число запросов - 5 в секунду. Лимит на число запросов - 250.

Примечание: Если Ваше приложение/вебхук создаёт аномальную нагрузку на портал, может сработать блокировка:
[
'error' => 'OVERLOAD_LIMIT',
'error_description' => 'REST API is blocked due to overload.'
]
Для разблокировки необходимо обратиться в техподдержку.

Rest API бот-платформы являются составной частью общей системы REST. Документация по всем остальным методам расположена в [ds]Документации REST API[/ds][di] Битрикс24 - программный продукт в виде облачного сервиса, а также коробочной версии, созданный компанией "1С-Битрикс". Разработчики могут создавать собственные приложения или интеграции для Битрикс24, используя открытый REST API, который работает как с облачным, так и с коробочным Битрикс24, начиная с версии 16.6.0.

Подробнее ...[/di].



Открытые линии Rest API

Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).



Версия платформы

imopenlines.revision.get – получение информации о ревизиях API Открытых линий

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 2

Параметры

Нет.

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

JavaScript

BX24.callMethod('imopenlines.revision.get', {}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP

$result = restCommand('imopenlines.revision.get', Array(
), $_REQUEST["auth"]);

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

{    
    "result": {
        "rest": 2,
        "web": 1,
        "mobile": 1,
    }
}

Описание ключей:


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



Работа с открытыми линиями

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).


МетодОписание метода
imopenlines.network.join Подключение открытой линии по коду.
imopenlines.network.message.add Отправка сообщения от лица открытой линии выбранному пользователю.


imopenlines.network.join

Подключение открытой линии по коду

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).

Параметры

Параметр Пример Обязат. Описание Ревизия
CODE ab515f5d85a8b844d484f6ea75a2e494 Да Код для поиска со страницы коннекторов 1


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

PHP

$result = restCommand('imopenlines.network.join', Array(

    'CODE' => 'ab515f5d85a8b844d484f6ea75a2e494'

), $_REQUEST["auth"]);

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

{
	"result": 42
}

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

Пример ответа при возникновении ошибки

{
    "error": "NOT_FOUND",
    "error_description": "Openline is not found"
}

Описание ключей:

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

Код Описание
IMBOT_ERROR Не установлен модуль по управлению ботами
NOT_FOUND Открытая линия не найдена
INACTIVE Открытая линия в данный момент недоступна


Работа с диалогами

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).


МетодОписание метода
imopenlines.dialog.get Получение информации о диалоге (чате) оператора открытой линии.


imopenlines.dialog.get

Получение информации о диалоге (чате) оператора открытой линии

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 2

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

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 13 Нет Числовой идентификатор чата 2
DIALOG_ID chat29
или
256
Нет Идентификатор диалога. Формат:
chatXXX – чат получателя, если сообщение для чата
или XXX – идентификатор получателя, если сообщение для приватного диалога
2
SESSION_ID 1743 Нет Идентификатор сессии в рамках открытой линии 2
USER_CODE livechat|1|1373|211 Нет Строковый идентификатор пользователя открытой линии из CRM, пример livechat|1|1373|211 или imol|livechat|1|1373|211 2

Можно использовать для вызова любой из параметров.

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

JavaScript

BX24.callMethod('imopenlines.dialog.get', {USER_CODE: 'livechat|1|1373|211'}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

PHP

$result = restCommand('imopenlines.dialog.get', Array(
	'DIALOG_ID': 'chat29'
), $_REQUEST["auth"]);

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

{
    "result": 
  {
	avatar: ""
	color: "#4ba984"
	date_create: "2020-05-12T17:40:55+02:00"
	dialog_id: null
	entity_data_1: "N|NONE|0|N|N|0|1591872180|1|0|"
	entity_data_2: ""
	entity_data_3: ""
	entity_id: "livechat|1|1363|203"
	entity_type: "LINES"
	extranet: false
	id: 1364
	manager_list: []
	message_type: "L"
	name: "Евгений Перекопский - Приоритетная поддержка"
	owner: 0
	type: "lines"
  }
}

Описание ключей:



Пример ответа при возникновении ошибки

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Описание ключей:

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

Код Описание
DIALOG_ID_EMPTY Не передан идентификатор диалога
ACCESS_ERROR Текущий пользователь не имеет прав доступа к диалогу


Работа с чат-ботами

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).


МетодОписание метода
imopenlines.bot.session.operator Переключение разговора на свободного оператора.
imopenlines.bot.session.transfer Переключение разговора на конкретного оператора.
imopenlines.bot.session.finish Завершение текущей сессии.
imopenlines.bot.session.message.send Метод отправки чат-ботом автоматического сообщения.


imopenlines.bot.session.operator

Переключение разговора на свободного оператора

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 12 Да Идентификатор чата 1


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

PHP


$result = restCommand('imopenlines.bot.session.operator', Array(

    'CHAT_ID' => 12

), $_REQUEST["auth"]);

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

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

Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
WRONG_CHAT Указанный чат находится не под управлением бота.
BOT_ID_ERROR Неправильный идентификатор чат-бота.


imopenlines.bot.session.transfer

Переключение разговора на конкретного оператора

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 112 Да Идентификатор чата 1
USER_ID 12 Да Идентификатор пользователя, на которого осуществляется перенаправление 1
LEAVE N Да Y/N. Если указано N - чат-бот не покинет данный чат после переадресации и будет присутствовать до момента подтверждения пользователя 1


Примечание: Вместо USER_ID можно указать QUEUE_ID для переключения на другую открытую линию.

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

PHP

$result = restCommand('imopenlines.bot.session.transfer', Array(

    'CHAT_ID' => 112,
    'USER_ID' => 12,
    'LEAVE' => 'N'

), $_REQUEST["auth"]);

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

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

Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
USER_ID_EMPTY Не передан идентификатор пользователя, на которого необходимо переадресовать разговор.
WRONG_CHAT Указан некорректный идентификатор пользователя или этот пользователь является чат-ботом или экстранет пользователем.
BOT_ID_ERROR Неправильный идентификатор чат-бота.


imopenlines.bot.session.finish

Завершение текущей сессии

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 112 Да Идентификатор чата 1


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

PHP

$result = restCommand('imopenlines.bot.session.finish', Array(

    'CHAT_ID' => 112

), $_REQUEST["auth"]);

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

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

Пример ответа при возникновении ошибки

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Не передан идентификатор чата"
}

Описание ключей:

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

Код Описание
CHAT_ID_EMPTY Не передан идентификатор чата.
BOT_ID_ERROR Неправильный идентификатор чат-бота.


imopenlines.bot.session.message.send

Отправка чат-ботом автоматического сообщения

[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1

Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).

Параметры

Параметр Пример Обязат. Описание Ревизия
CHAT_ID 2 Да Идентификатор чата, который забирает текущий оператор 1
MESSAGE message text Да Отправляемое сообщение 1
NAME WELCOME Да Тип сообщения: WELCOME - приветственное сообщение, DEFAULT - обычное сообщение. По умолчанию, пустое значение 1


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

PHP

$result = restCommand('imopenlines.bot.session.message.send', Array(

	'CHAT_ID' => 2,
	'MESSAGE' => 'message text',
	'NAME' => 'WELCOME'
), $_REQUEST["auth"]);

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

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



Полный список методов Rest API

Версия платформы:

МетодОписание метода
imopenlines.revision.get Получение информации о ревизиях API.

Работа с открытыми линиями:

МетодОписание метода
imopenlines.network.join Подключение открытой линии по коду.
imopenlines.network.message.add Отправка сообщения от лица открытой линии выбранному пользователю.

Работа с диалогами:

МетодОписание метода
imopenlines.dialog.get Получение информации о диалоге (чате) оператора открытой линии.

Работа с чат-ботами:

МетодОписание метода
imopenlines.bot.session.operator Переключение разговора на свободного оператора.
imopenlines.bot.session.transfer Переключение разговора на конкретного оператора.
imopenlines.bot.session.finish Завершение текущей сессии.
imopenlines.bot.session.message.send Метод отправки чат-ботом автоматического сообщения.


Отправка команд и продление авторизации

Взаимодействие с помощью PHP

В рамках нашего курса мы взаимодействуем c Битрикс24 с помощью PHP.

Все примеры указаны с использованием функций restCommand:

restCommand('imbot.message.add', Array(
   "DIALOG_ID" => $_REQUEST['data']['PARAMS']['DIALOG_ID'],
   "MESSAGE" => "[put=/search]Введите строку поиска[/put]",
), $_REQUEST["auth"]);
где:
Первый параметр – это название API (imbot.message.add);
Второй параметр – это передаваемые данные в API (Array(...))
Третий параметр – это данные для авторизации запроса ($_REQUEST["auth"]).

Примечание: Эта функция используется в качестве примера. Вы можете использовать свою функцию, основанную на протоколе взаимодействия, или javascript-метод BX24.callMethod, или партнерскую разработку bitrix24-php-sdk.



Функция restCommand

/**
 * Send rest query to Bitrix24.
 *
 * @param $method - Rest method, ex: methods
 * @param array $params - Method params, ex: Array()
 * @param array $auth - Authorize data, ex: Array('domain' => 'https://test.bitrix24.com', 'access_token' => '7inpwszbuu8vnwr5jmabqa467rqur7u6')
 * @param boolean $authRefresh - If authorize is expired, refresh token
 * @return mixed
 */
function restCommand($method, array $params = Array(), array $auth = Array(), $authRefresh = true)
{
   $queryUrl = "https://".$auth["domain"]."/rest/".$method;
   $queryData = http_build_query(array_merge($params, array("auth" => $auth["access_token"])));
   
   $curl = curl_init();

   curl_setopt_array($curl, array(
      CURLOPT_POST => 1,
      CURLOPT_HEADER => 0,
      CURLOPT_RETURNTRANSFER => 1,
      CURLOPT_SSL_VERIFYPEER => 1,
      CURLOPT_URL => $queryUrl,
      CURLOPT_POSTFIELDS => $queryData,
   ));

   $result = curl_exec($curl);
   curl_close($curl);

   $result = json_decode($result, 1);

   if ($authRefresh && isset($result['error']) && in_array($result['error'], array('expired_token', 'invalid_token')))
   {
      $auth = restAuth($auth);
      if ($auth)
      {
         $result = restCommand($method, $params, $auth, false);
      }
   }

   return $result;
}


Функция restAuth

Функция restAuth

/**
 * Get new authorize data if you authorize is expire.
 *
 * @param array $auth - Authorize data, ex: Array('domain' => 'https://test.bitrix24.com', 'access_token' => '7inpwszbuu8vnwr5jmabqa467rqur7u6')
 * @return bool|mixed
 */
function restAuth($auth)
{
   if (!CLIENT_ID || !CLIENT_SECRET)
      return false;

   if(!isset($auth['refresh_token']) || !isset($auth['scope']) || !isset($auth['domain']))
      return false;

   $queryUrl = 'https://'.$auth['domain'].'/oauth/token/';
   $queryData = http_build_query($queryParams = array(
      'grant_type' => 'refresh_token',
      'client_id' => CLIENT_ID,
      'client_secret' => CLIENT_SECRET,
      'refresh_token' => $auth['refresh_token'],
      'scope' => $auth['scope'],
   ));
   
   $curl = curl_init();

   curl_setopt_array($curl, array(
      CURLOPT_HEADER => 0,
      CURLOPT_RETURNTRANSFER => 1,
      CURLOPT_URL => $queryUrl.'?'.$queryData,
   ));

   $result = curl_exec($curl);
   curl_close($curl);

   $result = json_decode($result, 1);
   
   return $result;
}


Подписка на события

Обработчик серверных событий

Интерфейс REST API позволяет устанавливать свои обработчики серверных событий.

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

Обработчик получает на вход следующие данные:

Обработчик может:

Внимание! Если обработчику требуется обращение к Rest API для работы с данными, то настоятельно рекомендуется использовать для этого данные авторизации сохраненные на стороне приложения, а не опираться на получение access_token, так как его может и не быть.


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

Обработчик события будет вызван не сразу после срабатывания, а через некоторое время, зависящее от нагрузки.

Список доступных событий можно получить при помощи REST-метода events.



Установка обработчика

Установка обработчика события производится: