This site is no longer updated.Go to new Conversational Cloud docs

Типы ответов бота

text

Простой текстовый ответ, каждый элемент выводится отдельным сообщением.


Параметры
  • text — текст ответа.
  • tts — задает текст ответа с разметкой для синтеза речи.
  • markup — задает способ форматирования.

Синтаксис
{
  "type":"text",            //тип сообщения
  "text":"....",            //текст ответа
  "tts":"....",             //разметка для синтеза речи
  "markup":                 //форматирование
    "html|markdown|plain"
}

В тексте ответа можно использовать подстановки и функции, в рамках тега a и в $reaction.answer. Внутри скобок {{ }} может находиться любое валидное выражение на JavaScript, можно использовать те же переменные и функции, что и в скриптах.


Использование в сценарии
  • Добавление ответа в $response:
script:
    var reply = {
        "type":"text",
        "text":"мой ответ",
    };
    $response.replies = $response.replies || [];
    $response.replies.push(reply);
  • Модификация ответов. В примере используем postProcess: если ответ бота повторяется, то заменяем его на фразу "Что-то я повторяюсь".
init:
    bind("postProcess", function($context) {
        var currentAnswer = $context.response.replies.reduce(function(allAnswers, reply) {
            allAnswers += reply.type === "text" ? reply.text : "";  
            return allAnswers;
        },"");
        
        if ($context.session.lastAnswer === currentAnswer) {
            $context.response.replies = [
            {
                "type":"text",
                "text":"Что-то я повторяюсь"
            }
            ];
        }
        $context.session.lastAnswer = currentAnswer;
    });

theme: /
    state:
        q!: как твои дела
        a: У меня все хорошо!
        a: А у тебя как?

audio

Использование аудиозаписи в ответе бота.


Параметры
  • audioUrl — ссылка на аудиофайл.
  • audioName — имя аудиофайла.

Синтаксис
{
  "type":"audio",                 //тип сообщения
  "audioUrl":"http://..."         //ссылка на аудиофайл
  "audioName":"имя файла",        //имя аудиофайла
}
Использование в сценарии
 script:
        $response.replies.push( {
            type: "audio",
            audioUrl: " https://...jpg",
            audioName: "voice"       //поле опционально
        } )

video

Использование видеозаписи в ответе бота.


Параметры
  • videoUrl — ссылка на видео.

Синтаксис
{
  "type":"video",                 //тип сообщения
  "videoUrl":"http://..."         //ссылка на видео
}
Использование в сценарии
 script:
        $response.replies.push( {
            type: "video",
            videoUrl: " https://...",
        } )

file

Использование файла в ответе бота.


Параметры
  • fileUrl — ссылка на файл.
  • fileName — имя файла
  • mimeType — медиа тип, обязательный параметр.

Синтаксис
{
  "type":"file",                         //тип сообщения
  "fileUrl": "<https://fileUrl>",        // путь до файла
  "fileName": "example.docx",            // имя файла
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
}

Использование в сценарии
    q!: file
    a: отправка файла
    script:
        $response.replies = $response.replies || [];
        $response.replies.push({
            type:"file",                         // тип, может принимать значения `audio`, `image`
            fileUrl: "<https://fileUrl>",        // путь до файла
            fileName: "example.docx",            // имя файла
            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        });

buttons

Тип ответа buttons выводит в чате ряд кнопок.


Параметры
  • text — название кнопки.

Синтаксис
{
  "type":"buttons"         //тип сообщения
  "buttons":[
    {
      "text":"кнопка",     //название кнопки
      другие поля будут переданы
      непосредственно в мессенджер
    }
  ]
}

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

Вложенные данные тега buttons должны соответствовать шаблону: <json-node> -> <string>. В левой части валидный JsonNode — строка или объект, определяющие текст или тело кнопки. В правой части — опционально строка, определяющая путь перехода при нажатии кнопки.

 state: Buttons
        q!: * start
        a: Кнопка:
        buttons:
            "Имя кнопки" -> /NormalButtons/2   //после стрелки указывается путь до состояния, в которое будет совершен переход

Также кнопки могут содержать подстановку параметров в имени и указанном пути для перехода.

 state: Buttons
        q!: * start
        a: Подстановка параметров в кнопках:
        buttons:
            "Имя кнопки" -> /NormalButtons/2
            "подстановка параметров как в {{ 'имени' }} так и в пути для перехода" -> {{ './3' }}

Использование в сценарии
state:
  a: Текст сообщения
  buttons:
    "Привет" -> ../Hello
    {text:"Отправить контакты", request_contact: true}  // две кнопки будут расположены на одной строке
  buttons:
    "Вторая кнопка"

inlineButtons

Вывод inline-кнопки. При клике могут передаваться данные или URL (callback_data или URL, соответственно). Также inline-кнопки отображаются не под диалогом, а внутри него в виде реплик.


Параметры
  • text — название кнопки.
  • url — ссылка для перехода.

Синтаксис
{
  "type":"inlineButtons"    //тип сообщения
  "buttons":[
    {
      "text":"кнопка",      //название кнопки
      "url":"http://example.com"  //ссылка для перехода
    }
  ]
}

К одному ответу нельзя одновременно добавить buttons и inlineButtons. Но можно добавить несколько ответов в один стейт и к каждому ответу добавить разный тип кнопок.


Использование в сценарии
state:
  a: Текст сообщения
  inlineButtons:
    {text:"Просмотреть", url:"http://example.com"}  
    {text:"Оформить", url:"http://example.com"}     // две кнопки будут расположены на одной строке

image

Вывод изображения.


Параметры
  • imageUrl — ссылка на изображение.
  • text — описание для изображения.

Синтаксис
{
  "type":"image",           //тип сообщения
  "imageUrl":"http://..."   //ссылка на изображение
  "text":"описание",      //описание для изображения
}

Использование в сценарии
 script:
        $response.replies.push( {
            type: "image",
            imageUrl: " https://...jpg",
            text: "описание изображения"       //поле опционально
        } )

raw

Используется для передачи методов, специфичных для определенного канала.


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

Также опциональные параметры, специфичные для каждого канала. Например, для Телеграма поле method: "sendMessage|sendPhoto|editMessageText".


Синтаксис
{
  "type":"raw",            //тип сообщения
  "body":{ ... },          //тело ответа
  "method":"sendMessage"   //опциональный параметр
}

Использование в сценарии
function editText(messageId, text) {
    var $response = $jsapi.context().response;
    var reply = {
        type: "raw",
        body: {
            text: text,
            message_id: messageId,
            reply_markup: {
                "resize_keyboard": false,
            }
        },
        method: "editMessageText"
    };

switch

Переключает диалог клиента с бота на оператора.


Параметры

Опциональные параметры:

  • firstMessage — сообщение, которое будет отображено в операторском чате. По умолчанию: последняя фраза клиента.
  • closeChatPhrases — массив строк, передающий список команд. Используя их, клиент сам сможет закрыть чат и вернуться к боту.
  • appendCloseChatButton - управление отображением кнопки закрытия чата с оператором. Принимает значения true/false: если true - при ответе оператора кнопка отображается, если false - не отображается. Заголовок кнопки будет взят из указанного массива строк closeChatPhrases.
  • ignoreOffline — выполнить перевод на оператора, проигнорировав отсутствие доступных операторов. По умолчанию false.
  • oneTimeMessage — отправить текст сообщения из firstMessage оператору, не выполняя перевод. Предназначен для передачи данных оператору без вступления в диалог. По умолчанию false.
  • destination — группа операторов, на которую нужно перенаправить клиентов.
  • lastMessage — сообщение, которое будет передано оператору, при завершении беседы пользователем с closeChatPhrases.
  • attributes — пречат поля. Принимает JSON в виде пар {"ключ":"значение"}. Параметры будут переданы оператору как дополнительная информация о клиенте.
  • hiddenAttributes — пречат поля, которые не будут переданы оператору. Формат аналогичен attributes.
  • phoneNumber — номер телефона, на который нужно перевести звонок. Только для телефонного канала. Обратите внимание, что формат номера зависит от провайдера телефонии.
  • headers — при переводе на оператора для телефонного канала можно установить SIP заголовки, которые будут передаваться в invite сообщении на указанный номер. Данная возможность, как правило, используется для передачи АОН информации клиента.
  • transferChannel — укажите в поле botId для перевода вызова через SIP-транк, который относится к данному каналу. При этом будут применены параметры подключенного SIP-транка.
  • continueCall — при true, абонент будет возвращен к диалогу с ботом после разговора с оператором, а также, если оператор недоступен.
  • continueRecording — при true, разговор продолжает записываться, в том числе с оператором и при повторном возвращении абонента в диалог с ботом. Запись звонка будет доступна в логах диалогов.
  • sendMessagesToOperator — при true, история сообщений будет отправлена оператору.
  • sendMessageHistoryAmount — количество последних сообщений диалога, которые будут отправлены оператору.

Синтаксис
{
  "type":"switch",               //тип сообщения
  "firstMessage":"..."  ,        //опциональные параметры
  "closeChatPhrases": [".."],
  "ignoreOffline":true|false,
  "oneTimeMessage": true|false
}

Использование в сценарии
$response.replies
     .push({
        type:"switch",
        closeChatPhrases: "Сбросить оператора",
        firstMessage: "",
        phoneNumber: "01234567",
        headers:{                                 // SIP заголовки
             "Remote-Party-ID": remotePartyId ,
             testheader:"header"
             }
});
 $response.replies.push({
    type:"switch",
    closeChatPhrases: ["/close", "вернуться в беседу с роботом"],
    firstMessage: $client.history,  // последнее сообщение клиента
});
$response.replies.push({
    type:"switch",
    phoneNumber:*****,                     // для телефонного канала
    closeChatPhrases: ["/close", "вернуться в беседу с роботом"],
    firstMessage: $client.history,         // последнее сообщение клиента
    destination: catchAll.operatorGroup,   // группа операторов для направления клиентов
});
$response.replies.push({
    type:"switch",
    closeChatPhrases: ["/closeLiveChat", "Закрыть диалог"],
    firstMessage: $client.history,
    lastMessage: "Мы ждем вас снова!",
    attributes: {                         // пречат поля
                 "Имя": "Джон",
                 "Фамилия": "Доу"
    }
});
$response.replies.push({
    type:"switch",
    appendCloseChatButton: true,
    closeChatPhrases: ["Закрыть диалог", "/closeLiveChat"],
    firstMessage: $context.client.chatHistory.map(function(val) {return val.type + "\n" + val.text;}).join("\n\n"),
    lastMessage: "Мы ждем вас снова!",
    attributes: {
                  "LiveChatTranscript": "История чата",
                  "platform": "Платформа"
                }
});
$response.replies.push({
  type:"switch",
  sendMessagesToOperator: true,   //история сообщений будет отправлена клиенту
  sendMessageHistoryAmount: 20
})

Для передачи истории переписки клиента с ботом при переводе на оператора вы можете использовать обработчики preProcessи postProcess:

 init:
//  сохраняем историю переписки клиента
  $jsapi.bind({
    type: "preProcess",
    name: "savingVisitorChatHistory",
    path: "/",
    handler: function($context) {
      // инициализируем историю переписки
      $context.client.chatHistory = $context.client.chatHistory || [];
      var chatHistory = $context.client.chatHistory;
      if ($context.request.query) {
        // записываем историю сообщений в массив
        chatHistory.push({type: "Имя клиента", text:$context.request.query});
      }
      // оставляем в истории переписки последние 10 сообщений
      chatHistory.splice(0, chatHistory.length - 10);
    }
});
// сохраняем историю ответов бота
  $jsapi.bind({
    type: "postProcess",
    name: "savingBotChatHistory",
    path: "/",
    handler: function($context) {
      // инициализируем историю переписки
      $context.client.chatHistory = $context.client.chatHistory || [];
      var chatHistory = $context.client.chatHistory;
      if ($context.response.replies) {
        // записываем сообщение бота
        $context.response.replies
          .filter(function(val) { return val.type === "text"; })
          .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.text }); });
      }
      // оставляем в истории переписки последние 10 сообщений
      chatHistory.splice(0, chatHistory.length - 10);
    }
});

Передача истории переписки клиента с ботом для операторского канала Salesforce:

init:
  $jsapi.bind({
    type: "preProcess",
    name: "savingVisitorChatHistory",
    path: "/",
    handler: function($context) {
      $context.client.chatHistory = $context.client.chatHistory || [];
      var chatHistory = $context.client.chatHistory;
      if ($context.request.query) {
        chatHistory.push({type:"CLIENT", text:$context.request.query});
      }
      // если клиент отправил файл/изображение/аудио, добавляем в историю ссылку на них
      if ($context.request.event === 'fileEvent' || $context.request.event === 'imageEvent'
          || $context.request.event === 'audioEvent') {
            chatHistory.push({type:"CLIENT", text:$context.request.data.eventData.url});
      }
      chatHistory.splice(0, chatHistory.length - 10);
    }
});
  $jsapi.bind({
    type: "postProcess",
    name: "savingBotChatHistory",
    path: "/",
    handler: function($context) {
      $context.client.chatHistory = $context.client.chatHistory || [];
      var chatHistory = $context.client.chatHistory;
      if ($context.response.replies) {
        // записываем сообщение бота
        $context.response.replies
            .filter(function(val) { return val.type === "text"; })
            .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.text }); });
      }
      if ($context.response.replies) {
        // добавляем ссылку на изображение
        $context.response.replies
            .filter(function(val) { return val.type === "image"; })
            .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.imageUrl }); });
      }
      if ($context.response.replies) {
        // добавляем ссылку на аудио сообщение
        $context.response.replies
            .filter(function(val) { return val.type === "audio"; })
            .forEach(function(val) { chatHistory.push({ type:"BOT", text: val.audioUrl }); });
      }
      chatHistory.splice(0, chatHistory.length - 10);
    }
});

location

Вывод координат.


Параметры
  • lat — широта.
  • lan — долгота.

Синтаксис
{
  "type": "location",   //тип сообщения
  "lat": 59.934280,     //широта
  "lon": 30.335099      //долгота
}

timeout

Задает переход в состояние, если от пользователя нет ответа.


Параметры
  • interval — интервал ожидания для реакции в секундах, число.
  • targetState — состояние, в которое должен перейти бот по истечении таймаута.

Синтаксис
{
  "type":"timeout",
  "interval":10,
  "targetState":"/timeout"
}

Использование в сценарии
state: time
    q!: timeout
    a: Таймер начался, когда вы сказали: {{$parseTree.text}}
    a: Напишите что нибудь и таймер перезапустится
    script: 
      $reactions.timeout({interval: '30 seconds', targetState: '/timeout'});


state: timeout
    a: Отведенное время закончилось. Спасибо за ваше обращение! Будем рады видеть вас снова.

dtmf

Запрос у абонента набор DTMF-сообщения (цифры/символы в тоновом режиме). Только для телефонных звонков.


Параметры

Опциональные параметры:

  • timeout — интервал ожидания ввода от абонента в миллисекундах, число.
  • max — максимальное количество цифр, которое ожидается от абонента.

Синтаксис
$response.replies.push({type:"dtmf"});

Использование в сценарии
patterns:
    $Digits = $regexp<\d+>

theme: /

    state: Main
        q!: * start
        a: Наберите 4 цифры в тоновом режиме
        script:
          $response.replies.push({
            type: 'dtmf',
            max: 4,
            timeout: 15000
          });
        
        state: Digits
          q: $Digits
          a: вы набрали {{$parseTree.text}}! 
          a: Спасибо! До свидания!
          script:
            $response.replies.push({
              type: 'hangup'
            });
        
    
    state: NoDigits
      q!: *
      event: noDtmfAnswerEvent
      a: Вы не набрали цифр!
      go!: /Main

hangup

Прервать звонок. Только для телефонных звонков.


Синтаксис
$response.replies.push({type:"hangup"});

Использование в сценарии
 script: 
        $reactions.answer("Благодарю за общение!")
        $response.replies = $response.replies || [];
        $response.replies.push({type:"hangup"});

htmlResponse

Тип ответа htmlResponse используется для вывода визуальной составляющей навыков, созданных с использованием Interactive Canvas.


Параметры
  • updatedState — обновлённое состояние веб-приложения, принимает JSON-объект.
  • suppressMic — управление микрофоном устройства. Принимает значения true/false, при true микрофон после вывода визуализации будет отключен. Опциональный параметр.
  • url — URL веб-приложения.

Подробнее о параметрах


Синтаксис
{
  "type":"htmlResponse",               //тип сообщения
  "updatedState": "some",
  "suppressMic":true|false,           //опциональный параметр
  "url": "appUrl"                     //опциональный параметр
}

Использование в сценарии
    script:
        var videolink = getLink("lovecraft_loading.mp4");
        var poster = getLink("main_menu.gif");
        $response.replies = $response.replies || []
        $response.replies.push({
                "type":"htmlResponse",
                "updatedState": {
                    "command": "UPDATE_STATE",
                    "video": videolink,
                    "poster": poster,
                    "buttons": [{
                        title: "Skip"
                    }]
                }
            });

crmIntegration

Тип ответа crmIntegration используется для работы с CRM Битрикс24.


Параметры
  • channelType — для работы с CRM Битрикс24 укажите "BITRIX".
  • task — укажите тип события для CRM, возможные значения:
    • LEAD_CREATION — создание лида;
    • DEAL_CREATION — создание сделки;
    • DEAL_UPDATE — обновление сделки.
  • parameters — дополнительные параметры для события. Параметр указывается в формате "fields[имя_параметра]": "значение".

Подробнее о параметрах для лидов и сделок

При успешном событии в сценарий приходит event: CRM_SUCCESS_EVENT, иначе event: CRM_FAILED_EVENT


Использование в сценарии

Сценарий обновления сделки:

state: Update deal
        q!: обновить сделку
        script:
            var reply = {type:"crmIntegration"};
            reply.channelType = "BITRIX";
            reply.task = "DEAL_UPDATE";
            reply.parameters = {
                    "fields[TITLE]": "Обновленное название сделки"
            };
            $response.replies = $response.replies || [];
            $response.replies.push(reply);

        state: CRM_SUCCESS_EVENT
            event: CRM_SUCCESS_EVENT
            script:
                $reactions.transition("/next_step");

        state: CRM_FAILED_EVENT
            event: CRM_FAILED_EVENT
            script:
                $reactions.transition("/problem_resolution");

carousel

Список элементов с возможностью выбора одного из них. В ответе бота вы можете указать только текст или текст с изображением.


Параметры
Параметр Тип Обязательный Описание
text string да Общее описание параметра
content string да Cодержимое ответа
title string да Заголовок
description string нет Описание
image string нет Ссылка на изображение
url string нет Ссылка на источник
btnText string да Текст кнопки

Синтаксис
{
  "type": "carousel",                 //тип ответа
  "text": "Описание карусели"
  "content": [
      {
        "title": "Заголовок",
        "description": "Описание",
        "image": "imageUrl",
        "url": "appUrl",
        "btnText": "Текст кнопки"
      }
    ]
}

Использование в сценарии

В данном примере бот выведет текстовое сообщение с изображением. Под описанием Самый современный стадион в России появится кнопка с надписью Открыть. При клике на кнопку пользователь будет перенаправлен на страницу сайта, указанного в параметре url.

script:
  var reply = {
    "type": "carousel",
    "text": "Описание карусели",
    "content": [
      {
        "title": "Стадион Санкт-Петербург",
        "description": "Самый современный стадион в России",
        "image": "https://example.png",
        "url": "https://example.com/",
        "btnText": "Открыть"
      }
    ]
  }
  $response.replies.push(reply);