ym88659208ym87991671
Ответы смартапа | Документация SmartMarket
Skip to main content

Ответы смартапа

Раздел содержит описание ответов смартапа.

note

Ассистент ожидает ответа в течение семи секунд.

На запрос ассистента смартап вернет один из следующих типов ответа:

  • ANSWER_TO_USER — содержит ответ, который ассистент предоставит пользователю;
  • POLICY_RUN_APP — сообщает, что смартап хочет запустить другое приложение. Включение функции обсуждается индивидуально на этапе модерации;
  • NOTHING_FOUND — смартап не смог найти ответ. Может указывать на то, что приложение было запущено по ошибке;
  • ERROR — сообщает ассистенту, что в смартапе возникла ошибка. Ассистент самостоятельно сообщит пользователю о возникнокении ошибки;

Каждый ответ содержит объект payload, наполнение которого зависит от типа ответа.

danger

В ответах нельзя передавать null. Переносы строк в JSON-ответах смартапов запрещены.

Информация об устройстве пользователя передаётся в объекте device и присутствует в ответах любого типа.

Объект payload может быть дополнен новыми полями.

Пример запроса с типом ANSWER_TO_USER:

{
  "messageName": "ANSWER_TO_USER",
  "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
  "messageId": 0,
  "uuid": {
    "userChannel": "B2C",
    "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
    "userId": "123"
  },
  "payload": {...}
}

Общие поля для всех типов ответов

Ответы всех типов содержат следующие поля:

ПолеОписание

messageId

Обязательное

long

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

sessionId

Обязательное

string (36)

Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога.

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

messageName

Обязательное

string (30)

Тип ответа. Определяет логику обработки.

Возможные значения:

  • ANSWER_TO_USER — содержит ответ, который ассистент предоставит пользователю;
  • POLICY_RUN_APP — сообщает о вызове смартапа из другого приложения;
  • NOTHING_FOUND — смартап не смог найти ответ. Может указывать на то, что приложение было запущено по ошибке;
  • ERROR — возвращается, если смартап недоступен или вернул ошибку.

uuid

Обязательное

object

Составной идентификатор пользователя.

payload

Обязательное

object

Объект с данными, которые зависят от типа сообщения.

Содержимое payload по типам сообщений

ANSWER_TO_USER

Пример payload:

{
    "pronounceText": "Привет! Чем я могу помочь?",
    "emotion": {
        "emotionId": "oups"
    },
    "items": [
        {
            "card": {}
        },
        {
            "bubble": {
                "text": "Привет!"
            }
        }
    ],
    "intent": "hi",
    "projectName": "hello",
    "device": {
        "platformType": "android",
        "platformVersion": "1.0.2",
        "surface": "SBOL",
        "surfaceVersion": "1.0.2",
        "features": {
            "appTypes": ["DIALOG", "WEB_APP"]
        },
        "capabilities": {
            "screen": { "available": true },
            "mic": { "available": true },
            "speak": { "available": true }
        },
        "additionalInfo": {}
    }
}

Описание полей:

ПолеОписание
pronounceText

string

Текст, который ассистент озвучит пользователю.

В тексте можно использовать SSML-разметку, если в поле pronounceTextType указать значение application/ssml.

Используйте разметку синтеза речи (тег audio), чтобы добавлять звуки в смартап

pronounceTextType

string

Указывает, что в тексте, который необходимо озвучить (поле pronounceText) есть разметка application/text или application/ssml.

Поддерживаемые разметки;

  • application/text;
  • application/ssml.
emotion

object

Эмоция ассистента, которую он показывает с помощью кнопки.

emotionId

string

Идентификатор эмоции, определяющий эмоцию персонажа.

Возможные значения:

  • igrivost — анимация игривости, которую ассистент может испытывать в ответ на дружеские шутки и подколки пользователя;
  • udovolstvie — анимация удовольствия;
  • podavleniye_gneva — анимация подавляемого раздражения на отрицательно окрашенные реплики в адрес ассистента;
  • smushchennaya_ulibka — анимация смущения, например, в ответ на похвалу;
  • simpatiya — анимация симпатии в ответ на положительно окрашенные реплики;
  • oups — анимация неловкости в ответ на лёгкое раздражение или неудобные вопросы пользователя. Например, при вопросе вида "Почему такие низкие ставки по вкладам?";
  • laugh — анимация смеха над шуткой пользователя;
  • ok_prinyato — анимация исполнения запроса;
  • bespokoistvo — анимация беспокойства, например, при жалобе пользователя на самочувствие;
  • predvkusheniye — анимация возбуждённого ожидания следующей реплики пользователя;
  • vinovatiy — анимация вины, например, если в приложении произошла ошибка;
  • zhdu_otvet — анимация ожидания реакции от пользователя, например, ответа на заданный вопрос;
  • zadumalsa — анимация размышление над репликой пользователя, например, если её не удалось распознать;
  • neznayu — анимация отсутствия ответа.
  • nedoumenie — анимация сомнения, например, когда не удаётся точно распосзнать реплику.
  • nedovolstvo — анимация негативной реакции в ответ на реплику
  • nesoglasie — анимация несогласия с пользователем.
  • pechal — анимация грусти и тоскливого настроения.
  • radost — анимация радости или удовлетворения действиями или репликами пользователя.
  • sochuvstvie — анимация сопереживания или выражения участия в проблемах пользователя.
  • strakh — анимация испуга.
  • zainteresovannost — анимация проявления интереса или любопытства по отношению к действиям или репликам пользователя.
items

array of objects

Список команд и элементов интерфейса смартапа.


card

object

Карточка.


bubble

object

Текст.


command

object

Команда ассистенту.

suggestions

object

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

Важно! В интерфейсе SberBox предложения носят информационный характер. Оформляйте их в виде подсказок, а не кнопок.


buttons

array of objects

Список кнопок с предложениями смартапа. Каждая кнопка представлена в виде отдельного объекта.



title

string

Название кнопки, которое отображается в интерфейсе ассистента.



action

object

Описывает действие, которое выполнится по нажатию кнопки.

Объект игнорируется, если кнопка содержит массив actions.



actions

object

Массив, содержащий несколько действий, которые выполнятся по нажатию кнопки. Содержит минимум один элемент.

auto_listening

bool

Указывает, что ассистент должен слушать пользователя после выполнения действия.

По умолчанию false.

finished

bool

Сообщает ассистенту о завершении работы смартапа. Ассистент интерпретирует отсутствие поля как false.

Возможные значения:

  • true — диалог завершён, следующее сообщение пользователя поступит в другое приложение;
  • false — диалог продолжается, сообщения пользователя передаются в приложение.

В приложениях типа Canvas App необходимо самостоятельно закрывать окно приложения после завершения работы смартапа. Для этого требуется передать ассистенту команду close_app с помощью метода assistant.close() или window.AssistantHost.close(), если вы не используете Assistant Client.

device

Обязательное

object

Информация об устройстве пользователя.

intent

string

Интент, который смартап получит в следующем ответе ассистента.

asr_hints

object

Подсказки для сервиса синтеза и распознавания речи. Подробнее в разделах про контексты и хинты.

POLICY_RUN_APP

Позволяет запускать сторонние смартапы. Включение функции согласуется индивидуально на этапе модерации.

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

Пример payload:

{
    "projectName": "hello",
    "device": {
        "platformType": "android" | "ios",
        "platformVersion": "1.0.2",
        "surface": "SBOL",
        "surfaceVersion": "1.0.2",
        "features": {
            "appTypes": ["DIALOG", "WEB_APP"]
        },
        "capabilities": {
            "screen": { "available": true },
            "mic": { "available": true },
            "speak": { "available": true }
        },
        "additionalInfo": {}
    },
    "server_action": {
        "app_info": {
            "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
            "appversionId": "3fa85f64-5717-4562-b3fc-2c963f66afa8"
        },
        "action_id": "start_track",
        "parameters": {}
    }
}

Описание полей:

ПолеОписание

projectName

Обязательное

string

Имя смартапа, которое задается при создании проекта и отображается в каталоге приложений.

device

Обязательное

object

Информация об устройстве пользователя.

server_action

Обязательное

object

Информация о запускаемом смартапе и параметрах его запуска. Аналогично действию типа server_action.

    app_info

    Обязательное

object

Информация о смартапе.

NOTHING_FOUND

Пример payload:

{
    "device": {
        "platformType": "android" | "ios",
        "platformVersion": "1.0.2",
        "surface": "SBOL",
        "surfaceVersion": "1.0.2",
        "features": {
            "appTypes": ["DIALOG", "WEB_APP"]
        },
        "capabilities": {
            "screen": { "available": true },
            "mic": { "available": true },
            "speak": { "available": true }
        },
        "additionalInfo": {}
    }
}

Описание полей:

ПолеОписание

device

Обязательное

object

Информация об устройстве пользователя.

intent

string

Интент, который смартап получит в следующем ответе ассистента.

ERROR

При возникновении ошибки в приложении, вам достаточно передать ассистенту сообщение с типом ERROR и описанным ниже содержимым.

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

Пример payload:

{
    "code": 1984,
    "device": {
        "platformType": "android" | "ios",
        "platformVersion": "1.0.2",
        "surface": "SBOL",
        "surfaceVersion": "1.0.2",
        "features": {
            "appTypes": ["DIALOG", "WEB_APP"]
        },
        "capabilities": {
            "screen": { "available": true },
            "mic": { "available": true },
            "speak": { "available": true }
        },
        "additionalInfo": {}
    }
}

Описание полей:

ПолеОписание

code

Обязательное

int

Код ошибки.

description

string (30)

Описание ошибки.

device

Обязательное

object

Информация об устройстве пользователя.

intent

string

Интент, который смартап получит в следующем ответе ассистента.

Обновлено 16 мая 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней