Кнопки реакций

Важно: это экспериментальная функция, которая может существенно измениться в следующих версиях. Обратная совместимость не гарантируется.

Для сбора обратной связи по работе бота можно добавлять кнопки реакций к сообщениям бота.

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

История нажатых пользователем кнопок с реакциями видна в истории беседы в разделе Диалоги бота и сохраняется в транскрипте при экспорте беседы в json-файл.

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

Настройка реакций при отправке сообщений бота

Кнопки реакций можно настраивать только в скрипте — в обработчиках событий в основном скрипте бота и в элементах сценария Скрипт.

Для описания списка кнопок используются следующие свойства:

TypeScript
{
  promptText: 'Был ли ответ бота полезен?',
  actions: [
    {
      text: '👍',
      value: 'positive',
      groupId: '1',
      feedbackType: ActivityFeedbackType.Action,
      eventId: 'goodFeedback'
    },
    {
      text: '👎',
      value: 'negative',
      groupId: '1',
      feedbackType: ActivityFeedbackType.Action,
      eventId: 'badFeedback'
    },
    {
      text: '💬',
      value: 'comment',
      groupId: '2',
      feedbackType: ActivityFeedbackType.Action,
      eventId: 'commentFeedback'
    },
  ]
}

promptText — указывает текст, который будет отображаться перед кнопками реакций пользователя. Не обязательное поле.
actions — массив с кнопками реакций.
- text — отображаемый текст кнопки.
- value — значение реакции.
- groupId — группа, к которой относится кнопка. В одной группе может быть активно не больше одной кнопки. Не обязательное поле.
- feedbackType — тип реакции при нажатии кнопки:
  - ActivityFeedbackType.Reaction — простая реакция: при нажатии кнопки в журнал беседы добавится соответствующая запись.
  - ActivityFeedbackType.Action — реакция с дополнительным действием: при нажатии также дополнительно будет вызвано внешнее событие с указанным кодом.
- eventId — код внешнего события, которое будет вызвано при нажатии кнопки. По умолчанию feedback.

Настроить кнопки реакций для отправляемого сообщения можно в двух случаях — при отправке сообщения в чат через скрипт и при обработке событий диалогов.

При отправке сообщения в скрипте

Для настройки реакций при отправке сообщения через скрипт укажите настройки реакций в свойствах объекта activity:

TypeScript
const activity: ScriptActivity = {
    type: ScriptActivityTypes.Message,
    text: {
      content: 'Текст сообщения',
    },
    feedback: {
      promptText: 'Был ли ответ бота полезен?',
      actions: [
        { text:  '👍', value: '👍', groupId: '1' },
        { text:  '👎', value: '👎', groupId: '1' },
      ],
    }
    properties: {},
  };

  context.output.activities = [activity];

В событиях диалогов

В некоторых обработчиках событий диалогов, таких как onInputDialogBegin и onInputDialogValueRecognized, можно указать настройки реакций, заполнив поле feedback в объекте context.output.result.activityProperties:

TypeScript
onInputDialogBegin("looptextinput", async () => {
  context.output.result.activityProperties = {
    feedback: {
      promptText: 'Был ли ответ бота полезен?',
      actions: [
        { text:  '👍', value: '👍', groupId: '1' },
        { text:  '👎', value: '👎', groupId: '1' },
      ]
    },
  };
});

В этом примере при каждом запросе значения переменной looptextinput к соответствующему сообщению бота будут добавлены кнопки реакций.

При настройке поля feedback в обработчике события onInputDialogValueRecognized также можно установить значение context.output.result.recognized в false, чтобы работа элемента сценария Вопрос. Ввод текста не завершалась после ввода текста пользователем. Это может быть полезно, если бот должен постоянно отвечать на вопросы пользователя, а пользователь должен иметь возможность отдельно оценить каждый ответ бота.

TypeScript
onInputDialogValueRecognized("looptextinput", async () => {
  // NOTE: переопределение результатов распознавания, чтобы можно было обработать ввод пользователя в событии input_unrecognized
  context.output.result.recognized = false;

  context.output.result.activityProperties = {
    feedback: {
      promptText: 'Был ли ответ бота полезен?',
      actions: [
        { text:  '👍', value: '👍', groupId: '1' },
        { text:  '👎', value: '👎', groupId: '1' },
      ]
    },
  };
});

Использование кнопок реакций вместе с предложенными действиями

При отправке сообщения бота можно комбинировать кнопки реакций и кнопки с предложенными действиями:

Для этого необходимо заполнить в скрипте оба свойства: context.output.result.activityProperties и context.output.result.suggestedActions (или свойства feedback и suggestions у объекта activity).

История нажатий кнопок с реакциями в беседе бота

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

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

При экспорте беседы в формате json информация о реакциях сохраняется в объектах с типом Message в поле feedback:

JSON
{
  "feedback": {
    "values": [
      "Comment",
      "👍"
    ],
    "customValue": "Комментарий пользователя"
  }
}

feedback — объект с информацией о реакциях.
- values — список значений реакций, добавленных к сообщению
- customValue — текст дополнительного комментария, если он был добавлен к сообщению

Вызов внешних событий при нажатии кнопок с реакциями

При нажатии пользователем кнопки с реакцией с типом ActivityFeedbackType.Action в момент нажатия создается внешнее событие с кодом, указанным в поле eventId настроек кнопки (если значение кода не указано, то используется код feedback). Это событие можно обработать в сценарии бота с помощью триггера Внешнее событие.

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

Обработка внешнего события при нажатии кнопки реакции

В поле Идентификатор необходимо указать код события (такой же, как в поле eventId настройках кнопки реакции).
В списке переменных можно добавить следующие переменные, значения которых заполняются при срабатывании триггера (обратите внимание — названия переменных должны быть именно такими):
- answerText — текст сообщения бота, которому пользователь отправляет реакцию.
- questionText — текст исходного вопроса пользователя, на который дает ответ бот в сообщении, на которое пользователь отправляет реакцию.
- activityKey — внутренний уникальный идентификатор сообщения, на которое пользователь отправляет реакцию. Необходим для отправки дополнительного комментария пользователя.
- feedbackValue — значение нажатой кнопки реакции.

Добавление дополнительного комментария пользователя

При срабатывании триггера внешнего события при нажатии кнопки реакции можно сохранить идентификатор соответствующего сообщения и с помощью элемента сценария Скрипт сохранить дополнительный комментарий, относящийся к сообщению. Для этого нужно:

В триггере внешнего события добавить в список переменных activityKey (такая перменная должна быть создана в списке переменных бота)
При необходимости запросить у пользователя текст комментария, например, с помощью элемента сценария "Вопрос. Ввод текста" и сохранить его в одну из переменных, например commentText
В элементе сценария Скрипт сохранить комментарий с помощью вспомогательной функции sendFeedback:

TypeScript
const activityKey = context.input.variables.activityKey;
const feedback = context.input.variables.commentText;
await context.utils.feedback.sendFeedback(activityKey, feedback);

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