SmartApp API


Ассистент использует SmartApp API для обмена сообщениями с приложениями, представленными в виде сторонних веб-сервисов. Обмен сообщениями происходит по протоколу HTTPS. Ассистент получает от пользователя текст, который отправляет в смартап с помощью POST-запроса на Webhook URL. Адрес вебхука необходимо указывать при создании смартапа в SmartApp Studio. Текст может быть как репликой пользователя, так и текстом нажатой кнопки или текстом, который пользователь указал в интерфейсе.

Используйте SmartApp API для портирования приложений с других платформ. Например, для портирования навыков Алисы.

Персональные данные пользователей не передаются физическим лицам. Если вы представляете юридическое лицо и вашему смартапу необходимо обрабатывать персональные данные пользователей, напишите нам на developer@sberdevices.ru.

Этот раздел содержит описание формата сообщений, которыми ассистент обменивается со смартапом.

Формат запроса

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

  • MESSAGE_TO_SKILL — содержит сообщение для смартапа;
  • SERVER_ACTION — сообщает смартапу о действиях пользователя на фронтенде, а также фоновые действия полноэкранных приложений;
  • RUN_APP — сообщает о запуске смартапа. Приходит в бэкенд смартапа при передаче сообщения POLICY _RUN_APP или запуске смартапа с помощью действия;
  • CLOSE_APP — сообщает о закрытии и не требует ответа от смартапа. Содержимое сообщения совпадает с содержимым payload сообщения MESSAGE_TO_SKILL.

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

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

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

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

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

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

messageId

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

long

Идентификатор запроса, который отправил ассистент.

Ответ на запрос должен содержать такой же идентификатор в поле messageId.

sessionId

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

string (36)

Идентификатор сессии, который обновляется каждый раз, когда в поле new_session приходит true.

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

messageName

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

string (30)

Тип запроса.

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

  • MESSAGE_TO_SKILL — содержит сообщение для смартапа;
  • SERVER_ACTION — сообщает смартапу о действиях пользователя на фронтенде;
  • RUN_APP — сообщает о запуске смартапа;
  • CLOSE_APP — сообщает о закрытии смартапа.

uuid

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

object

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

payload

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

object

Коллекция, в которой в зависимости от потребителя и messageName передается дополнительная информация.

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

MESSAGE_TO_SKILL

Пример payload:

{
    "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": {}
    },
    "app_info": {
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
        "appversionId": "3fa85f64-5717-4562-b3fc-2c963f66afa8"
    },
    "character": {
        "id": "sber",
        "name": "Сбер",
        "gender": "male",
        "appeal": "official"
    },
    "intent": "rain",
    "original_intent": "rain",
    "intent_meta": {},
    "meta": {
        "time": {
            "timezone_id": "Europe/Moscow",
            "timezone_offset_sec": 10800,
            "timestamp": 1432233446145000
        }
    },
    "projectName": "weather",
    "annotations": {
        "censor_data": {
            "classes": ["politicians", "obscene", "model_response"],
            "probas": [0, 0, 0.20716862380504608]
        },
        "text_sentiment": {
            "classes": ["negative", "speech", "neutral", "positive", "skip"],
            "probas": [0.1, 0.1, 0.1, 0.6, 0.1]
        },
        "asr_sentiment": {
            "classes": ["positive", "neutral", "negative"],
            "probas": [0.0, 1.0, 0.0]
        }
    },
    "strategies": { "happy_birthday": false, "last_call": 158644724 },
    "message": {
        "original_text": "переведи сотню евро на мой счёт",
        "normalized_text": "перевести MONEY_TOKEN на мой счет .",
        "asr_normalized_message": "переведи 100 евро на мой счёт",
        "entities": {
            "CCY_TOKEN": [
                {
                    "value": "eur"
                }
            ],
            "MONEY_TOKEN": [
                {
                    "amount": 100,
                    "currency": "eur"
                }
            ],
            "NUM_TOKEN": [
                {
                    "adjectival_number": false,
                    "value": 100
                }
            ]
        },
        "tokenized_elements_list": [
            {
                "dependency_type": "root",
                "grammem_info": {
                    "aspect": "perf",
                    "mood": "imp",
                    "number": "sing",
                    "part_of_speech": "VERB",
                    "person": "2",
                    "raw_gram_info": "aspect=perf|mood=imp|number=sing|person=2|transitivity=tran|verbform=fin|voice=act",
                    "transitivity": "tran",
                    "verbform": "fin",
                    "voice": "act"
                },
                "head": 0,
                "lemma": "перевести",
                "list_of_dependents": [2, 3],
                "text": "переведи"
            },
            {
                "composite_token_length": 2,
                "composite_token_type": "MONEY_TOKEN",
                "composite_token_value": {
                    "amount": 100,
                    "currency": "eur"
                },
                "dependency_type": "nummod",
                "grammem_info": {
                    "numform": "digit",
                    "part_of_speech": "NUM",
                    "raw_gram_info": "numform=digit"
                },
                "head": 1,
                "is_beginning_of_composite": true,
                "lemma": "100",
                "list_of_dependents": [],
                "list_of_token_types_data": [
                    {
                        "token_type": "NUM_TOKEN",
                        "token_value": {
                            "adjectival_number": false,
                            "value": 100
                        }
                    }
                ],
                "text": "100",
                "token_type": "NUM_TOKEN",
                "token_value": {
                    "adjectival_number": false,
                    "value": 100
                }
            },
            {
                "composite_token_length": 2,
                "composite_token_type": "MONEY_TOKEN",
                "composite_token_value": {
                    "amount": 100,
                    "currency": "eur"
                },
                "dependency_type": "obj",
                "grammem_info": {
                    "degree": "pos",
                    "part_of_speech": "X",
                    "raw_gram_info": "degree=pos"
                },
                "head": 1,
                "is_beginning_of_composite": false,
                "lemma": "eur",
                "list_of_dependents": [6],
                "list_of_token_types_data": [
                    {
                        "token_type": "CCY_TOKEN",
                        "token_value": {
                            "value": "eur"
                        }
                    }
                ],
                "text": "eur",
                "token_type": "CCY_TOKEN",
                "token_value": {
                    "value": "eur"
                }
            },
            {
                "dependency_type": "case",
                "grammem_info": {
                    "part_of_speech": "ADP",
                    "raw_gram_info": ""
                },
                "head": 6,
                "lemma": "на",
                "list_of_dependents": [],
                "text": "на"
            },
            {
                "dependency_type": "det",
                "grammem_info": {
                    "case": "acc",
                    "gender": "masc",
                    "number": "sing",
                    "part_of_speech": "DET",
                    "raw_gram_info": "case=acc|gender=masc|number=sing"
                },
                "head": 6,
                "lemma": "мой",
                "list_of_dependents": [],
                "text": "мой"
            },
            {
                "dependency_type": "nmod",
                "grammem_info": {
                    "animacy": "inan",
                    "case": "acc",
                    "gender": "masc",
                    "number": "sing",
                    "part_of_speech": "NOUN",
                    "raw_gram_info": "animacy=inan|case=acc|gender=masc|number=sing"
                },
                "head": 3,
                "lemma": "счет",
                "list_of_dependents": [4, 5],
                "text": "счет"
            },
            {
                "lemma": ".",
                "list_of_token_types_data": [
                    {
                        "token_type": "SENTENCE_ENDPOINT_TOKEN",
                        "token_value": {
                            "value": "."
                        }
                    }
                ],
                "text": ".",
                "token_type": "SENTENCE_ENDPOINT_TOKEN",
                "token_value": {
                    "value": "."
                }
            }
        ]
    }
}

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

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

app_info

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

object

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

intent

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

string

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

original_intent

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

string

Исходный интент. Значение поля отличается от значения intent только при монопольном захвате контекста.

intent_meta

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

object

Мета данные, полученные от сервиса распознавания интентов.

Поле будет использовано в будущем. В текущей реализации содержит пустой объект.

Определяйте интенты в SmartApp Code и передавайте их в запросах к своему серверу.

meta

object

Данные о содержимом экрана пользователя.


time

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

object

Данные о текущем времени на устройстве пользователя.

Содержит следующие поля:

  • timestamp — число. Unix-время в миллисекундах.
  • timezone_id — строка. Наименование часового пояса. Пример Europe/Moscow.
  • timezone_offset_sec — число.
projectName

string

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

selected_item

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

object

Описание элемента экрана, который пользователь назвал при запросе ("включи второй" / "включи второго терминатора"). Для работы этой функциональности нужна отправка во входящем сообщении с фронтенда item_selector со списком элементов.

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


index

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

number

Номер элемента из списка, начиная с 0.


title

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

string

Название элемента.


is_query_by_number

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

bool

Указывает выбор элемента по номеру.

device

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

object

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

new_session

bool

Указывает на характер запуска смартапа. Если поле содержит true, сессии присваивается новый идентификатор (поле sessionId). 

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

  • true — приложение запущено впервые или после закрытия приложения, а так же при запуске приложения по истечению тайм-аута (10 минут) или после прерывания работы приложения, например, по запросу "текущее время"i>
  • false — во всех остальных случаях..

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

character

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

object

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

strategies
annotations

object

Общие характеристики сообщения пользователя.


censor_data

object

Информация о прохождении цензуры.



classes

array of strings

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

  • politicians — наличие политиков из списка
  • obscene — наличие нецензурной лексики
  • model_response — вероятность негатива


probas

array of numbers

Коэффициенты подцензурных категорий. Сопоставляются по индексам, в соотвествии со списком категорий censor_data.classes.

Для категорий politicians и obscene могут принимать только значения 0 и 1.


text_sentiment

object

Эмоциональная окраска текста пользователя.



classes

array of strings

Список характеристик эмоциональной окраски текста пользователя. Содержит следующие значения: 

  • negative
  • positive
  • neutral


probas

array of numbers

Коэффициенты той или иной эмоциональной характеристики текста пользователя в диапазоне от 0 до 1.

Коэффициенты сопоставляются по индексам с характеристиками, представленными в поле text_sentiment.classes.


asr_sentiment

object

Эмоциональная окраска голоса пользователя.



classes

array of strings

Список характеристик эмоциональной окраски голоса пользователя. Содержит следующие значения: 

  • positive
  • neutral
  • negative


probas

array of numbers

Коэффициенты той или иной эмоциональной характеристики реплики пользователя в диапазоне от 0 до 1.

Коэффициенты сопоставляются по индексам с характеристиками, представленными в поле asr_sentiment .classes.

message

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

object

Результат предобработки.


original_text

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


string

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

Пример: "хочу заказать пиццу на девять вечера за пятьсот рублей".


asr_normalized_message

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

string

Отображаемый на экране текст запроса / нормализованный на этапе ASR запрос.

Пример: "Хочу заказать пиццу на 9 вечера за 500 ₽".



normalized_text

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

string

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

Пример: хотеть заказать пицца на TIME_TIME_TOKEN за MONEY_TOKEN .


entities

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

object

Извлеченные из запроса сущности.


tokenized_elements_list

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


list

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

SERVER_ACTION

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

Пример payload:

{
    "device": {
        "platformType": "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": {}
    },
    "app_info": {
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
        "appversionId": "3fa85f64-5717-4562-b3fc-2c963f66afa8"
    },
    "projectName": "weather",
    "server_action": {
        "action_id": "start_track",
        "parameters": {}
    }
}

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

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

device

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

object

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

app_info

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

object

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

projectName

string

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

character

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

Информация о текущем персонаже ассистента, который установлен у пользователя.
strategies

object

Возможные стратегии смартапа.

server_action

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



object

Информация о запускаемом смартапе и параметрах его запуска.

Формируется бэкендом приложения.

По умолчанию: пустой объект.

RUN_APP

Пример payload:

{
    "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": {}
    },
    "app_info": {
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
        "appversionId": "3fa85f64-5717-4562-b3fc-2c963f66afa8"
    },
    "projectName": "weather",
    "intent": "run_app",
    "strategies": { "happy_birthday": false, "last_call": 158644724 },
    "server_action": {
        "action_id": "start_track",
        "parameters": {}
    }
}

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

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

device

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

object

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

app_info

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

object

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

projectName

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

string

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

intent

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

string

Интент, который приходит при запуске смартапа.

Значение всегда run_app.

character

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

object

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

strategies

server_action

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

object

Информация о запускаемом смартапе и параметрах его запуска.

Формируется бэкендом приложения.

По умолчанию: пустой объект.

CLOSE_APP

Когда пользователь произносит команду для остановки приложения, Ассистент передаёт сообщение CLOSE_APP в текущий открытый смартап и закрывает его. Ассистент не ждёт ответа от смартапа. Содержимое сообщения совпадает с содержимым payload сообщения MESSAGE_TO_SKILL.

Пример payload:

{
    "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": {}
    },
    "app_info": {
        "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
        "appversionId": "3fa85f64-5717-4562-b3fc-2c963f66afa8"
    },
    "character": {
        "id": "sber",
        "name": "Сбер",
        "gender": "male",
        "appeal": "official"
    },
    "intent": "rain",
    "original_intent": "rain",
    "intent_meta": {},
    "projectName": "weather",
    "annotations": {
        "censor_data": {
            "classes": ["politicians", "obscene", "model_response"],
            "probas": [0, 0, 0.20716862380504608]
        },
        "text_sentiment": {
            "classes": ["negative", "speech", "neutral", "positive", "skip"],
            "probas": [0.1, 0.1, 0.1, 0.6, 0.1]
        },
        "asr_sentiment": {
            "classes": ["positive", "neutral", "negative"],
            "probas": [0.0, 1.0, 0.0]
        }
    },
    "strategies": { "happy_birthday": false, "last_call": 158644724 },
    "message": {
        "original_text": "переведи сотню евро на мой счёт",
        "normalized_text": "перевести MONEY_TOKEN на мой счет .",
        "asr_normalized_message": "переведи 100 евро на мой счёт",
        "entities": {
            "CCY_TOKEN": [
                {
                    "value": "eur"
                }
            ],
            "MONEY_TOKEN": [
                {
                    "amount": 100,
                    "currency": "eur"
                }
            ],
            "NUM_TOKEN": [
                {
                    "adjectival_number": false,
                    "value": 100
                }
            ]
        },
        "tokenized_elements_list": [
            {
                "dependency_type": "root",
                "grammem_info": {
                    "aspect": "perf",
                    "mood": "imp",
                    "number": "sing",
                    "part_of_speech": "VERB",
                    "person": "2",
                    "raw_gram_info": "aspect=perf|mood=imp|number=sing|person=2|transitivity=tran|verbform=fin|voice=act",
                    "transitivity": "tran",
                    "verbform": "fin",
                    "voice": "act"
                },
                "head": 0,
                "lemma": "перевести",
                "list_of_dependents": [2, 3],
                "text": "переведи"
            },
            {
                "composite_token_length": 2,
                "composite_token_type": "MONEY_TOKEN",
                "composite_token_value": {
                    "amount": 100,
                    "currency": "eur"
                },
                "dependency_type": "nummod",
                "grammem_info": {
                    "numform": "digit",
                    "part_of_speech": "NUM",
                    "raw_gram_info": "numform=digit"
                },
                "head": 1,
                "is_beginning_of_composite": true,
                "lemma": "100",
                "list_of_dependents": [],
                "list_of_token_types_data": [
                    {
                        "token_type": "NUM_TOKEN",
                        "token_value": {
                            "adjectival_number": false,
                            "value": 100
                        }
                    }
                ],
                "text": "100",
                "token_type": "NUM_TOKEN",
                "token_value": {
                    "adjectival_number": false,
                    "value": 100
                }
            },
            {
                "composite_token_length": 2,
                "composite_token_type": "MONEY_TOKEN",
                "composite_token_value": {
                    "amount": 100,
                    "currency": "eur"
                },
                "dependency_type": "obj",
                "grammem_info": {
                    "degree": "pos",
                    "part_of_speech": "X",
                    "raw_gram_info": "degree=pos"
                },
                "head": 1,
                "is_beginning_of_composite": false,
                "lemma": "eur",
                "list_of_dependents": [6],
                "list_of_token_types_data": [
                    {
                        "token_type": "CCY_TOKEN",
                        "token_value": {
                            "value": "eur"
                        }
                    }
                ],
                "text": "eur",
                "token_type": "CCY_TOKEN",
                "token_value": {
                    "value": "eur"
                }
            },
            {
                "dependency_type": "case",
                "grammem_info": {
                    "part_of_speech": "ADP",
                    "raw_gram_info": ""
                },
                "head": 6,
                "lemma": "на",
                "list_of_dependents": [],
                "text": "на"
            },
            {
                "dependency_type": "det",
                "grammem_info": {
                    "case": "acc",
                    "gender": "masc",
                    "number": "sing",
                    "part_of_speech": "DET",
                    "raw_gram_info": "case=acc|gender=masc|number=sing"
                },
                "head": 6,
                "lemma": "мой",
                "list_of_dependents": [],
                "text": "мой"
            },
            {
                "dependency_type": "nmod",
                "grammem_info": {
                    "animacy": "inan",
                    "case": "acc",
                    "gender": "masc",
                    "number": "sing",
                    "part_of_speech": "NOUN",
                    "raw_gram_info": "animacy=inan|case=acc|gender=masc|number=sing"
                },
                "head": 3,
                "lemma": "счет",
                "list_of_dependents": [4, 5],
                "text": "счет"
            },
            {
                "lemma": ".",
                "list_of_token_types_data": [
                    {
                        "token_type": "SENTENCE_ENDPOINT_TOKEN",
                        "token_value": {
                            "value": "."
                        }
                    }
                ],
                "text": ".",
                "token_type": "SENTENCE_ENDPOINT_TOKEN",
                "token_value": {
                    "value": "."
                }
            }
        ]
    }
}

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

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

app_info

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

object

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

intent

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

string

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

original_intent

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

string

Исходный интент. Значение поля отличается от значения intent только при монопольном захвате контекста.

intent_meta

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

object

Мета данные, полученные от сервиса распознавания интентов.

Поле будет использовано в будущем. В текущей реализации содержит пустой объект.

Определяйте интенты в SmartApp Code и передавайте их в запросах к своему серверу.

projectName

string

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

selected_item

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

object

Описание элемента экрана, который пользователь назвал при запросе ("включи второй" / "включи второго терминатора"). Для работы этой функциональности нужна отправка во входящем сообщении с фронтенда item_selector со списком элементов.

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


index

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

number

Номер элемента из списка, начиная с 0.


title

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

string

Название элемента.


is_query_by_number

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

bool

Указывает выбор элемента по номеру.

device

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

object

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

new_session

bool

Указывает на характер запуска смартапа. Если поле содержит true, сессии присваивается новый идентификатор (поле sessionId). 

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

  • true — приложение запущено впервые или после закрытия приложения, а так же при запуске приложения по истечению тайм-аута (10 минут) или после прерывания работы приложения, например, по запросу "текущее время"i>
  • false — во всех остальных случаях..

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

character

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

object

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

strategies
annotations

object

Общие характеристики сообщения пользователя.


censor_data

object

Информация о прохождении цензуры.



classes

array of strings

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

  • politicians — наличие политиков из списка
  • obscene — наличие нецензурной лексики
  • model_response — вероятность негатива


probas

array of numbers

Коэффициенты подцензурных категорий. Сопоставляются по индексам, в соотвествии со списком категорий censor_data.classes.

Для категорий politicians и obscene могут принимать только значения 0 и 1.


text_sentiment

object

Эмоциональная окраска текста пользователя.



classes

array of strings

Список характеристик эмоциональной окраски текста пользователя. Содержит следующие значения: 

  • negative
  • positive
  • neutral


probas

array of numbers

Коэффициенты той или иной эмоциональной характеристики текста пользователя в диапазоне от 0 до 1.

Коэффициенты сопоставляются по индексам с характеристиками, представленными в поле text_sentiment.classes.


asr_sentiment

object

Эмоциональная окраска голоса пользователя.



classes

array of strings

Список характеристик эмоциональной окраски голоса пользователя. Содержит следующие значения: 

  • positive
  • neutral
  • negative


probas

array of numbers

Коэффициенты той или иной эмоциональной характеристики реплики пользователя в диапазоне от 0 до 1.

Коэффициенты сопоставляются по индексам с характеристиками, представленными в поле asr_sentiment .classes.

message

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

object

Результат предобработки.


original_text

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


string

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

Пример: "хочу заказать пиццу на девять вечера за пятьсот рублей".


asr_normalized_message

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

string

Отображаемый на экране текст запроса / нормализованный на этапе ASR запрос.

Пример: "Хочу заказать пиццу на 9 вечера за 500 ₽".



normalized_text

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

string

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

Пример: хотеть заказать пицца на TIME_TIME_TOKEN за MONEY_TOKEN .


entities

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

object

Извлеченные из запроса сущности.


tokenized_elements_list

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


list

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

Формат ответа

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

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

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

Переносы строк в 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)

Идентификатор сессии, который обновляется каждый раз, когда в поле new_session приходит true.

При использовании совместно с 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

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

pronounceTextType

string

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

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

  • 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

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

Описание общих объектов

Объект uuid

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

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

userId

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

string (64)

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


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

sub

string (256)

Постоянный идентификатор пользователя созданный на основе Сбер ID. Может отсутствовать, если пользователь не аутентифицирован.

Может использовать для хранения контекста диалога пользователя. Контекст диалога можно обновлять по значению поля new_session.

userChannel

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

string (64)

Идентификатор канала коммуникации.

Объект device

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

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

string

Операционная система устройства.

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

  • ANDROID;
  • IOS.
platformVersion

string

Версия операционной системы.

surface

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

string

Устройство или мобильное приложение, от которого приходит вызов ассистента


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

  • SBERBOX — запрос пришел от устройства SberBox;
  • COMPANION — запрос от приложения Сбер Салют;
  • STARGATE — запрос от устройства SberPortal.
surfaceVersion

string

Версия поверхности.

deviceId

string

Идентификатор устройства.

features

object

Описание функциональности устройства.



appTypes

array of strings

Типы смартапов, которые поддерживает устройство.

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

  • DIALOG;
  • WEB_APP;
  • APK;
  • CHAT_APP.

capabilities

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

object

Описание возможностей устройства пользователя.


screen

object

Описание экрана устройства.



available

bool

Признак наличия экрана.


mic

object

Описание микрофона устройства.



available

bool

Признак наличия микрофона.


speak

object

Описание динамиков устройства.



available

bool

Признак наличия динамиков.

additionalInfo

object

Дополнительная информация об объекте или устройстве. В настоящий момент не используется.

Объект app_info

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

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

projectId

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

guid

Идентификатор проекта в SmartApp Studio.

applicationId

guid

Идентификатор смартапа.

appversionId

guid

Идентификатор опубликованной версии смартапа.

frontendEndpoint

string

Ссылка на веб-приложение. Поле актуально для Canvas Apps.

frontendType

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

string

Тип смартапа.

Обратите внимание, что ассистент перехватывает навигационные команды "вверх", "вниз", "влево" и "вправо" только в Canvas App (тип приложения WEB_APP). В этом случае команды обрабатываются на уровне фронтенда приложения. В остальных случаях, команды передаются в бекэнд активного приложения.

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

  • DIALOG;
  • WEB_APP;
  • APK;
  • CHAT_APP.
systemName

string

Более читаемый аналог поля projectId. Не актуален для внешних приложений.

frontendStateId

string

Объединённое значение полей projectId, applicationId и appversionId.

Объект character

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

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

id

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

string

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

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

  • sber — персонаж мужского пола по имени Сбер. Обращается на "вы".
  • athena — персонаж женского пола по имени Афина. Обращается на "вы".
  • joy — персонаж женского пола по имени Джой.  Обращается на "ты".

Учитывайте пол персонажа (поле gender) и форму обращения (поле appeal) при проектировании ответов.

name

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

string

Имя персонажа.

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

  • Сбер;
  • Афина;
  • Джой.

gender

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

string

Пол персонажа. Учитывайте пол персонажа при проектировании ответов.

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

  • male;
  • female.

appeal

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

string

Форма обращения персонажа. Учитывайте форму обращения персонажа при проектировании ответов.

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

  • official — персонаж обращается на "вы".
  • no_official — персонаж обращается на "ты".

Объект strategies

Возможные стратегии смартапа.

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

bool

Сообщает, что у пользователя сегодня день рождения.

last_call

unix time

Время, которое прошло с момента последнего обращения к смартапу.

is_alice

bool

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

Объект server_action

Информация о запускаемом смартапе и параметрах его запуска. Формируется бэкендом приложения. По умолчанию: пустой объект.

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

app_info

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

object

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

parameters

object

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

action_id

string

Действие, которое обрабатывает бэкенд смартапа.


Значение по умолчанию:run_app.