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

Обновлено 25 декабря 2023

SmartApp API

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

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

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

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

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

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

Описание ответов

ANSWER_TO_USER

ANSWER_TO_USER — это ответ сценария, который содержит команду для фронта навыка и ответ пользователю. Ответ сценария состоит из текста озвучки и текста, выводимого на экран.

• Пример
• Описание

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "ANSWER_TO_USER"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "ANSWER_TO_USER",
• "payload": {

  • "pronounceText": "Привет! Чем я могу помочь?",
  • "pronounceTextType": "application/text",
  • "emotion": {

    • "emotionId": "oups"

    },
  • "items": [

    • {

      • "bubble": { },
      • "card": { },
      • "command": { }

      }

    ],
  • "suggestions": {

    • "buttons": [

      • {

        • "title": "string",
        • "action": { },
        • "actions": [

          • { }

          ]

        }

      ]

    },
  • "auto_listening": false,
  • "finished": true,
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string",
  • "asr_hints": { }

  }

}

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "ANSWER_TO_USER"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "ANSWER_TO_USER",
• "payload": {

  • "pronounceText": "Привет! Чем я могу помочь?",
  • "pronounceTextType": "application/text",
  • "emotion": {

    • "emotionId": "oups"

    },
  • "items": [

    • {

      • "bubble": { },
      • "card": { },
      • "command": { }

      }

    ],
  • "suggestions": {

    • "buttons": [

      • {

        • "title": "string",
        • "action": { },
        • "actions": [

          • { }

          ]

        }

      ]

    },
  • "auto_listening": false,
  • "finished": true,
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string",
  • "asr_hints": { }

  }

}

POLICY_RUN_APP

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

Добавить возможность запуска сторонних смартапов можно на этапе разработки или модерации:

• На этапе разработки смартапа напишите письмо на developer@sberdevices.ru, в котором укажите:

  • название смартапа;
  • назначение смартапа;
  • список смартапов, которые можно будет запускать из сценария.

• При подготовке смартапа к модерации в поле Инструкция для тестирования укажите, что в сценарии используется сообщение POLICY_RUN_APP, и приведите список всех смартапов, которые можно будет запускать из сценария.

• Пример
• Описание

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "POLICY_RUN_APP"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "POLICY_RUN_APP",
• "payload": {

  • "projectName": "weather",
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "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",
      • "frontendEndpoint": "string",
      • "frontendType": "APK",
      • "systemName": "string",
      • "frontendStateId": "string"

      },
    • "action_id": "string",
    • "parameters": { }

    }

  }

}

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "POLICY_RUN_APP"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "POLICY_RUN_APP",
• "payload": {

  • "projectName": "weather",
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "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",
      • "frontendEndpoint": "string",
      • "frontendType": "APK",
      • "systemName": "string",
      • "frontendStateId": "string"

      },
    • "action_id": "string",
    • "parameters": { }

    }

  }

}

NOTHING_FOUND

NOTHING_FOUND — смартап не смог найти ответ. Может указывать на то, что приложение было запущено по ошибке.

• Пример
• Описание

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "NOTHING_FOUND"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "NOTHING_FOUND",
• "payload": {

  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string"

  }

}

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "NOTHING_FOUND"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "NOTHING_FOUND",
• "payload": {

  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string"

  }

}

Подробнее о методе обработки ошибочных запросов NOTHING_FOUND.

ERROR

ERROR — сообщает ассистенту, что в смартапе возникла ошибка. Ассистент самостоятельно сообщит пользователю о возникновении ошибки.

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

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

• Пример
• Описание

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "ERROR"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "ERROR",
• "payload": {

  • "code": 1984,
  • "description": "Описание ошибки",
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string"

  }

}

sessionId required	string <= 36 characters Идентификатор соединения (не диалоговой сессии). Обновляется при каждом новом запросе с сохранением контекста диалога. При использовании с messageId гарантирует уникальность сообщения. В том числе если пользователь взаимодействует с несколькими поверхностями.
messageId required	integer <int32> Идентификатор запроса, который отправил ассистент. Ответ на запрос должен содержать такой же идентификатор в поле messageId.
required	object Составной идентификатор пользователя. Code создает собственный идентификатор пользователя, который можно получить в сценарии: $session.userId. Идентификатор создается на основе значения поля sub. Если поле sub отсутствует в запросе ассистента, для создания идентификатора используется значение поля userId.
messageName required	string Название сообщения Value: "ERROR"
required	object Полезная нагрузка сообщения. Объект может быть дополнен новыми полями.

{

• "sessionId": "86024848-c12b-4056-b58b-93c69b412314",
• "messageId": 0,
• "uuid": {

  • "userChannel": "B2С",
  • "sub": "d2d6da62-6bdd-452b-b5dd-a145090075ba",
  • "userId": 123

  },
• "messageName": "ERROR",
• "payload": {

  • "code": 1984,
  • "description": "Описание ошибки",
  • "device": {

    • "platformType": "ANDROID",
    • "platformVersion": "1.0.2",
    • "surface": "SBOL",
    • "surfaceVersion": "1.0.2",
    • "devicesId": "string",
    • "features": {

      • "appTypes": [

        • "DIALOG"

        ]

      },
    • "capabilities": {

      • "screen": {

        • "available": true,
        • "width": 1080,
        • "height": 1920,
        • "scale_factor": 2.5

        },
      • "mic": {

        • "available": true

        },
      • "speak": {

        • "available": true

        }

      },
    • "additionalInfo": { }

    },
  • "intent": "string"

  }

}