Solicitações

As solicitações definem como sua ação renderiza as respostas aos usuários e como solicita que elas continuem. Ao criar sua ação, é possível adicionar solicitações a invocações e a vários lugares nas cenas. As solicitações podem ser simples, como uma resposta de texto ou fala, ou mais complexas e ter conteúdo avançado, como cartões, imagens e tabelas.

Tipos de resposta

Para cada prompt, você seleciona vários tipos de resposta interessantes para o Google Assistente apresentar aos usuários:

• Respostas simples: as respostas simples têm a aparência visual de um balão de chat e usam a conversão de texto em voz (TTS, na sigla em inglês) ou a linguagem de marcação de síntese de fala (SSML, na sigla em inglês) para som. As respostas simples são as únicas compatíveis com todos os tipos de dispositivo.
• Respostas avançadas: contêm elementos visuais ou funcionais que melhoram as interações do usuário com as ações. Com as respostas avançadas, também é possível exibir dados tabulares ou reproduzir conteúdo de áudio de formato mais longo.
• Respostas visuais de seleção: as respostas de seleção visual fornecem uma interface visual para que os usuários escolham entre várias opções que se diferenciam mais facilmente pelo título ou pela imagem.
• Respostas de mídia: as respostas de mídia permitem que suas ações reproduzam conteúdo de áudio mais longo que SSML e forneçam um componente visual com controles de mídia.
• Tela interativa: a tela interativa renderiza respostas como visualizações da Web em tela cheia e funciona como um app da Web interativo que o Google Assistente envia como resposta ao usuário na conversa. O Canvas usa um formato de solicitação um pouco diferente para acomodar a flexibilidade dos padrões da Web, como HTML, CSS e JavaScript.

Cada um desses tipos de resposta usa o mesmo formato de solicitação básico e tem acesso aos mesmos recursos gerais descritos abaixo.

Formato de uma solicitação

No projeto do Actions, você define solicitações no formato YAML ou JSON. Cada solicitação pode conter até duas respostas simples e, opcionalmente, definir uma resposta avançada. As respostas são definidas das seguintes maneiras:

• first_simple: resposta inicial por voz ou texto (simples) para enviar ao usuário.
• content: conteúdo de resposta complementar complementar que será enviado após respostas simples.
• last_simple Resposta de texto ou fala (simples) para enviar ao usuário.
• canvas: faz referência a um app da Web que se integra à tela interativa.

Por padrão, as solicitações são anexadas umas às outras na ordem acima em uma fila. Para que o usuário possa responder, o Assistente apresenta todas as solicitações na fila.

Além disso, você tem flexibilidade para usar o prompt usando os seguintes recursos:

• Candidatos: os candidatos permitem que você defina respostas com base nos recursos do dispositivo de um usuário. Por exemplo, o Assistente pode exibir respostas completas somente quando o usuário interagir com a ação em um dispositivo com funcionalidade de exibição.
• Variantes: são variantes alternativas de uma única mensagem. Por exemplo, é possível fazer com que o Google Assistente escolha entre cinco variantes diferentes de mensagens de boas-vindas sempre que um usuário invocar sua ação.
• Suggestions: as sugestões fornecem aos usuários em dispositivos com funcionalidade de exibição ícones de sugestão quando o Assistente exibe a solicitação.

Um prompt padrão usa um candidato, uma variante e uma resposta first_simple.

Observação: como prática recomendada, use content para oferecer suporte à resposta first_simple. Por exemplo, se a first_simple fornece opções para pedir uma bebida, você pode usar content para fornecer recursos visuais para as opções de bebida. Essa abordagem garante que os usuários recebam as informações importantes, independentemente do dispositivo usado. Como alternativa, use candidatos para fornecer respostas diferentes com base no dispositivo.

Candidatos

Em uma solicitação, o objeto candidates permite definir respostas com base nos recursos do dispositivo de um usuário. Por exemplo, o Assistente pode exibir respostas completas somente quando o usuário interagir com a ação em um dispositivo com funcionalidade de exibição. Para definir os tipos de dispositivo em que o Google Assistente pode retornar um candidato, use a propriedade selector do objeto candidates.

No exemplo abaixo, a propriedade selector contém as informações de capacidade do dispositivo. As solicitações definidas no primeiro candidato são enviadas aos usuários em um dispositivo que pode renderizar respostas avançadas. O segundo candidato contém solicitações para usuários que só podem receber respostas de texto e fala.

YAML

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    first_simple:
      variants:
        - speech: Here's a simple message.
    content:
      card:
        title: Image card title
        text: Some details about the image
        image:
          url: 'https://www.example.com/image/'
  - first_simple:
      variants:
        - speech: Text explains what the image might have shown in more detail.
    

JSON

{
  "candidates": [{
    "selector": {
      "surface_capabilities": {
        "capabilities": ["RICH_RESPONSE"]
      }
    },
    "first_simple": {
      "variants": [{
        "speech": "Here's a simple message."
      }]
    },
    "content": {
      "card": {
        "title": "Image card title",
        "text": "Some details about the image",
        "image": {
          "url": "https://www.example.com/image/"
        }
      }
    }
  }, {
    "first_simple": {
      "variants": [{
        "speech": "Text explains what the image might have shown in more detail."
      }]
    }
  }]
}
    

Você pode fornecer um ou mais requisitos de capacidade para um determinado candidato. A lista a seguir descreve cada um dos requisitos de capacidade disponíveis:

• SPEECH: o dispositivo pode falar com o usuário por conversão de texto em voz ou SSML.
• RICH_RESPONSE: o dispositivo pode exibir respostas avançadas, como cards, listas e tabelas.
• LONG_FORM_AUDIO: o dispositivo pode tocar mídia de áudio em formato longo, como músicas e podcasts.
• INTERACTIVE_CANVAS: o dispositivo pode exibir uma resposta de tela interativa.
• WEB_LINK: o dispositivo pode usar links da Web em respostas avançadas para abrir um navegador da Web.
• HOME_STORAGE: o dispositivo pode armazenar e acessar dados do armazenamento doméstico.

Variantes

As variantes fornecem uma maneira de definir várias versões de uma resposta. Quando o Google Assistente envia a solicitação a um usuário, uma das variantes é escolhida aleatoriamente. Como prática recomendada no design de conversas, forneça respostas alternativas aos usuários quando eles conversarem com sua ação.

Por exemplo, forneça diferentes variantes da mensagem de boas-vindas para que os usuários não ouçam a mesma resposta sempre que invocarem sua ação:

YAML

candidates:
  - first_simple:
      variants:
        - speech: Hello.
        - speech: Hi there.
        - speech: Welcome.
    

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Hello."
      },{
        "speech": "Hi there."
      },{
        "speech": "Welcome."
      }]
    }
  }]
}
    

Sugestões

As sugestões fornecem ícones aos usuários em dispositivos com tela de exibição quando o Google Assistente exibe a solicitação. Use ícones de sugestão para dar respostas ao usuário e continuar ou dinamizar a conversa. Quando tocado, um ícone de sugestão retorna o texto exibido à conversa na íntegra, como se o usuário tivesse digitado.

Você pode ter no máximo oito sugestões em uma única solicitação, cada uma com um comprimento máximo de 25 caracteres em texto simples.

Para adicionar uma sugestão, forneça um objeto Suggestion que contenha cada sugestão em um campo title separado. Cada título precisa ser exclusivo entre o conjunto de ícones de sugestão. No Actions Builder, esse objeto é representado em YAML e JSON como suggestions.

Por exemplo, você pode fornecer sugestões de "Sim" e "Não" ao lado de uma pergunta:

YAML

candidates:
  - first_simple:
      variants:
        - speech: 'Welcome, do you want to play a game?'
    suggestions:
      - title: 'Yes'
      - title: 'No'
    

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Welcome, do you want to play a game?"
      }]
    },
    "suggestions": [{
      "title": "Yes"
    }, {
      "title": "No"
    }]
  }]
}