Установка отмены о прочитанных уведомлениях - im.notify.read
Февраль 2018
В методы imbot.register и imbot.update были добавлены поля EVENT_MESSAGE_UPDATE и EVENT_MESSAGE_DELETE для подписки на события изменения и удаления сообщений.
Добавлен новый тип чат-бота с повышенными привилегиями (supervisor) - бот, получающий доступ ко всем сообщениям в чатах, где он состоит (ко всем, если его пригласили с доступом к истории, и к новым, если доступ к истории ему не доступен).
Для создания чат-бота с повышенными привилегиями в метод imbot.register в поле TYPE укажите тип S.
Обратите внимание, если это не требуется логикой вашего приложения, то рекомендуется отвечать боту на сообщения пользователя только при упоминании этого чат-бота. Проверить это можно по полю TO_USER_ID, которое будет передано в событие.
Кроме этого добавлены обработчики для отслеживания изменения и удаления сообщений (доступны для этого типа бота).
В метод im.chat.add добавлены новые поля ENTITY_TYPE и ENTITY_ID, с помощью которых вы можете осуществить быстрый поиск и идентификацию чата в событиях EVENT_MESSAGE_ADD, EVENT_MESSAGE_UPDATE, EVENT_MESSAGE_DELETE.
Метод imbot.update больше не поддерживает изменение полей TYPE и OPENLINE.
Добавлен новый метод im.chat.get, который с помощью ENTITY_TYPE и ENTITY_ID позволяет получить идентификатор чата.
В события EVENT_MESSAGE_ADD, EVENT_MESSAGE_UPDATE, EVENT_MESSAGE_DELETE добавлены поля CHAT_ENTITY_TYPE и CHAT_ENTITY_ID для идентификации чата (данные поля вы можете задать в момент создания).
В события EVENT_MESSAGE_ADD, EVENT_MESSAGE_UPDATE добавлено поле TO_USER_ID, в котором будет идентификатор упомянутого пользователя. Благодаря этому, в случае бота с типом S вы сможете понять, нужно ли вам отвечать или нет.
Обновление в imbot.register и imbot.update: если все обработчики событий у вас ведут на один и тот же адрес, вы вместо указания EVENT_MESSAGE_ADD, EVENT_MESSAGE_UPDATE, EVENT_MESSAGE_DELETE, EVENT_WELCOME_MESSAGE, EVENT_BOT_DELETE - можете указать только EVENT_HANDLER - значение из него автоматически пропишется во все обработчики.
В метод im.chat.add добавлено новое поле OWNER_ID, с помощью которого вы сможете указать владельца чата.
В раздел Работа с чатами (Bot API) добавлены методы:
В метод imbot.register был добавлен новый код ошибки MAX_COUNT_ERROR - достигнуто максимальное количество зарегистрированных ботов для одного приложения.
Теперь максимальное количество ботов для одного приложения: 5.
С чего начать
В главе дается представление о том, что такое чат-боты и зачем они нужны, как работают и что могут делать. Также мы расскажем, как создать своё приложение для чат-бота и, собственно, покажем пример готового чат-бота для платформы Битрикс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]
Клавиатура - это набор кнопок, каждая кнопка может состоять из определённых ключей.
EchoBot
Постраничная навигация, кнопки при вызове команды «Помощь»
Марта
Просто напишите марте Поиграй со мной!. Клавиатура используется как игровое поле:
Giphy
Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему:
Примечание: Подробнее о работе с клавиатурами можно прочитать здесь
Чаты
Чат-боты могут общаться в чате почти как живые люди. Также они могут напоминать о различных событиях (о текущих задачах, встречах) или давать справочную информацию. Кроме того, что чат-боты могут писать в чаты, они могут еще создавать такие чаты и автоматически приглашать туда людей, например для обсуждения какой либо задачи.
Примечание: Подробнее о работе с чатами можно прочитать здесь
Уведомления
Уведомления от чат-бота могут быть полезны и информативны. Они могут состоять из нескольких блоков различной информации из внешних систем.
Примечание: Подробнее о работе с уведомлениями можно прочитать здесь
Жизненный цикл чат-бота
Чат-бот публикует свои сообщения в чат через Rest API, получает ответы и команды пользователя через События Rest API (POST запрос).
Схема жизни чат-бота выглядит так:
Создание своего приложения
Основное, что нам надо понимать про чат-боты – это то, что их логика обычно строится на реагировании на некие действия пользователя и системы.
И у нас есть 6 событий, которые полностью покрывают необходимый спектр реакций:
ONAPPINSTALL – событие на установку приложения с чат-ботом.
ONIMJOINCHAT – событие после приглашения чат-бота «к разговору», т.е. либо при вызове его пользователем в индивидуальном чате, либо при подключении его к групповому чату.
ONIMBOTMESSAGEADD – событие после отправки сообщения от пользователя к чат-боту (в групповом чате, при явном упоминании бота).
ONIMCOMMANDADD – событие после отправки команды от пользователя к чат-боту (в персональной переписке с ним, или в групповом чате (если команда глобальная, то он может не участвовать в чате)).
Иными словами, мы должны написать обработчики указанных событий, чтобы реализовать простую логику:
Зарегистрировать чат-бота на портале пользователя при установке.
Вывести приветствие-справку от имени чат-бота в момент приглашения его в чат.
Научиться анализировать текст сообщения от пользователя и что-то отправлять в ответ, причем под анализом подразумевается простой «разбор командной строки», а не лексический разбор естественного языка.
И для этого у нас есть набор простых методов, добавленных в 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' => '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',
// Аватар бота - 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оздание чат-бота для Открытых линий аналогично созданию обычного чат-бота, за исключением нескольких примечаний:
При создании чат-бота для Открытых линий в imbot.register в параметр TYPE нужно передать O.
Если необходимо расширить возможности уже существующего чат-бота, то нужно передать новый ключ OPENLINE => Y, тогда чат-бот будет работать в гибридном режиме.
Внимание! В гибридном режиме чат-бот должен корректно обрабатывать ситуацию, когда его приглашают и общаются в групповом, персональном и чате открытых линий. Для этого нужно во всех входящих событиях (ONIMBOTMESSAGEADD, ONIMBOTJOINCHAT) проверять параметр CHAT_ENTITY_TYPE, для Открытых линий он должен быть CHAT_ENTITY_TYPE => LINES.
Во всем остальном, это привычный и уже знакомый чат-бот.
Для более тесной интеграции с Открытыми линиями необходимо иметь права доступа на scope imopenlines.
Имея такие права, будут доступны команды:
imopenlines.network.join - подключение открытой линии вашей компании в портал Битрикс24, после чего сотрудники смогут вам писать.
Примечание. Для чат-ботов не является обязательным использование сертификата https, но крайне рекомендуется из-за возможной передачи конфиденциальных данных клиента. При этом само приложение должно быть в кодировке UTF-8.
Скачать пример чат-бота для Открытых линий
В качестве примера чат-бота для открытых линий мы подготовили чат-бот ITR Bot. Cкачать его можно:
или взять в продукте «Битрикс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, в том числе и по чат-ботам.
Для этого необходимо:
Перейти в раздел Контакт-центр и подключить канал коммуникации Битрикс24.Network:
После подключения вам будет доступна форма настроек подключения к Битрикс24.Network:
Обязательно заполните поля Название, Краткое описание и установите Аватар - это поможет клиентам легче вас найти.
Приветственное сообщение будет автоматически отправлено, как только пользователь перейдет в вашу Открытую линию Битрикс24.Network:
Обратите внимание на галочку Доступен в поиске: если вы хотите организовать закрытую линию поддержки, вам необходимо выключить этот пункт.
После этого ваша линия пропадет из поиска Бизнес-чата портала и найти ее можно будет, только указав поиске уникальный код.
Если опция Доступен в поиске включена, то вашу открытую линию можно будет найти по названию в поиске Бизнес-чата портала, точно также, как и пользователя Битрикс24.Network.
Создать новую или выбрать действующую открытую линию технической поддержки по вашему продукту:
Чтобы вашим пользователям было удобно, можно с помощью 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.
Если вы отправите ссылку на картинку https://files.shelenkov.com/bitrix/images/mantis.jpg (окончание ссылки должно быть .png, .jpg, .gif), то она автоматически преобразуется в изображение:
Вы можете сформировать ссылку самостоятельно через код URL - [URL=http://bitrix24.ru]Ссылка на Битрикс24[/URL]:
Если вы хотите, чтобы по клику на ссылку пользователь отправил какой-то текст, используйте тег SEND:
[send=текст]название кнопки[/send] - мгновенная отправка текста боту.
С помощью такого тега, вы сможете заставить пользователя отправить команду вашего бота, но существует более предпочтительный способ - Набираемые клавиатуры
Если необходимо, чтобы пользователь что-то дописал к команде, используйте код PUT:
[put=/search]Введите строку поиска[/put]
С помощью данного тега можно дать возможность пользователю указать дополнительные данные для вашей команды вместо того, чтобы пользователь набирал команду вручную. После клика на такую ссылку, текст указанный в теге PUT будет подставлен в поле для ввода и пользователю достаточно будет дописать необходимые данные и нажать кнопку отправить (но существует более предпочтительный способ - Набираемые клавиатуры):
Также после этого иконка будет добавлена в набор смайлов Бизнес-чата. Удалить иконку из набора можно, нажав правой кнопкой мыши на иконке в наборе и выбрав Удалить.
Обязательным свойством является указание пути до картинки (без пробелов).
Доступны дополнительные атрибуты:
title - заголовок;
height - высота;
width - ширина;
size - высота и ширина;
Для наилучшего отображения на всех устройствах, размер иконки должен быть в два раза больше, чем указан в параметрах отображения.
COLOR - отвечает за цветовое выделение вложения. По умолчанию цвет вложения назначается в цвет чата получателя (или если это уведомление в цвет текущего пользователя), Данный ключ можно не задавать, если не требуется.
BLOCKS должен содержать блоки разметки, которые мы рассмотрим чуть ниже.
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-уведомления на телефон.
GRID - существует три представления блока: блочное, строчное и в виде 2х колонок.
Внимание Во всех 3-х представлениях смешивать элементы в рамках одной записи нельзя. Если нужно одновременно использовать блоки разного типа, нужно создавать новый блок:
Объект Вложение является конструктором, вы можете «собрать» его так, как вам требуется, используя доступные блоки. Порядок добавления блоков имеет значение.
Примечание: функция 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".
Обработка команд чат-ботом
Для обработки нажатия кнопок клавиатуры, используются команды.
Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register
(чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом "HIDDEN" => "Y").
В кнопке указывается следующие ключи:
"COMMAND" => "page", // команда, которая будет отправлена чат-боту
"COMMAND_PARAMS" => "1", // параметры для команды
Внутри этого события нужно либо создать новое сообщение, либо отредактировать старое (тем самым формируя эффект постраничной навигации).
Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT - это специальный ключ, описывающий в каком контексте была вызвана команда:
если команду написал пользователь самостоятельно, там будет TEXTAREA;
если команда пришла из клавиатуры, то будет KEYBOARD;
если команда пришла из контекстного меню, то будет MENU.
Готовый пример, можно посмотреть в обновленной версии ЭхоБота (bot.php).
Обработка открытия приложения для чата
Приложение для чата, запускаемые из контекстного меню, работают по принципам Контекстного приложения.
Примеры использования клавиатуры
EchoBot
Постраничная навигация, кнопки при вызове команды «Помощь»
Марта
Просто напишите марте Поиграй со мной!. Клавиатура используется как игровое поле:
Giphy
Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему:
Работа с контекстным меню
Контекстное меню
Контекстное меню позволит пользователю взаимодействовать с чат-ботом или приложением для чата из контекстного меню сообщения.
Как добавить свои пункты в контекстное меню
Контекстное меню – это часть сообщения, при создании сообщения нужно добавить ключ MENU и передать параметры.
Примечание: функция 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".
Обработка команд чат-ботом
Для обработки нажатия кнопок клавиатуры и пунктов меню, используются команды.
Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register
(чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом "HIDDEN" => "Y").
В кнопке указывается следующие ключи:
"COMMAND" => "page", // команда, которая будет отправлена чат-боту
"COMMAND_PARAMS" => "1", // параметры для команды
Внутри этого события нужно либо создать новое сообщение, либо отредактировать старое (тем самым формируя эффект постраничной навигации).
Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT - это специальный ключ, описывающий в каком контексте была вызвана команда:
если команду написал пользователь самостоятельно, там будет TEXTAREA;
если команда пришла из клавиатуры, то будет KEYBOARD;
если команда пришла из контекстного меню, то будет MENU.
Обработка открытия приложения для чата
Приложение для чата, запускаемые из контекстного меню, работают по принципам Контекстного приложения.
Bot API
Для работы с Bot API при создании приложения (или загрузке новой версии) нужно указать scope: imbot (Создание и управление чат-ботами).
Работа с чат-ботами
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Для работы ботов должен быть обеспечен доступ к 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"]);
Обязательные поля:
CODE – строковой идентификатор бота, уникальный в рамках вашего приложения.
PROPERTIES – массив с личными данными чат-бота.
EVENT_HANDLER – ссылка на обработчик события отправки сообщения чат-боту.
или
EVENT_MESSAGE_ADD – ссылка на обработчик события отправки сообщения чат-боту.
EVENT_WELCOME_MESSAGE – ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат.
EVENT_BOT_DELETE – ссылка на обработчик события удаления чат-бота со стороны клиента.
Результат выполнения
Числовой идентификатор созданного бота 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', // Ссылка на обработчик события подписки на события удаления сообщений
Ссылка обработчик события невалидная или не указана.
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"]);
Внимание! Все чаты один-на-один данного чат-бота с пользователями будут утеряны.
Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
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"]);
Обязательные поля:
BOT_ID - идентификатор чат-бота, которого нужно изменить.
FIELDS - массив с данными для обновления.
PROPERTIES - массив с личными данными чат-бота.
EVENT_HANDLER - ссылка на обработчик события отправки сообщения чат-боту.
или
EVENT_MESSAGE_ADD - ссылка на обработчик события отправки сообщения чат-боту.
EVENT_WELCOME_MESSAGE - ссылка на обработчик события открытия диалога с чат-ботом или приглашения его в групповой чат.
EVENT_BOT_DELETE - ссылка на обработчик события удаления чат-бота со стороны клиента.
Результат выполнения
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', // Ссылка на обработчик события подписки на события удаления сообщений
Чат-бот не принадлежит этому приложению, работать можно только с чат-ботами, установленными в рамках приложения.
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, такой код должен быть уникален для каждого чат-бота.
preview – превью анимации с фиксированной шириной в 200 px, сокращенная до 6 кадров версия оригинала;
original – полная версия анимации.
Возможные коды ошибок
Ошибки с серверной стороны. Это стандартные ошибки модуля «микросервис», среди которых есть:
LICENSE_NOT_FOUND
WRONG_SIGN
LICENSE_DEMO
LICENSE_NOT_ACTIVE
[/ICO_NEW]
Работа с чатами
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Обратите внимание! Метод указан с использованием функции 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"]);
Обязательные поля:
ENTITY_TYPE - идентификатор произвольной сущности (например CHAT, CRM, OPENLINES, CALL и тд), может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE.
ENTITY_ID - числовой идентификатор сущности, может быть использован для поиска чата и для легкого определения контекста в обработчиках событий ONIMBOTMESSAGEADD, ONIMBOTMESSAGEUPDATE, ONIMBOTMESSAGEDELETE.
Результат выполнения
Возвращает идентификатор чата 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 – идентификатор получателя, если сообщение для приватного диалога
extranet – признак участия в чате внешнего экстранет-пользователя (true/false)
color – цвет чата в формате hex
avatar – ссылка на аватар (если пусто, значит аватар не задан)
type – тип чата (групповой чат, чат для звонка, чат открытой линии и тд)
entity_type – внешний код для чата – тип
entity_id – внешний код для чата – идентификатор
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
date_create – дата создания чата в формате АТОМ
message_type – тип сообщений чата
Пример ответа при возникновения ошибки
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
DIALOG_ID_EMPTY
Не передан идентификатор диалога
ACCESS_ERROR
Текущий пользователь не имеет прав доступа к диалогу
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Работа с сообщениями
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Обратите внимание! Данные методы работы с сообщениями обычно применяются, когда пользователь что-то пишет, поэтому нужно обязательно обрабатывать событие 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.
Чат-бот не принадлежит этому приложению. Работать можно только с чат-ботами, установленными в рамках приложения.
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"]);
Чат-бот не принадлежит этому приложению. Работать можно только с чат-ботами, установленными в рамках приложения.
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"]);
Работают в любом диалоге или любом чате. Пример такой команды (COMMON = Y):
/giphy картинка
Её вызов в любом чате сформирует ответ от чат-бота. Даже в чате, в котором чат-бот не состоит.
Локальные
Работают только в личной переписке с чат-ботом и в групповых чатах, где он есть в участниках. Пример такой команды (COMMON = N):
/help
Её вызов в ЭхоБоте (bot.php) выведет список доступных команд.
Пример «Команды и активные ссылки»
Работа с командами
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Обратите внимание! Для обработки команды нужно, чтобы в приложении была обработка события добавления команды 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_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 или ошибка.
Чат-бот не принадлежит этому приложению. Работать можно только с чат-ботами, установленными в рамках приложения.
MESSAGE_EMPTY
Не передан текст сообщения.
ATTACH_ERROR
Весь переданный объект вложения не прошел валидацию.
ATTACH_OVERSIZE
Превышен максимально допустимый размер вложения (30 Кб).
KEYBOARD_ERROR
Весь переданный объект клавиатуры не прошел валидацию.
KEYBOARD_OVERSIZE
Превышен максимально допустимый размер клавиатуры (30 Кб).
MENU_ERROR
Весь переданный объект меню не прошел валидацию.
MENU_OVERSIZE
Превышен максимально допустимый размер меню (30 Кб).
WRONG_REQUEST
Что-то пошло не так.
Работа с событиями
При генерации события (добавление нового сообщения, открытие диалога с чат-ботом, приглашение чат-бота в чат, удаление чат-бота со стороны клиента) формируется запрос на обработчик события, указанный вами при регистрации бота, подробнее об механизме событий можно почитать тут.
[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 (женский)
)
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Работа с чатами
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Параметры
Параметр
Пример
Обязат.
Описание
Ревизия
TYPE
CHAT
Нет
Тип чата OPEN | CHAT (OPEN - открытый для вступления чат, CHAT - обычный чат по приглашениям, по-умолчанию CHAT)
{
"error": "USERS_EMPTY",
"error_description": "Не переданы участники чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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 то новый пользователь не будет видеть историю.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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] - для открытых линий
Результат выполнения: возвращает идентификатор чата CHAT_ID или null.
im.chat.mute
Отключение уведомлений в чате
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Изменение факта прочтения сообщений: все сообщения после указанного (включая само сообщение) помечаются как непрочитанные.
Обратите внимание! Все вышеперечисленные методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Методы, указанные с использованием javascript-метода BX24.callMethod:
[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
Если не переданы ключи LAST_ID и FIRST_ID, будут загружены последние 20 сообщений чата.
Для загрузки предыдущих 20 сообщений, необходимо передать LAST_ID с идентификатором минимального ID сообщения, полученного из последней выборки.
Если вам необходимо загрузить следующие 20 сообщений, необходимо передать FIRST_ID с идентификатором максимального ID сообщения, полученного из последней выборки.
Если вам необходимо загрузить первые 20 сообщений, необходимо передать FIRST_ID с идентификатором 0, вам будет возвращен результат с самым первым доступным вам сообщением в этом чате.
Обратите внимание! Из-за потенциально большого обьема данных, этот метод не поддерживает стандартную постраничную навигацию Bitrix24 Rest Api.
authorName – имя и фамилия пользователя, загрузившего объект
urlPreview – ссылка на предпросмотр изображения (доступна для картинок)
urlShow – ссылка для перехода к объекту в режиме "просмотра"
urlDownload – ссылка для начала загрузки
chat_id – идентификатор чата
Описание дополнительных параметров:
ATTACH – объект, содержащий богатое оформление
KEYBOARD – объект, содержащий описание клавиатуры
IS_DELETED – флаг, обозначающий, что сообщение удалено
IS_EDITED – флаг, обозначающий, что сообщение отредактировано
FILE_ID – массив идентификаторов файлов
LIKE – массив идентификаторов пользователей, которые проголосовали за сообщение
Пример ответа при возникновении ошибки
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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
Да
Идентификатор последнего прочитанного сообщения в диалоге
counter – кол-во непрочитанных сообщений после выполнения метода
lastId – последнее прочитанное сообщение
Если метод не смог установить новую метку прочтения:
{
"result": false
}
Пример ответа при возникновении ошибки
{
"error": "MESSAGE_ID_ERROR",
"error_description": "Message ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 – идентификатор получателя, если сообщение для приватного диалога
{
"error": "MESSAGE_ID_ERROR",
"error_description": "Message ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 – идентификатор получателя, если сообщение для приватного диалога
Обратите внимание! Все вышеперечисленные методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Методы, указанные с использованием javascript-метода BX24.callMethod:
Создание новых сущностей по сообщению в чате: новый чат, задача, пост в Новостях, событие в календаре.
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'
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Параметры
Параметр
Пример
Обязат.
Описание
Ревизия
MESSAGE_ID
1
Да
Идентификатор сообщения
18
MESSAGE
Текст сообщения
Нет
Текст сообщения. Если передать пустое значение, то сообщение будет удалено
{
"error": "MESSAGE_ID_ERROR",
"error_description": "Не передан идентификатор сообщения"
}
Описание ключей:
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.
{
"error": "MESSAGE_ID_ERROR",
"error_description": "Не передан идентификатор сообщения"
}
Описание ключей:
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
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
MESSAGE_ID_ERROR
Параметр MESSAGE_ID не задан или не является числом
DIALOG_ID_EMPTY
Параметр DIALOG_ID не задан или не соответствует формату
ACCESS_ERROR
Текущий пользователь не имеет прав доступа к чату или диалогу
PARAMS_ERROR
Параметр TYPE не задан или не соответвует имеющимся
Работа с файлами
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Получение информации о папке хранения файлов для чата
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Chat ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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
Для успешного вызова API нужно указать CHAT_ID и одно из двух полей – UPLOAD_ID или DISK_ID.
Обратите внимание! Файл должен быть предварительно загружен через метод disk.folder.uploadfile.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Chat ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Chat ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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.
{
"error": "FILE_ID_EMPTY",
"error_description": "File ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
FILE_SAVE_ERROR
Файл не удалось сохранить
FILE_ID_EMPTY
Не передан идентификатор файла
Работа с пользователями
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Параметры
Параметр
Пример
Обязат.
Описание
Ревизия
ID
5
Нет
Идентификатор пользователя
18
AVATAR_HR
N
Нет
Генерировать аватар в высоком разрешении
18
Если не передан ключ ID, будут выбраны данные для текущего пользователя.
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
departments – идентификаторы подразделения
desktop_last_date – дата последнего действия в десктопном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
phones – массив номеров телефонов: work_phone – рабочий телефон, personal_mobile – мобильный телефон, personal_phone – домашний телефон
Пример ответа при возникновении ошибки
{
"error": "ID_EMPTY",
"error_description": "User ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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
Если не передан ключ ID, будут выбраны данные для текущего пользователя.
Обратите внимание! Метод указан с использованием функции 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.
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Работа с подразделениями
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Примечание: Методы im.department.* доступны только для [ds]интранет-пользователей[/ds][di]
В Битрикс24 различают два вида пользователей:
интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);
экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Примечание: Метод im.department.get доступен только для [ds]интранет-пользователей[/ds][di]
В Битрикс24 различают два вида пользователей:
интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);
экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
Пример ответа при возникновении ошибки
{
"error": "INVALID_FORMAT",
"error_description": "A wrong format for the ID field is passed"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 различают два вида пользователей:
интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);
экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).
Если передан параметр USER_DATA = Y, то в ответе вместо массива идентификаторов будет передан массив объектов с информацией о пользователе.
Метод поддерживает стандартную постраничную навигацию Bitrix24 Rest Api, но в добавок к ней есть возможность построить навигацию с помощью параметров OFFSET и LIMIT.
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
desktop_last_date – дата последнего действия в десктопном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
phones – массив номеров телефонов: work_phone – рабочий телефон, personal_mobile – мобильный телефон, personal_phone – домашний телефон
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 различают два вида пользователей:
интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);
экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
desktop_last_date – дата последнего действия в десктопном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
phones – массив номеров телефонов: work_phone – рабочий телефон, personal_mobile – мобильный телефон, personal_phone – домашний телефон
Пример ответа при возникновении ошибки
{
"error": "ID_EMPTY",
"error_description": "Department ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 различают два вида пользователей:
интранет-пользователи – внутренние пользователи (сотрудники Вашей компании);
экстранет-пользователи – внешние пользователи (поставщики, дистрибьюторы и т.п.).
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
desktop_last_date – дата последнего действия в десктопном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
phones – массив номеров телефонов: work_phone – рабочий телефон, personal_mobile – мобильный телефон, personal_phone – домашний телефон
Пример ответа при возникновении ошибки
{
"error": "ID_EMPTY",
"error_description": "Department ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
ID_EMPTY
Не передан список идентификаторов
Работа с поиском
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
[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
Поиск осуществляется по следующим полям: Имя, Фамилия, Должность, Подразделение.
Метод поддерживает стандартную постраничную навигацию Bitrix24 Rest Api, но в добавок к ней есть возможность построить навигацию с помощью параметров OFFSET и LIMIT.
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
desktop_last_date – дата последнего действия в десктопном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
Пример ответа при возникновении ошибки
{
"error": "FIND_SHORT",
"error_description": "Too short a search phrase."
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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
Поиск осуществляется по следующим полям: Заголовок, Имя и Фамилия участников чата.
Метод поддерживает стандартную постраничную навигацию Bitrix24 Rest Api, но в добавок к ней есть возможность построить навигацию с помощью параметров OFFSET и LIMIT.
avatar – ссылка на аватар (если пусто, значит аватар не задан)
type – тип чата (групповой чат, чат для звонка, чат открытой линии и тд)
entity_type – внешний код для чата – тип
entity_id – внешний код для чата – идентификатор
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
date_create – дата создания чата в формате АТОМ
message_type – тип сообщений чата
Пример ответа при возникновении ошибки
{
"error": "FIND_SHORT",
"error_description": "Too short a search phrase."
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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
Если передан параметр USER_DATA = Y, то к результату будут подгружены данные о руководителе.
Поиск осуществляется по следующим полям: Полное название подразделения.
Метод поддерживает стандартную постраничную навигацию Bitrix24 Rest Api, но в добавок к ней есть возможность построить навигацию с помощью параметров OFFSET и LIMIT.
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
Пример ответа при возникновении ошибки
{
"error": "FIND_SHORT",
"error_description": "Too short a search phrase."
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
FIND_SHORT
Слишком короткая поисковая фраза, поиск осуществляется от трех символов.
im.search.last.get
Получение списка элементов последнего поиска
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 18
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
chat – объект описания данных чата (не доступно, если это тип записи – пользователь):
id – идентификатор чата
title – название чата
owner – идентификатор пользователя владельца чата
extranet – признак участия в чате внешнего экстранет-пользователя (true/false)
color – цвет чата в формате hex
avatar – ссылка на аватар (если пусто, значит аватар не задан)
type – тип чата (групповой чат, чат для звонка, чат открытой линии и тд)
entity_type – внешний код для чата – тип
entity_id – внешний код для чата – идентификатор
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
date_create – дата создания чата в формате АТОМ
message_type – тип сообщений чата
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 – идентификатор получателя, если сообщение для приватного диалога
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 – идентификатор получателя, если сообщение для приватного диалога
Обратите внимание! Все вышеперечисленные методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Методы, указанные с использованием javascript-метода BX24.callMethod:
Получение списка последних диалогов пользователя (с поддержкой пагинации).
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
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, false)
chat – объект описания данных чата (не доступно, если это тип записи – пользователь):
id – идентификатор чата
title – название чата
owner – идентификатор пользователя владельца чата
extranet – признак участия в чате внешнего экстранет-пользователя (true/false)
color – цвет чата в формате hex
avatar – ссылка на аватар (если пусто, значит аватар не задан)
type – тип чата (групповой чат, чат для звонка, чат открытой линии и тд)
entity_type – внешний код для чата – тип
entity_id – внешний код для чата – идентификатор
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
date_create – дата создания чата в формате АТОМ
message_type – тип сообщений чата
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
Если указать параметр PIN = N, то закрепленный диалог будет откреплен.
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
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 – идентификатор получателя, если сообщение для приватного диалога
connector – признак пользователя открытых линий (true/false)
external_auth_id – код внешней авторизации
status – выбранный статус пользователя
idle – дата, когда пользователь отошел от компьютера, в формате АТОМ (если не задано, то false)
last_activity_date – дата последнего действия пользователя в формате АТОМ
mobile_last_date – дата последнего действия в мобильном приложении в формате АТОМ (если не задано, то false)
absent – дата, по какое число у пользователя отпуск, в формате АТОМ (если не задано, то false)
chat – объект описания данных чата (не доступно, если это тип записи – пользователь):
id – идентификатор чата
title – название чата
owner – идентификатор пользователя-владельца чата
extranet – признак участия в чате внешнего экстранет-пользователя (true/false)
color – цвет чата в формате hex
avatar – ссылка на аватар (если пусто, значит, аватар не задан)
type – тип чата (групповой чат, чат для звонка, чат открытой линии и т.д.)
entity_type – внешний код для чата – тип
entity_id – внешний код для чата – идентификатор
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
date_create – дата создания чата в формате АТОМ
message_type – тип сообщений чата
pinned – закреплен чат или нет
unread – стоит ли ручная метка о том, что чат не прочитан
date_update – дата последнего изменения в связанных сущностях
Работа со счетчиками
Обратите внимание! Все методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24. Он есть в ЭхоБоте и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
CHAT – объект, содержащий список чатов, в которых есть непрочитанные сообщения
DIALOG – объект, содержащий список диалогов, в которых есть непрочитанные сообщения
LINES – объект, содержащий список чатов открытых линий, в которых есть непрочитанные сообщения
TYPE – объект, содержит суммарные счетчики
ALL – суммарный счетчик всех сущностей
CHAT – суммарный счетчик чатов
DIALOG – суммарный счетчик диалогов
LINES – суммарный счетчик открытых линий
NOTIFY – суммарный счетчик уведомлений
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Обратите внимание! Все вышеперечисленные методы указаны с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Методы, указанные с использованием javascript-метода BX24.callMethod:
[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
Нет
Тег уведомления, уникальный в рамках системы. При добавлении уведомления с существующим тегом другие уведомления будут удалены
Результат выполнения: идентификатор уведомления ID или ошибка.
Пример ответа при возникновении ошибки
{
"error": "USER_ID_EMPTY",
"error_description": "Идентификатор получателя не задан"
}
Описание ключей:
error – код возникшей ошибки
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
Нет
Тег уведомления, уникальный в рамках системы. При добавлении уведомления с существующим тегом другие уведомления будут удалены
Результат выполнения: идентификатор уведомления ID или ошибка.
Пример ответа при возникновении ошибки
{
"error": "USER_ID_EMPTY",
"error_description": "Идентификатор получателя не задан"
}
Описание ключей:
error – код возникшей ошибки
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 (дополнительный тег).
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
Если параметр ONLY_CURRENT передан как Y, отметка о прочтении будет установлена только для указанного ID. Иначе отметка проставится для уведомления, равным или больше указанного ID.
Важно! Описанный в данной главе формат встраивания в чат приложений на текущий момент работает корректно, однако в дальнейшем для Нового чата нужно будет встраивать приложения в формате [ds]Rest Placement[/ds][di]
В Новом чате реализован единый для всего продукта Rest Placement (места для встраивания Rest-приложений).
В рамках Нового чата есть несколько точек встраивания.
У разработчиков появилась возможность встраиваться в Мессенджер, добавив свою иконку в панель ввода текста:
Если приложение не загрузит картинку, будет выведена служебная иконка Приложения для чата, по клику на которую будет показан текстовый вариант иконки.
Приложение для чата бывает двух типов - JS команда или IFRAME приложение.
JS команда
При нажатии на иконку будет вставлена команда для чат-бота в поле ввода, либо отправлена команда в чат, либо начнется телефонный звонок, либо откроется открытая линия поддержки.
С помощью этого формата, разработчики в своих чат-ботах могут сделать кнопку для связи с ними.
Пример такой команды для чат-бота Марта - там появится иконка для игры в крестики нолики:
IFRAME приложение
Это улучшенный формат, при нажатии на иконку, будет открыто IFRAME приложение, в котором разработчик сможет сделать все, что пожелает.
Приложение может взаимодействовать с чатом c помощью JS-команд:
для вставки сообщения в поле ввода
для отправки сообщения от лица пользователя
для закрытия диалога
открытия чата технической поддержки (консультант ОЛ)
совершения звонка
Пример такой реализации вы можете увидеть на примере чат-бота GIphy:
Прочувствуйте разницу - раньше вы писали команду в виде сообщения, и GIphy выдавал вам случайную картинку по теме. Теперь вы видите то, что отправляете.
Обратите внимание, иконки умеют понимать контекст, а это значит, что приложение может отображаться только в тех чатах, в которых вам это требуется.
Например, для связи с техподдержкой приложение правильнее будет разместить в контексте вашего чат-бота, ведь в других чатах она будет лишней. Либо вы можете сделать специальное приложение для открытых линий - оно должно показываться только в контексте открытых линий.
Доступные контексты: all, chat, bot, lines, user, call.
К каждому контексту можно добавить постфикс -admin - тогда иконка будет показана в нужном контексте только администраторам.
Контекстные приложения
Контекстные приложения созданы для того, чтобы помогать взаимодействовать пользователю с чат-ботом в рамках конкретного диалога (сообщения).
Например, клиент пишет в открытую линию, чат-бот для открытых линий анализирует сообщение и подготавливает варианты ответа. Чтобы не мешать операторам работать и не показывать ему весь поток информации, мы аккуратно формируем кнопку, по нажатию на которую откроется IFRAME приложение.
$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:
PUT - вставка команды чат-боту в textarea, JS_PARAM может содержать только текст команды и параметры к ней (разрешенные символы: a-z 0-9 - + _ / ).
SEND - отправка команды чат-боту, JS_PARAMможет содержать только текст команды и параметры к ней (разрешенные символы a-z 0-9 - + _ / ).
CALL - вызов телефонного номера.
SUPPORT - открытие чат-бота техподдержки работающего через Открытые линии, в JS_PARAM необходимо указать код открытой линии (32 символа).
Формат иконки ICON_FILE:
В данное поле необходимо передать base64 от вашей иконки, формат иконки подробно описан в документации.
Обратите внимание, если данное поле не указано, то приложение будет доступно в системном диалоге "Приложения для чата".
Контекст CONTEXT указывает, где будет доступно приложение:
ALL – во всех чатах.
USER – только в чатах Один-на-один.
CHAT – только в групповых чатах.
BOT – только у чат-бота, который установил приложение.
LINES – только в чатах Открытых линий.
CALL – только в чатах, созданных в рамках Телефонии.
К каждому контексту можно добавить постфикс -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"]);
Обратите внимание:
Хоть вы при регистрации IFRAME-приложения и задаете размеры окна, оно может быть уменьшено приложением по фактически доступным размерам. Идеальный вариант – делать таким образом, чтобы оно вписывалось в минимальные размеры и могло свободно адаптироваться к увеличению и уменьшению, это будет очень важно для мобильных устройств.
Cсылка на IFRAME обязательно должна вести на сайт с активным HTTPS-сертификатом. Правила разработки IFRAME-обработчика и ограничения вы можете прочитать в документации.
Обязательно используйте проверки хешей перед выполнением любых операций.
Приложения доступны только после перезагрузки страницы или после служебного хита на сервер (на разных установках по разному, от 15 до 26 минут). Приложение появится мгновенно только при взаимодействии с контекстной кнопкой.
В значения IFRAME_WIDTH и IFRAME_HEIGHT вы указываете желаемые значения ширины и высоты окна приложения. Окно приложения будет уменьшено до размера окна мессенджера, если окно мессенджера окажется меньше. Если же, наоборот, больше, то будут использованы желаемые размеры для приложения.
В случае вызова приложения из контекста (клавиатура или меню), оно будет вызвано в контекстном режиме. В этом режиме значение 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
Что-то пошло не так.
Контекстные приложения
О том, что такое контекст-приложения можно прочитать здесь.
Для работы с контекстом, вам необходимо выполнить несколько действий:
Зарегистрировать приложение. Вы можете зарегистрировать скрытое приложение, тогда оно не будет отображаться на панели ввода текста.
Для загрузки картинки, при регистрации или обновлении приложения вам необходимо передавать ключ IMAGE_FILE. Значение этого ключа должно быть base64 от вашей картинки:
Обратите внимание, вы можете и не создавать иконку для приложения, тогда оно будет сгруппировано в служебную кнопку:
Cоздание IFRAME-обработчика
IFRAME-обработчик
После регистрации приложения для чата, вам необходимо сделать IFRAME-обработчик.
Обратите внимание, что, хотя вы при регистрации и задаете размеры окна, оно может быть уменьшено приложением по фактически доступным размерам. Идеальный вариант - делать приложение таким образом, чтобы оно вписывалось в минимальные размеры и могло свободно адаптироваться к увеличению и уменьшению, это будет очень важно для мобильных устройств.
BOT_ID и BOT_CODE - данные о чат-боте, под которым запущено приложение.
APP_ID и APP_CODE - данные приложении для чата запущенного приложения.
DOMAIN - адрес портала, с которого запустили приложение.
DOMAIN_HASH - это поле HASH, переданное при регистрации иконки. Используются для отсечения неавторизованных запросов.
USER_ID - идентификатор пользователя.
USER_HASH - хеш-строка для валидации корректности запросов на портале клиента.
DIALOG_ID - идентификатор запущенного диалога у пользователя в момент открытия фрейма.
CONTEXT - это контекст вызова диалога, может быть textarea или button.
LANG - текущий язык интерфейса клиента.
IS_CHROME - запущен ли данный фрейм в браузере Google Chrome или нет.
DIALOG_CONTEXT - данный параметр пока недоступен. Может быть all, chat, bot, lines, user, call .
DIALOG_ENTITY_ID - дополнительные данные о чате (данный параметр пока недоступен). Для Открытых линий данные разделены |. Значение полей для Открытых линий: 1 - канал, через который пользователь написал, 2 - идентификатор ОЛ, 3 и 4 - служебные данные (параметр пока недоступен).
DIALOG_ENTITY_DATA_1 - дополнительные данные о чате (данный параметр пока недоступен). Для Открытых линий данные разделены |. Значение полей для Открытых линий: 1 - сохранен в CRM, 2 - тип сущности CRM, 3 - идентификатор сущности CRM, 4 и 5 - служебные данные, 6 - идентификатор сессии открытой линии.
Если фрейм запущен в режиме контекста:
MESSAGE_ID - идентификатор сообщения.
BUTTON_PARAMS - параметр кнопки, заданный при отправке.
Взаимодействие с родительским
окном (с мессенджером)
Вам необходимо сделать функции взаимодействия с основным окном, инициализацией и отправкой данных.
Примеры реализации:
<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>
После этого вам будут доступны следующие функции:
Команда отправки текст от лица пользователя: frameCommunicationSend({'action': 'send', 'message': 'Send message'})
Команда вставки текста в поле ввода: frameCommunicationSend({'action': 'put', 'message': 'Put message'})
Команда начала звонка: frameCommunicationSend({'action': 'call', 'number': '123456'})
Команда открытия диалога с вашей открытой линией: frameCommunicationSend({'action': 'support', 'code': '6a4cdbcf753addac1a573ea64be826ca'})
Команда закрытия фрейма: frameCommunicationSend({'action': 'close'})
Регистрация и безопасность
Вы можете не проверять входящие запросы, но мы настоятельно рекомендуем это делать.
На основе входящих данных вы можете реализовать необходимые проверки:
Рекомендуем проверять REFERER на совпадение с указанным доменом.
Рекомендуем проверять домен и хеш от него.
Рекомендуем проверять пользователя и хеш от него.
Используйте уникальный 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 / не для перепродажи) – бесплатная лицензия на определенный период, предназначенная для ознакомления с программой и тестовых развёртываний программы.
Предыдущий формат встраивания в чат приложений был реализован ещё до создания единого для всего продукта формата Rest Placement (места для [ds]встраивания[/ds][di]
Ваше приложение может добавлять функционал в специальные отведенные области стандартного интерфейса: карточки объектов CRM, различные списки элементов и т.д.
Для этого установите обработчик места встраивания при помощи placement.bind. Одно приложение может установить произвольное число обработчиков, даже для одного и того же места встраивания (например, если вам нужно добавить несколько разных операций в контекстное меню лида в CRM).
После выхода формата Rest Placement разработчикам для одинаковой задачи "встроиться в продукт" нужно было изучить два разных формата реализации ([ds]старый формат[/ds][di]
Разработчики могут встраиваться в Мессенджер, добавив свою иконку в панель ввода текста.
Приложение для чата бывает двух типов - JS команда или IFRAME приложение.
Подробнее...[/di] для чатов и новый – для остальных сущностей), а поддерживать в одном приложении несколько вариантов довольно сложно.
Поэтому в Новом чате, который станет доступен клиентам чуть позже в 2023 году, реализован единый для всего продукта Rest Placement.
В рамках Нового чата есть несколько точек встраивания:
IM_NAVIGATION – приложение для левого меню навигации (по сути, это приложение внутри окружения чата без встраивания непосредственно в чат);
IM_TEXTAREA – приложение для панели над полем ввода (данный формат был и раньше – это генерация контента в момент написания сообщения);
IM_SIDEBAR – приложение для сайдбара (можно создавать приложения, добавляющие дополнительные сценарии для чата – например, отдельный диск для чата или базу знаний);
IM_CONTEXT_MENU – приложение для открытия контекстного меню сообщения внутри чата, встраивание в пункт "Создать контент на основании" (аналогом является "Создать задачу” или "Создать встречу" на основании сообщения);
IM_SMILES_SELECTOR – приложение для расширения возможностей смайлов и giphy (тут могут быть свои источники картинок или смайлов).
Общая информация по всем точкам встраивания
Приложения для Нового чата
Все встраивания являются стандартным форматом и регистрируются с помощью метода placement.bind. Пример:
iconName – иконка приложения (это код из библиотеки Font Awesome 6.0). Иконка выводится везде, кроме контекстного меню и селектора смайлов;
context – контекст отрисовки приложения. Есть возможность сделать показ приложения только для определенных типов чатов (по умолчанию активно для всех типов чатов);
Примечание: Опция ALL имеет высший приоритет над всеми остальными опциями, поэтому нет смысла перечислять другие типы чатов вместе с ней. Если же такое произошло, то значения конкретных типов чатов будут проигнорированы. При этом неверное значение одной из переданных опций всё равно выдаст ошибку при регистрации приложения.
role – роль пользователя, для которой будет показываться это приложение (по умолчанию USER – доступно всем);
extranet – доcтупно ли приложения для [ds]экстранет-пользователей[/ds][di]
«Экстранет» позволяет компании осуществлять конфиденциальную связь с поставщиками, дистрибьюторами и другими внешними пользователями без доступа к внутрикорпоративной информации.
Внешние пользователи (экстранет-пользователи) не имеют доступа внутрь вашего Битрикс24, не видят структуру и любую другую информацию компании, они могут работать только в специальных экстранет-группах или проектах.
Рекомендуемая ширина фрейма как в старом чате (по умолчанию 100).
height
Нет
Рекомендуемая высота фрейма как в старом чате (по умолчанию 100).
extranet
Нет
Доступно ли приложение для экстранет-пользователей (по умолчанию N). Поддерживает следующие значения:
N – приложение недоступно для экстранет-пользователей;
Y – приложение доступно для экстранет-пользователей.
В данном встраивании доступен текущий контекст открытия, будет передан dialogId текущего чата.
const context = BX24.placement.info().options;
Будет открыт IFRAME приложения с заданными размерами. Если вы укажете размер приложения больше, чем может быть показан, то этот размер автоматически будет уменьшен (ваше приложение должно это учитывать).
Rest API бот-платформы являются составной частью общей системы REST. Документация по всем остальным методам расположена в [ds]Документации REST API[/ds][di] Битрикс24 - программный продукт в виде облачного сервиса, а также коробочной версии, созданный компанией "1С-Битрикс".
Разработчики могут создавать собственные приложения или интеграции для Битрикс24, используя открытый REST API, который работает как с облачным, так и с коробочным Битрикс24, начиная с версии 16.6.0.
Rest API предназначено для создания приложений для облачного сервиса Битрикс24.
Rest API позволяет получить доступ и управлять такими инструментами облачного сервиса Битрикс24 как:
CRM,
Бизнес-процессы,
Диск,
Социальная сеть,
Телефония,
Универсальные списки,
Хранилища данных (инфоблоки),
Уведомления,
Задачи,
работа с пользователями и с подразделениями,
Живая лента,
Календари.
Для использования методов Rest API внешними приложениями приложение должно быть зарегистрировано в Маркетплейсе. В этом случае у приложения есть все необходимые данные для получения ключа OAuth 2.0.
где транспорт - необязательный параметр, который может иметь значения 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.
Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
Версия платформы
imopenlines.revision.get – получение информации о ревизиях API Открытых линий
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 2
Обратите внимание! Метод указан с использованием функции restCommand - это метод отправки данных в Битрикс24, данный метод есть в примере ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод BX24.callMethod или bitrix24-php-sdk.
Работа с открытыми линиями
Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
Отправка сообщения от лица открытой линии выбранному пользователю.
imopenlines.network.join
Подключение открытой линии по коду
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1
Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
{
"error": "NOT_FOUND",
"error_description": "Openline is not found"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
IMBOT_ERROR
Не установлен модуль по управлению ботами
NOT_FOUND
Открытая линия не найдена
INACTIVE
Открытая линия в данный момент недоступна
Работа с диалогами
Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
Получение информации о диалоге (чате) оператора открытой линии.
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
Можно использовать для вызова любой из параметров.
avatar – ссылка на аватар (если пусто, значит аватар не задан)
color – цвет чата в формате hex
date_create – дата создания чата в формате АТОМ
dialog_id – идентификатор диалога
entity_data_1 – внешние данные для чата
entity_data_2 – внешние данные для чата
entity_data_3 – внешние данные для чата
entity_id – внешний код для чата – идентификатор
entity_type – внешний код для чата – тип
extranet – признак участия в чате внешнего экстранет-пользователя (true/false)
id – идентификатор чата
manager_list – список операторов
message_type – тип сообщений чата
name – название открытой линии
owner – идентификатор пользователя-владельца чата
type – тип чата (групповой чат, чат для звонка, чат открытой линии и тд)
Пример ответа при возникновении ошибки
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
Описание ключей:
error – код возникшей ошибки
error_description – краткое описание возникшей ошибки
Возможные коды ошибок
Код
Описание
DIALOG_ID_EMPTY
Не передан идентификатор диалога
ACCESS_ERROR
Текущий пользователь не имеет прав доступа к диалогу
Работа с чат-ботами
Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
Метод отправки чат-ботом автоматического сообщения.
imopenlines.bot.session.operator
Переключение разговора на свободного оператора
[dw]Ревизия[/dw][di]Получить информацию о текущей ревизии API (версии платформы) – im.revision.get[/di]: 1
Внимание! Для использования методов IMOPENLINES REST необходимо помимо прав на imbot (Создание и управление чат-ботами) иметь доступ к scope imopenlines (Открытые линии).
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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 для переключения на другую открытую линию.
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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 (Открытые линии).
{
"error": "CHAT_ID_EMPTY",
"error_description": "Не передан идентификатор чата"
}
Описание ключей:
error – код возникшей ошибки
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 - обычное сообщение. По умолчанию, пустое значение
где: Первый параметр – это название API (imbot.message.add); Второй параметр – это передаваемые данные в API (Array(...)) Третий параметр – это данные для авторизации запроса ($_REQUEST["auth"]).
Интерфейс REST API позволяет устанавливать свои обработчики серверных событий.
Обработчиком события служит URL, который будет вызван после того, как пользователь произведет запрошенное действие на портале Битрикс24, на котором установлено приложение.
Обработчик получает на вход следующие данные:
event – имя сработавшего события.
data – массив данных события.
auth – набор данных для авторизации.
Обработчик может:
Использовать полученные данные авторизации для выполнения запросов к REST API.
Быть установлен только пользователем с правами администрирования портала.
Внимание! Если обработчику требуется обращение к Rest API для работы с данными, то настоятельно рекомендуется использовать для этого данные авторизации сохраненные на стороне приложения, а не опираться на получение access_token, так как его может и не быть.
При установке события можно указать пользователя, под которым будет авторизовываться обработчик. По умолчанию обработчику будет выдана авторизация пользователя, действия которого привели к срабатыванию события.
Обработчик события будет вызван не сразу после срабатывания, а через некоторое время, зависящее от нагрузки.
Список доступных событий можно получить при помощи REST-метода events.
Установка обработчика
Установка обработчика события производится:
при помощи REST-метода event.bind на основе restCommand:
Получение списка зарегистрированных обработчиков событий производится при помощи REST-метода events.get.
Снятие зарегистрированного обработчика производится при помощи REST-метода event.unbind или при помощи функции BX24.callUnbind js-библиотеки.
Для доступа к каждому событию при регистрации версии приложения должно быть запрошено соответствующее право доступа.
Приложение может установить произвольное количество обработчиков одного и того же события, но все обработчики должны быть установлены с авторизацией различных пользователей. Кроме того, вызов обработчика может зависеть от доступа пользователя, чья авторизация будет выдана обработчику.
Имена событий регистронезависимы.
Внимание! При деинсталляции приложения или при установке новой версии все обработчики событий, установленные приложением, будут удалены.
События установки и обновления
Во время установки и обновления приложения используются 2 события: ONAPPINSTALL и ONAPPUPDATE. Оба события имеют одинаковый набор данных, а отличаются лишь параметром - [PREVIOUS_VERSION] => 1, в котором указывается старая версия приложения.
Событие на установку
приложения 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 // Ключ для продления авторизации
)
Событие на обновление
приложения 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 // Ключ для продления авторизации
)
Обратите внимание! В базовом варианте работы с чат-ботом, поля expires_in, member_id, refresh_token - не требуются. Но, если для вашего приложения это необходимо, то прочитать, как с ними работать можно тут. Пример бота содержит возможность продления.
JS-методы для iframe-приложений
В рамках iframe-приложений вы можете использовать методы, такие как открытие диалога с пользователями или управления размерами окна.
Для работы с веб-мессенджером существуют следующие функции: