Кастомные блоки

Кастомные блоки позволяют создавать пользовательские решения в диалогах, независимо от команды разработки.

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

Блоки, которые были созданы и доступны для всех инстансов – глобальные блоки. Их редактирование и удаление невозможно. Вы можете только установить их на инстанс или деинсталлировать.

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

редактирование;
деинсталляция;
повторная установка;
экспорт;
удаление.

Последовательность работы с кастомным блоком

Найти кастомный блок

Чтобы найти кастомный блок, вы можете отфильтровать все блоки раздела по параметрам, либо найти его по названию.

Чтобы отфильтровать блоки, выберите параметры на панели фильтрации:

Категория – каждому блоку при создании присваивается категория, чтобы было проще ориентироваться в большом количестве блоков. Отметьте категории, котоые вас интересуют, в списке. Всем блокам, которые были созданы до релиза 1.29.00, присвоена категория Misc. Для отмены фильтрации по этому параметру выберите Все категории.
Тип – позволяет посмотреть, какие блоки созданы и доступны только на этом инстансе (локальные), а какие – на всех инстансах (глобальные). Для отмены фильтрации по этому параметру выберите Все блоки.
Статус – позволяет посмотреть только установленные или, наоборот, только неустановленные блоки. Для отмены фильтрации по этому параметру выберите Все статусы.

Чтобы найти блок по названию или описанию, используйте поле Поиск.

Фильтры можно использовать как по отдельности, так и совместно.

Для сброса всех параметров фильтрации, нажмите кнопку Сбросить справа.

В каких ботах используется кастомный блок

Чтобы узнать, в каких ботах используется кастомный блок:

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

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

Установить блок

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

Рисунок 1. Установка блока на инстанс

После установки кнопка изменится на отметку Установлен.

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

Создать кастомный блок

Чтобы добавить новый кастомный блок, нажмите кнопку Создать .

Откроется форма Новый кастомный блок.

Укажите параметры блока:

Название – обязательное поле, может повторяться. Справа в этом же поле отображается эмоджи блока, выбранная рандомно системой. Вы можете изменить эмоджи. Для этого нажмите на изображение и выберите эмоджи.
Категория – категория нужна, чтобы было проще ориентироваться в большом количестве блоков. Вы можете выбрать существующую категорию в списке или создать новую – для этого просто впишите категорию в поле. Обязательное поле.
Внешний веб-сервис – установите флаг, если для работы блока нужно задействовать процессы внешнего сервиса.
URL – поле отображается, если установле флаг Внешний веб-сервис. Адрес внешнего веб-сервиса для обработки кастомного блока.
Описание – описание блока будет отображаться на карточке блока в разделе Кастомные блоки. Обязательное поле. Максимальный размер текста – 128 символов.

После заполнения всех полей нажмите кнопку Создать.

Откроется редактор блока, который содержит три вкладки:

Интерфейс;
Код;
Настройки.

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

Интерфейс

На вкладке Интерфейс пропишите манифест блока в формате JSON, который будет определять внешний вид блока в конструкторе бота. В манифесте нужно описать все секции sections и поля fields, которые в них содержатся. Эти поля в редакторе бота будет заполнять пользователь, который добавит блок в на схему бота.

Пример манифеста блока

{
    "sections": [
        {
            "title": "Выбор валюты",
            "name": "currency",
            "fields": [
                {
                    "title": "Код валюты (трехбуквеный код)",
                    "name": "currency_code",
                    "type": "text",
                    "defaultValue": "USD"
                }
            ]
        },
        {
            "title": "Настройка блока",
            "name": "block_settings",
            "fields": [
                {
                    "title": "Название переменной для результата",
                    "name": "result_var_name",
                    "type": "text",
                    "defaultValue": null
                }
            ]
        }
    ]
}

Таблица 1. Доступные типы данных:
Тип данных	Прописывается на вкладке	Описание
Teкст	`"type": "text",`	Текстовые данные. Пользователь в диалоге может вводить любые данные, они будут восприниматься блоком как строка.
Числа	`"type": "number",`	Целые и десятичные числа. Поле принимает значения как из переменной, так и вручную. Если типы не совпадают, то блок исполняется с передачей этой переменной как null.
Дата	`"type": "date",`	Строковое представление даты или объект Date. Поле принимает значения как из переменной, так и вручную. Если типы не совпадают, то блок исполняется с передачей этой переменной как null.
Файл	`"type": "file",`	Передача в блок файла. Поле принимает значения только из переменной. Так как файл приходит из переменной, то ограничения на тип и объем файла отрабатывают в момент добавления файла. Если типы не совпадают, то блок исполняется с передачей этой переменной как null. В переменной передается только один файл. Если в переменной собран массив файлов, то обрабатывается только первый файл из массива.

Код

На вкладке Код напишите js-код для обработки бизнес-логики кастомного блока.

Пример кода кастомного блока

let key = data.activity.currency_code.value;
context.test = key;

let result = '';

let res = fetch({
    "url": 'https://www.cbr-xml-daily.ru/daily_json.js',
    "method": 'GET'
});

let cur_data = JSON.parse(res.body);


let hasKey = key in cur_data.Valute;
if(hasKey) {
    let diff = (cur_data.Valute[key].Value - cur_data.Valute[key].Previous).toFixed(4);
    cur_data.Valute[key].Diff = (diff>=0) ? '+'+diff : diff;
    result = cur_data.Valute[key];
    context[data.activity.result_var_name.value] = result.Nominal+' '+result.Name+' сегодня стоит '+result.Value+' ('+result.Diff+')';
} else {
    result = 'Код валюты неверный';
    context[data.activity.result_var_name.value] = result;
}

BotOne.completion();

Структура данных на вкладке Код

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

Данные Массив Описание

Данные	Массив	Описание
`data`		Массив, содержит данные по активному диалогу (данные блока, диалога, входящих и исходящих сообщений)
	`data.activity`	Данные, заполненные на боковой панели блока в редакторе бота. В массив не попадают данные: незаполненные поля поля с типом variable (в эти переменные будет записан результат выполнения кастомного блока) Этот массив принимает данные двух типов – `text` и `select` Структура text: key: { // Строковый ключ поля заданный в манифесте блока 'value': string // значение из поля в редакторе блока с учетом преобразования переменных } Структура select: key: { // Строковый ключ поля заданный в манифесте блока 'value': string // выбранное значение из списка 'text': string // выбранное значение из списка с учетом преобразования переменных }
	`data.bot_message`	В данный массив будут записаны данные последнего отправленного сообщения сообщений из бота. Структура: "bot_message": { "message_id": int, // идентификатор сообщения "created_at": timestamp, // дата создания сообщения "type": string, // тип сообщения "payload": { "message": string // текст сообщения } } В данный момент из блока можно отправлять только текстовые сообщения. Его `type=message`
	`data.user_message`	В данный массив будут записаны данные отправленного сообщения респондентом. Структура: "user_message": { "message_id": int, // идентификатор сообщения "created_at": timestamp, // дата создания сообщения "type": string, // тип сообщения "payload": { "message": string // текст сообщения } } В данный момент кастомный блок может принимать от респондента только текстовые сообщения. Его `type=message`
	`data.dialog`	Данные диалога: "dialog": { "id": int, // идентификатор диалога "locale": string // локаль диалога }
`context`		Обращение к переменным бота. Например, `context.formOneVariable`.

data

Массив, содержит данные по активному диалогу (данные блока, диалога, входящих и исходящих сообщений)

data.activity

Данные, заполненные на боковой панели блока в редакторе бота.

В массив не попадают данные:

незаполненные поля
поля с типом variable (в эти переменные будет записан результат выполнения кастомного блока)

Этот массив принимает данные двух типов – text и select

Структура text:

key: { // Строковый ключ поля заданный в манифесте блока
'value': string // значение из поля в редакторе блока с учетом преобразования переменных
}

Структура select:

key: { // Строковый ключ поля заданный в манифесте блока
'value': string // выбранное значение из списка
'text': string // выбранное значение из списка с учетом преобразования переменных
}

data.bot_message

В данный массив будут записаны данные последнего отправленного сообщения сообщений из бота.

Структура:

"bot_message": {
  "message_id": int, // идентификатор сообщения
  "created_at": timestamp, // дата создания сообщения
  "type": string, // тип сообщения
  "payload": {
    "message": string // текст сообщения
  }
}

В данный момент из блока можно отправлять только текстовые сообщения. Его type=message

data.user_message

В данный массив будут записаны данные отправленного сообщения респондентом.

Структура:

"user_message": {
  "message_id": int, // идентификатор сообщения
  "created_at": timestamp, // дата создания сообщения
  "type": string, // тип сообщения
  "payload": {
    "message": string // текст сообщения
  }
}

В данный момент кастомный блок может принимать от респондента только текстовые сообщения. Его type=message

data.dialog

Данные диалога:

"dialog": {
  "id": int, // идентификатор диалога
  "locale": string // локаль диалога
}

context

Обращение к переменным бота. Например, context.formOneVariable.

Чтобы указать боту, как и какие данные опубликовать в диалоге, используйте команду BotOne.sendTextMessage с двумя параметрами:

text – текст сообщения (string|required|min:1|max:4096 )
typing – отображать тайпинг после отправки сообщения или нет (true|false)

Пример:

// Отправка текстового сообщения от бота, тайпинг отображается
BotOne.sendTextMessage('Ваши данные:', true);

// Отправка текстового сообщения с полученными данными, тайпинг не отображается
BotOne.sendTextMessage('Страна: ' + data.activity.country1.text, false);

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

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

Настройки

На вкладке Настройки вы можете просмотреть и изменить свойства блока. Все настройки на вклакде такие же, как при создании блока.

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

Кнопка доступна, если:

Было внесено изменение хотя бы в одно свойство блока в редакторе.
Если указаны все обязательные свойства блока.

Note	Любой новый созданный блок устанавливается атоматически.

Внешний и внутренний кастомный блок

Кастомный блок может выполняться:

На сервере Bot.one — внутренний кастомный блок.
На внешнем сервере — внешний кастомный блок.

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

В результате будет недоступна вкладка Код и появится поле URL. В поле нужно указать адрес или эндпоинт (метод API), на который будут приходить данные из диалога при выполнении кастомного блока.

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

activity — манифест кастомного блока и значения, указанные в редакторе данного блока в Bot.one.
bot_message — последнее сообщение, отправленное логикой блока.
user_message — последнее сообщение, отправленное респондентом.
dialog — данные по диалогу.
token — токен для работы с API Bot.one.
host_api — хост, на который надо отправлять API запросы.

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

{
"activity": {
     "text_field":  {
          "type": "text",
          "value": "текстовое значение"
        },
     "num_field": {
         "type": "number",
         "value": 123
        }
    },
"bot_message": [],
"user_message": [],
"dialog": {
   "id": 1093791,
   "locale": "en"
    },
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpbnN0YW5jZSI6ImRldiIsImRpYWxvZ19pZCI6MTA5Mzc5MiwidmVydGV4X2lkIjoyODQ3Nywic2Vzc2lvbl9pZCI6MTYwMDE4OX0.vOZM3DlSl_jszeuanHT9erJx-0XLXUQ5Qzn-EefMFOU",
"host_api": "http://api.local.form.one:9711"
 }

Для внешних блоков доступны два метода API для взаимодействия с диалогом:

Редактировать локальный блок

Warning

Только локальные блоки доступны для редактирования.

Для редактирования локального блока, нажмите на него.

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

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

Note	Если кнопка Сохранить недоступна при внемении изменений, проверьте, чтобы были заполнены и валидны вкладки Интерфейс и Код, а также заполнены все поля на вкладке Настройки.

Если измененный блок используется в опубликованных ботах, то появится предупреждение, что все боты будут обновлены. Если у вас есть сомнения, стоит ли обновлять их все, вы можете просмотреть боты, которые содержат этот блок (см. В каких ботах используется кастомный блок) – и потом решить, сохранять или нет изменения.

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

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

Для этого:

Перейдите в раздел Диалоги и откройте нужный диалог.
Перейдите на вклаку Данные.
В разделе Собранная информация содержатся ссылки с результатами выполнения всех кастомных блоков диалога. Слева в таблице отображается название блока, справа – ссылка на файл с логом выполнения. Перейдите по ссылке в строке с наименованием нужного блока.

В результате на устройство сохранится файл формата json с результатом выполнения блока.

Note	Если кастомный блок ссылается на внешний веб-сервис, то вместо ссылки в столбце слева – прочерк.

Деинсталлировать блок

Деинсталлировать можно любой блок, независимо от его типа.

Для этого:

Наведите курсор на блок и нажмите кнопку .
Выберите Денисталлировать.

В результате статус блока изменится на Деинсталлировать: блок останется в списке, но будет недоступен для использования в ботах.

Чтобы блок можно было снова использовать в ботах, его нужно заново установить (см. Установить блок).

Экспортировать локальный блок

Warning

Экспортировать можно только локальные блоки.

Для экспорта кастомного блока:

Наведите курсор на блок и нажмите кнопку .
Выберите Скачать ZIP-архив.

В результате на устройство пользователя будет сохранен ZIP-архив, который содержит файлы:

interface.json – файл с конфигурацией интерфейса блока;
code.js – код бизнес-логики в случае, если в настройках блока указана встроенная обработка бизнес-логики;
settings.json – файл с общими свойствами блока.

Содержимое файлов interface.json и code.js аналогично содержимому вкладок Интерфейс и Код редактора блока.

Файл settings.json содержит контент следующего вида:

"title": название блока,

"emoji": эмоджи для блока,

"category": название категории,

"description": описание блока,

"sourceСode": выбор источника для обработки бизнес-логики блока,

"url": адрес веб-сервиса, который должен обрабатывать логику блока,