ym88659208ym87991671
Переменная $response для JS API для смартапов | Документация для разработчиков

$response

Обновлено 15 декабря 2023
Code
SmartApp API

Объект для заполнения поля $response в ответах ассистента.

$response.replies — список ответов, выведенных в процессе обработки реакций.

replies — массив реплик ассистента, содержащий строго типизированные элементы. Предназначен для передачи ответов.

Массив replies может содержать следующие элементы:

text

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

  • text — текст ответа;
  • tts — реплика, которую произнесет ассистент. Без разметки для синтеза речи;
  • ssml — реплика из поля tts c ssml-разметкой для синтеза речи;
  • markdown — текст ответа из поля text, отформатированный с помощью разметки markdown;
  • auto_listening — указывает будет ли смартап слушать ответ пользователя после ответа ассистента.
{
    "type": "text",
    "text": "....",
    "tts": "....",
    "ssml": ".....",
    "markdown": ".....",
    "auto_listening": true
}

Пример поля items.bubble, которое передается в ответе ассистента:

Интерфейс Postman

Поддерживаемые markdown-теги

Доступны следующие элементы форматирования:

ФорматированиеПример кода
Жирный шрифт
Жирный шрифт
Курсив
Курсив

или


Курсив
Зачеркнутый шрифт
Зачеркнутый шрифт
Ссылка
текст ссылки
Маркированный список
    

  • Пункт 1
    • 

  • Пункт 2
    • 

  • Пункт 3
    •

или


    

  • Пункт 1
    • 

  • Пункт 2
    • 

  • Пункт 3
    •

buttons

Кнопки с подсказками в чате с ассистентом.

{
    "type": "buttons",
    "buttons": [
        {
            "text": "Переход по адресу",
            "url": "https://example.com"
        },
        {
            "text": "Подсказка"
        }
    ]
}

Пример массива подсказок suggestions.buttons, который передается в ответе ассистента:

Интерфейс Postman

image

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

{
    "type": "image",
    "imageUrl": "http://...",
    "hash": "<hash картинки из раздела Контент>"
}

Изображения должны соответствовать требованиям:

  • Размер — менее 500 Кб;
  • Формат — jpg, png или bmp;
  • Рекомендуемое соотношение сторон — 3:2;
  • Рекомендуемое разрешение — больше 1024 × 682 пикселей.

Пример содержит код карточки типа list_card, с помощью которой можно передавать изображения в ответах ассистента:

Пример картинки

card

Формирует ответ в виде карточки, которая содержит: заголовок, описание, изображение и кнопку. Содержит обязательное поле поле title.

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

{
    "type": "card",
    "title": "title",
    "description": "descr",
    "imageUrl": "<url на картинку из раздела Контент>",
    "hash": "<hash картинки из раздела Контент>",
    "button": {
        "text": "text",
        "url": "url"
    },
    "auto_listening": false
}

Пример карточки list_card, которую можно передать в поле items.card ответа ассистента:

Интерфейс Postman

cardList

Формирует ответ в виде карточки со списком, которая содержит: заголовок, подзаголовок, кнопку и список ячеек. Карточка включает обязательный заголовок (title), подзаголовок (subtitle), а также обязательные массивы ячеек (cells) и кнопок (buttons). Если кнопки или ячейки не нужны, в полях cells и buttons указывайте пустые массивы.

При добавлении ячейки, нужно указать ее заголовок (title) и значение (value).

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

{
    "type": "cardList",
    "title": "Заголовок карточки",
    "subtitle": "Описание",
    "cells": [
        {
            "title": "Заголовок ячейки 1",
            "subtitle": "Описание ячейки 1",
            "value": "Значение, которое отображается в правой части ячейки 1. Рекомендуемая длина менее 5 символов.",
            "iconUrl": "https://example.ru/images/image.png",
            "hash": "3a74d5abfc671f47e45d336ed4d41026",
            "action": {
                "url": "Веб-адрес, который откроется при нажатии ячейки"
            }
        },
        {
            "title": "Заголовок ячейки 2",
            "subtitle": "Описание ячейки 2",
            "value": "Значение, которое отображается в правой части ячейки 2. Рекомендуемая длина менее 5 символов.",
            "iconUrl": "https://example.ru/images/image.png",
            "hash": "3a74d5abfc671f47e45d336ed4d41026",
            "action": {
                "text": "Текст, который отправится при нажатии ячейки"
            }
        }
    ],
    "buttons": [
        {
            "text": "Название кнопки карточки",
            "url": "Веб-адрес, который откроется при нажатии кнопки"
        }
    ],
    "auto_listening": false
}

Пример списка в карточке list_card, которую можно передать в поле items.card ответа ассистента:

Пример списка

raw

Используется для передачи собранных вручную ответов. Обязательный параметр body тело ответа, содержание которого будет добавлено в поле payload протоколе ассистента. Параметры, идентифицирующие пользователя будут подставлены автоматически.

При необходимости можно указать поле messageName и передать в нем необходимое сообщение. По умолчанию передается значение ANSWER_TO_USER. Описание тела сообщения ANSWER_TO_USER вы найдете в разделе SmartApp API.

{
  "type":"raw",
  "body":{ ... },
  "messageName":"ANSWER_TO_USER"
}

Тестовый виджет не отображает ответы с типом raw, если они передаются с помощью $context.response.replies.

Примеры значений

  • Вывод изображения.
script: $response.replies = $response.replies || [];
$response.replies.push({
    type: 'image',
    imageUrl: ' https://testimageurl.jpg',
    hash: '<hash картинки из раздела Контент>',
});
  • Отправка текстового ответа с markdown-разметкой.
script: $response.replies = $response.replies || [];
$response.replies.push({
    type: 'raw',
    body: {
        items: [
            {
                bubble: {
                    text: '*Привет всем!*',
                    markdown: true,
                },
            },
        ],
    },
});
  • Пример изменения ответа в post-процессе при третьей попытке ассистента ответить одинаково.
init: bind('postProcess', function () {
    var $session = $jsapi.context().session;
    var $response = $jsapi.context().response;
    var answer = $response.replies
        ? $response.replies.reduce(function (answers, current) {
              answers += ' ' + current.text;
              return answers;
          }, '')
        : '';
    if ($session.lastAnswer && answer == $session.lastAnswer) {
        $session.answerRepetition = $session.answerRepetition || 0;
        $session.answerRepetition += 1;
    } else {
        $session.answerRepetition = 0;
    }
    if ($session.answerRepetition == 2) {
        $response.replies = [
            {
                type: 'text',
                text: 'Похоже мы ходим кругами. Может спросишь о чем-нибудь другом?',
            },
        ];
    }
    $session.lastAnswer = answer;
});
  • Передача карточки типа grid_card в диалог с пользователем:
var reply = {
    type: 'raw',
    body: {
        emotion: null,
        items: [
            {
                card: {
                    type: 'grid_card',
                    items: [
                        {
                            type: 'greeting_grid_item',
                            top_text: {
                                type: 'text_cell_view',
                                text: 'SBER Box',
                                typeface: 'caption',
                                text_color: 'default',
                                max_lines: 3,
                            },
                            bottom_text: {
                                type: 'text_cell_view',
                                text: 'Компактная ТВ-приставка SBER Box – интеллектуальный центр вашего дома',
                                typeface: 'body3',
                                text_color: 'default',
                                max_lines: 3,
                                margins: {
                                    top: '4x',
                                },
                            },
                            paddings: {
                                top: '6x',
                                left: '6x',
                                right: '6x',
                                bottom: '6x',
                            },
                            actions: [
                                {
                                    text: 'Подписка Okko в подарок.',
                                },
                            ],
                        },
                        {
                            type: 'greeting_grid_item',
                            top_text: {
                                type: 'text_cell_view',
                                text: 'SberPortal',
                                typeface: 'caption',
                                text_color: 'default',
                                max_lines: 3,
                            },
                            bottom_text: {
                                type: 'text_cell_view',
                                text: 'Смарт-дисплей с премиальной акустикой и функцией видеозвонков',
                                typeface: 'body3',
                                text_color: 'default',
                                max_lines: 3,
                                margins: {
                                    top: '4x',
                                },
                            },
                            paddings: {
                                top: '6x',
                                left: '6x',
                                right: '6x',
                                bottom: '6x',
                            },
                            actions: [
                                {
                                    type: 'deep_link',
                                    text: 'Узнать больше',
                                    deep_link: 'https://spasibosberbank.ru/partners/korporativnyy-magazin-sberbanka',
                                },
                            ],
                        },
                    ],
                    columns: 2,
                    item_width: 'small',
                },
            },
        ],
    },
    messageName: 'ANSWER_TO_USER',
};
$response.replies = $response.replies || [];
$response.replies.push(reply);
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.