A Propriedade de Metadados nos Componentes de Resposta Comuns

Use a propriedade Metadados nos componentes Resposta Comum para definir como as mensagens serão exibidas aos usuários.

Defina os metadados em dois níveis: no nível raiz, em que você define a saída e as ações que são específicas do próprio componente e no nível de resposta, em que você define a exibição e o comportamento específicos do texto, da lista, do cartão ou das mensagens de anexo que esse componente gera.
metadata:
  responseItems:
  - text: "To which location do you want the pizza to be delivered?"
    type: "text"
    name: "What location"
    separateBubbles: true
  globalActions:
  - label: "Send Location"
    type: "location"
    name: "SendLocation"
Propriedade Descrição 0brigatório?
responseItems Uma lista de itens de resposta, cada um dos quais resulta em uma nova mensagem enviada ao cliente de chat (ou várias mensagens quando você define a iteração para o item de resposta usando a propriedade iteratorVariable ou uma combinação das propriedades iteratorVariable e iteratorExpression). Defina esses itens de resposta usando estes valores:
  • text - Bolhas de texto (a propriedade text) que podem incluir uma lista de botões que geralmente são exibidos como botões.

    Para entidades compostas (o que significa que a propriedade variable nomeia uma variável de entidade composta), você pode usar um prompt de expressão do FreeMarker para obter um valor para a entidade atual ( “${system.entityToResolve.value.prompt}”).

  • cards - Uma série de cartões que rolam na horizontal ou vertical.

  • attachment - Uma imagem, áudio, vídeo ou anexo de arquivo que os usuários podem fazer upload ou download.

  • editForm - Um formulário interativo.
  • form
  • dataSet
Sim
globalActions Uma lista de ações globais, o que significa que elas não são específicas de nenhum dos itens de resposta. Essas ações geralmente são exibidas na parte inferior da janela de chat. No Facebook Messenger, por exemplo, essas opções são chamadas de respostas rápidas. No
keywords Uma lista de palavras-chave que correspondem às palavras-chave digitadas por um usuário para um payload de postback correspondente. As palavras-chave suportam canais somente de texto nos quais os botões de ação não são bem renderizados. No
Também é possível configurar os metadados dos vários itens de resposta, como texto, cartão ou mensagens de anexo.
Propriedade Descrição 0brigatório?
type O tipo de item de resposta que determina o formato da mensagem. Você pode definir uma mensagem como text, attachment ou cards. Sim
name Um nome para o item de resposta que é usado internamente; não é usado no runtime. No
iteratorVariable Adiciona dinamicamente vários itens de texto, anexo ou palavra-chave à resposta iterando os elementos variáveis. No
iteratorExpression Uma expressão FreeMarker usada para exibir valores de um array aninhado na variável especificada pela propriedade iteratorVariable.

Por exemplo, se você tiver definido o valor da propriedade iteratorVariable como "team" e essa variável tiver um elemento chamado members do qual você deseja exibir os valores, use a expressão ${team.value.members}.

No
visible Determina como as mensagens são exibidas por entrada e canal do usuário. Consulte A Propriedade visível. No
rangeStart Se você tiver especificado uma iteratorVariable, poderá produzir um subconjunto de itens de resposta especificando a propriedade rangeStart em combinação com a propriedade rangeSize. Você pode informar um valor codificado ou usar uma expressão FreeMarker que mencione uma variável de fluxo de caixas de diálogo que contenha o início da faixa. Usando uma variável rangeStart, você pode ir até o próximo conjunto de dados definindo a variável rangeStart no payload da opção de pesquisa. Veja um exemplo das propriedades rangeStart e rangeSize no estado OrderPizza do CrcPizzaBot. No
rangeSize O número de itens de resposta que serão exibidos conforme especificado pelas propriedades iteratorVariable e rangeStart. No
channelCustomProperties Uma lista de propriedades que acionam funções específicas de um canal. Como essas funções são específicas da plataforma, elas estão fora do componente Resposta Comum e, portanto, não podem ser controladas pelo nível raiz do componente nem pelas propriedades no nível do item de resposta. Você pode encontrar um exemplo dessa propriedade no estado OrderPizza do CrcPizzaBot.
channelCustomProperties:
          - channel: "facebook"
            properties:
              top_element_style: "large"
Para obter detalhes sobre como usar o channelCustomProperties, bem como as propriedades disponíveis para cada canal, consulte Extensões Específicas do Canal.
No

Propriedades de Metadados de Palavra-chave

Você pode criar atalhos para ações definindo as propriedades de palavra-chave e label. Por exemplo, elas permitem que os usuários digitem P para Pequeno.

O snippet a seguir ilustra como você pode ter um conjunto de palavras-chave geradas com base em uma variável pizzaSize que contém a lista de valores definidos para uma entidade PizzaSize.
      
responseItems:         
- type: "text"  
  text: "What size of pizza do you want?" 
  actions: 
  - label: "(${enumValue[0]?upper_case})${enumValue?keep_after(enumValue[0])}"
    type: "postback"
    keyword: "${enumValue[0]?upper_case},${(enumValue?index)+1}"
    payload: 
      variables: 
        pizzaSize: "${enumValue}" 
    iteratorVariable: "pizzaSize.type.enumValues"
Propriedade Descrição 0brigatório?
keyword Uma lista de palavras-chave que acionam o payload de postback definido pela propriedade payload. Você pode usar uma expressão do FreeMarker para retornar palavras-chave que a propriedade interatorVariable gera com base nas entidades de lista de valores usando as propriedades type e enumValues (iteratorVariable: "pizzaSize.type.enumValues"). Sim
label O label da ação, que pode ser uma string de texto ou uma expressão do Apache FreeMarker. Por exemplo, uma expressão que indica uma palavra-chave de duas letras seria assim:

label: "(${enumValue[0]?upper_case}${enumValue[1]?upper_case})${enumValue?keep_after(enumValue[1])}"

Para suporte a vários idiomas, use uma expressão do Apache FreeMarker que mencione um pacote de recursos.
No
skipAutoNumber Defina como true para suprimir a numeração automática de um item chave quando a opção Ativar Numeração Automática em Cartões estiver definida no Digital Assistant ou no nível da habilidade. No
visible Determina como as mensagens de texto são exibidas por entrada e canal do usuário. Consulte A Propriedade visível No
iteratorVariable Adiciona dinamicamente várias palavras-chave repetindo os itens armazenados na variável especificada. Por exemplo, iteratorVariable: "pizzaSize.type.enumValues". No
iteratorExpression Uma expressão FreeMarker usada para exibir valores de um array aninhado na variável especificada pela propriedade iteratorVariable.

Por exemplo, se você tiver definido o valor da propriedade iteratorVariable como "team" e essa variável tiver um elemento chamado members do qual você deseja exibir os valores, use a expressão ${team.value.members}.

payload O payload de postback, que tem as propriedades a seguir.
  • action — A ação de destino.
  • <variable names> - Define valores para variáveis.
Defina pelo menos uma dessas propriedades. Consulte As Propriedades de payload.
 

Extrair Palavras-chave de Mensagens

Embora o componente acione um postback quando os usuários digitam um número, você pode estender sua habilidade para suportar uma entrada mais ampla, como First ou let's try the 1st item. Para fazer isso, crie uma variável de matriz para as frases-chave (por exemplo, primeiro,1o,um, segundo, 2o, dois, etc.)

Em seguida, faça referência à variável na propriedade keyword nos metadados. Por exemplo, isso é o que pode parecer em um fluxo para pedir uma pizza.
- keyword: "${pizzas.name},<#if pizzas?index <KEYWORDS_VAR.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
Nessa definição, a última palavra-chave se baseia no início da faixa atual. Ela está definida como a última pizza atualmente exibida, com base no número de vezes em que o cliente digitou mais.

A Propriedade visível

Defina a exibição de acordo com a entrada e o canal do usuário usando a propriedade visible opcional.
Propriedade Descrição 0brigatório?
expression A diretiva do Apache FreeMarker que mostra ou oculta condicionalmente texto, cartão ou anexos. Por exemplo, o estado OrderPizza do CrcPizzaBot usa ""<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>" No
channels:
 include:
 exclude:
Para include e exclude, informe uma lista separada por vírgulas dos tipos de canal cujo texto, cartão ou anexo deve ser mostrado (include) ou ficar oculto (exclude). Os valores válidos do canal são:
  • facebook

  • webhook

  • websdk

  • androidsdk

  • iossdk

  • twilio

  • slack

  • msteams

  • cortana

  • test

metadata:
  responseItems:
  - type: "text"
    text: "This text is only shown in Facebook Messenger"
    visible:
      channels:
        include: "facebook"             
  - type: "text"
    text: "This text is NOT shown in Facebook Messenger and Twilio"
    visible:
      channels:
        exclude: "facebook, twilio"
    actions:
    - label: "This action is only shown on web channel"
      type: "postback"
      payload:
        action: "someAction"
      visible:
        channels:
          include: "websdk"
No
onInvalidUserInput Um flag booliano que mostra o item de texto ou anexo quando o usuário digita uma entrada válida (value=false) ou quando digita uma que não é válida (value=true). No
onDisambiguation Quando true, mostra apenas o item de resposta, o cartão ou a ação quando um prompt de desambiguação é mostrado. No
entitiesToResolve Use esta propriedade para criar uma mensagem personalizada para cada item composto. Adicione uma lista delimitada por vírgulas de nomes de itens compostos para os quais o item de resposta deve ser mostrado (include) ou oculto (exclude).
visible:
           entitiesToResolve:
           include: "Amount"
No

As Propriedades de Metadados de Ação

Você pode definir ações para um cartão ou listas, um tipo de resposta ou ações globais para um componente (como ações de resposta rápida do Facebook). Não é possível configurar ações para mensagens de anexo.

Propriedade Descrição 0brigatório?
type O tipo de ação:
  • postback - Retorna um objeto JSON que contém o estado, ação e variáveis.

  • share — Abre uma caixa de diálogo de compartilhamento no cliente do messenger, permitindo que os usuários compartilhem bolhas de mensagens com seus amigos.

  • call — Chama o número de telefone especificado no payload.

  • url — Abre o URL especificado no payload do browser. No Facebook Messenger, você pode especificar a propriedade channelCustomProperties com webview_height_ratio, messenger_extensions e fallback_url.

  • location — Retorna o local atual. No Facebook Messenger, o local atual não é suportado para respostas de texto ou cartão. Só é suportado com uma Resposta Rápida. Para obter mais informações, consulte a documentação da Plataforma do Facebook Messenger.

Sim
label Um label para a ação. Para localizar esse label, você pode usar uma expressão do FreeMarker para mencionar uma entrada no pacote de recursos do seu bot. Sim
iteratorVariable Essa opção adiciona diversas ações repetindo os itens armazenados na variável especificada. Você não pode usar esta propriedade com as ações de compartilhamento e local. No
iteratorExpression Uma expressão FreeMarker usada para exibir valores de um array aninhado na variável especificada pela propriedade iteratorVariable.

Por exemplo, se você tiver definido o valor da propriedade iteratorVariable como "team" e essa variável tiver um elemento chamado members do qual você deseja exibir os valores, use a expressão ${team.value.members}.

Número
imageUrl O URL da imagem usada para um ícone que identifica uma ação. Você pode usar essa propriedade para exibir um ícone do botão de resposta rápida do Facebook (que é uma ação global). Número
skipAutoNumbering Quando definido como true, esta propriedade exclui uma ação de postback individual da numeração automática. É possível usar essa propriedade para uma resposta de texto ou cartão. Número
channelCustomProperties Uma lista de propriedades com alguma funcionalidade específica do canal de trigger que não é controlada pelas propriedades de ação padrão. Você encontra um exemplo no estado OrderPizza do CrcPizzaBot. Número
name Um nome que identifica a ação na plataforma do Digital Assistant. Esse nome é usado internamente e não é exibido na mensagem. Número
visible Determina como os anexos são exibidas por entrada e canal do usuário. Consulte A Propriedade visível. Número
payload Um objeto de payload para os itens de resposta call, url e postback. Consulte As Propriedades de payload. Número

As Propriedades de payload

Propriedade Descrição 0brigatório?
action Uma transição action que é acionada quando o usuário escolhe essa ação. Número
variables Define os valores das variáveis quando você define o tipo de ação como postback e adiciona propriedades de payload nome para as variáveis. Quando o usuário toca na ação, as variáveis são definidas com os valores especificados por essa propriedade. Número
url O URL do site que é aberto quando os usuários tocam nessa ação. Essa propriedade é obrigatória para o tipo de ação url.
phoneNumber O número de telefone que é chamado quando um usuário toca nessa ação. Essa propriedade é obrigatória para o tipo de ação call.

Como as Ações Não Postback São Renderizadas em Canais Somente Texto?

Algumas coisas a serem observadas para essas propriedades de metadados de ação para componentes de Resposta Comum.

  • Se o canal somente texto suportar hiperlinks, você poderá usá-los no lugar de botões quando o tipo de ação global for url ou call.

  • Os tipos de ação share e location serão ignorados ou não serão renderizados.

Dica:

Não é possível enumerar ações de postback como url e call porque elas não são transmitidas ao Mecanismo de Caixa de Diálogo; portanto, não podem ser acionadas por palavras-chave. Consequentemente, se você misturar os dois tipos de ações, a mensagem do seu bot poderá parecer inconsistente porque apenas algumas opções são numeradas.
Uma imagem de runtime com numeração de postback e não postback.
Usando o SDK, você pode criar uma saída mais consistente desativando a numeração automática para o postback. Por exemplo :
{
  "type": "text",
  "text": "Please choose one of the following options",
  "actions": [
    {
      "type": "url",
      "label": "Check out our website",
      "url": "http://www.oracle.com"
    },
    {
      "type": "postback",
      "label": "<#if autoNumberPostbackActions.value>Enter 1 to Order pizza<#else>Order Pizza<#if>"
      "skipAutoNumber": true
      "keyword": "1"
      "postback": { ...}
    }
  ]
}

O Item de Resposta de Texto

Estas são as propriedades dos itens de resposta de texto nos componentes de Resposta Comum.

Propriedade Descrição 0brigatório?
text O texto que solicita ação do usuário. Sim
iteratorExpression Uma expressão FreeMarker usada para exibir valores de um array aninhado na variável especificada pela propriedade iteratorVariable.

Por exemplo, se você tiver definido o valor da propriedade iteratorVariable como "team" e essa variável tiver um elemento chamado members do qual você deseja exibir os valores, use a expressão ${team.value.members}.

 
iteratorVariable Adiciona dinamicamente vários itens de texto, anexo ou palavra-chave à resposta iterando os elementos variáveis. Número
footerText Texto exibido na parte inferior da mensagem (abaixo das ações de texto e botão, se houver). Adicione um rodapé para melhorar a saída em canais somente texto. Conforme descrito em Rodapés, você pode usar expressões do FreeMarker para condicionalizar o texto do rodapé para canais somente texto. Número
separateBubbles Você poderá definir essa propriedade se também definir a propriedade iteratorVariable. Quando você define essa propriedade como true, cada item de texto é enviado como outra mensagem; por exemplo, Pizzas e Pastas nos estados ShowMenu e OrderPizza do CrcPizzaBot. Se você defini-la como false, uma única mensagem de texto será enviada, uma na qual cada item de texto começará em uma nova linha. Número
visible Determina como as mensagens de texto são exibidas por entrada e canal do usuário. Consulte A Propriedade visível. Número
actions A ação de postback. Para suporte somente texto, você pode definir palavras-chave. Número
Se você quiser ver um exemplo de resposta de texto com ações, examine os metadados do estado showMenu do CrcPizzaBot: Como ele nomeia postback como ação, ele permite que a habilidade trate um comportamento inesperado do usuário, como selecionar um item uma mensagem mais antiga, em vez de selecionar um na mensagem mais recente.
metadata:
  responseItems:
    - type: "text"
      text: "Hello ${profile.firstName}, this is our menu today:"
      footerText: "${(textOnly.value=='true')?then('Enter number to make your choice','')}"
      name: "hello"
      separateBubbles: true
      actions:
        - label: "Pizzas"
          type: "postback"
          keyword: "${numberKeywords.value[0].keywords}"
          payload:
            action: "pizza"
          name: "Pizzas"
        - label: "Pastas"
          keyword: "${numberKeywords.value[1].keywords}"
          type: "postback"
          payload:
            action: "pasta"
          name: "Pastas"

O Item de Resposta de Cartão

Estas são as propriedades dos itens de resposta do cartão nos componentes de Resposta Comum.

Propriedade Descrição 0brigatório?
cardLayout O layout do cartão: horizontal (o padrão) e vertical. Sim
headerText Texto do cabeçalho. Por exemplo: headerText: "<#if cardsRangeStart?number == 0>Here are our pizzas you can order today:<#else>Some more pizzas for you:</#if>" . Número
title O título do cartão Sim
description A descrição do cartão, que é exibida como subtítulo. Número
imageUrl O URL da imagem que é exibida abaixo do subtítulo. No
cardUrl O URL de um site. É exibido como hiperlink no cartão, que os usuários tocam para abrir. No
iteratorExpression Uma expressão FreeMarker usada para exibir valores de um array aninhado na variável especificada pela propriedade iteratorVariable.

Por exemplo, se você tiver definido o valor da propriedade iteratorVariable como "team" e essa variável tiver um elemento chamado members do qual você deseja exibir os valores, use a expressão ${team.value.members}.

 
iteratorVariable Adiciona dinamicamente vários cartões à resposta, repetindo os itens armazenados na variável que você especifica para essa propriedade. Embora você defina a variável como string, ela contém um array JSON quando é usada como variável de iterador. Você pode mencionar as propriedades em um objeto do array com uma expressão como ${iteratorVarName.propertyName}. Por exemplo, com uma variável de iterador denominada pizzas, a propriedade de nome de uma pizza pode ser referenciada com a expressão ${pizzas.name}. No
rangeStart Se você tiver especificado uma variável iteratorVariable, poderá produzir um subconjunto de cartões especificando a propriedade rangeStart em combinação com a propriedade rangeSize. Você pode informar um valor codificado ou usar uma expressão FreeMarker que mencione uma variável que contenha o início da faixa. Usando uma variável rangeStart, você pode ir até o próximo conjunto de dados definindo a variável rangeStart no payload de uma opção de pesquisa. No
rangeSize O número de cartões que serão exibidos conforme especificado pelas propriedades iteratorVariable e rangeStart. No
visible Determina como os labels de ação são renderizados por entrada e canal do usuário. Consulte A Propriedade visível. No

Você pode designar um conjunto de ações específicas de um determinado cartão ou uma lista de ações anexadas ao final da lista de cartões.

O estado OrderPizza do CrcPizzaBot inclui uma definição de item de resposta do cartão, conforme mostrado no seguinte trecho de código:
responseItems:
  - type: "cards"
    headerText: "<#if cardsRangeStart?number == 0>Here are our pizzas you can order today:<#else>Some more pizzas for you:</#if>"
    cardLayout: "vertical"
    name: "PizzaCards"
    actions:
      - label: "More Pizzas"
        keyword: "more"
        type: "postback"
        skipAutoNumber: true
        visible:
          expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
        payload:
          action: "more"
          variables:
            cardsRangeStart: "${cardsRangeStart?number+4}"
        name: "More"
    cards:
      - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        name: "PizzaCard"
        iteratorVariable: "pizzas"
        rangeStart: "${cardsRangeStart}"
        rangeSize: "4"
        actions:
          - label: "Order Now"
            type: "postback"
            payload:
              action: "order"
              variables:
                orderedPizza: "${pizzas.name}"
                orderedPizzaImage: "${pizzas.image}"
            name: "Order"
            visible:
              expression: "${(textOnly=='true')?then('false','true')}"

Como os Cartões São Renderizados em Canais Somente Texto?

Os componentes de Resposta Comum renderizam respostas como cartões. Quando sua habilidade é executada em um canal somente texto, algumas das propriedades de item de resposta do cartão têm comportamento distinto. Veja aqui algumas coisas para você ter em mente.

  • Não há rolagem vertical ou horizontal (comportamentos definidos pela opção cardLayout). Todos os cartões são renderizados em uma única bolha de mensagem, que pode incluir cabeçalho e rodapé. As propriedades title e description do cartão são separadas por um caractere de nova linha. Você pode numerar a propriedade de título do cartão.

  • Ainda são suportados hiperlinks em canais somente texto, com o endereço configurado para a propriedade cardUrl renderizada na bolha com as propriedades title e description, que são separadas pelo caractere de nova linha.

  • As imagens especificadas pela propriedade imageURL são renderizadas.

  • O texto do label dos botões de ação é exibido (embora os próprios botões não sejam convertidos). Os usuários podem digitar o texto ou, se a numeração automática estiver ativada, poderão digitar o número correspondente, em vez disso, por questões de maior praticidade.


Otimizar Cartões em Canais Somente Texto com Palavras-chave

A maioria dos cartões tem uma única ação, como o botão Pedir Agora do CRCPizzaBot e uma ação global como Mais para carregar o próximo cartão no carrossel. Conforme ilustrado em Como os Cartões São Renderizados em Canais Somente Texto?, o label de cada ação é numerado automaticamente quando a habilidade é executada nos canais SMS/somente texto. Nesses canais, um conjunto de cartões é representado em uma única bolha, que pode se tornar grande e com isso dificultar a leitura. Você pode evitar isso configurando ações de postback não associadas aos labels de ação, mas executadas por palavras-chave do usuário (1,2,3, cheese ou more, por exemplo).


Descrição da ilustração Cards-text-only.png a seguir
Descrição da ilustração cartões-texto-only.png

Você pode ocultar os labels de ação quando sua habilidade é executada em canais somente texto usando essas diretrizes gerais.

Na propriedade de metadados
  • Defina a propriedade keywords. No seguinte trecho de código do CRCPizzaBot, a expressão ${pizza.name} definida para a propriedade de palavra-chave define uma palavra-chave para cada nome de pizza:
    
    metadata:
      keywords:
        - keyword: "${pizzas.name},<#if pizzas?index <numberKeywords.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
          visible:
            expression: "${textOnly.value}"
    ...

    Essas palavras-chave só são adicionadas quando textOnly é verdadeiro.

Nos metadados card:
  • Defina a propriedade title. No seguinte trecho de código, uma expressão usa a variável index do FreeMarker para prefixar um número ao título (retornado por ${pizzas.name} quando o valor da variável textOnly é true). Isso significa que, quando um cliente digitar more, a habilidade carregará outra bolha de mensagem contendo o próximo conjunto de pizzas que começa no Número 5 (rangeSize: "4").
    cards:
            - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${pizzas.name}"
              description: "${pizzas.description}"
              imageUrl: "${pizzas.image}"
              name: "PizzaCard"
              iteratorVariable: "pizzas"
              rangeStart: "${cardsRangeStart}"
              rangeSize: "4"
  • No seguinte trecho de código, as ações do cartão ("Order" e "More Pizzas") só são exibidas quando o valor da variável textOnly é false:
            - label: "More Pizzas"
              keyword: "more"
              type: "postback"
              skipAutoNumber: true
              visible:
                expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
  • Adicione um rodapé que só seja exibido quando o valor da variável textOnly for true.
    footerText: "<#if textOnly=='true'>Enter a pizza number to make your choice<#if cardsRangeStart?number+4 < pizzas.value?size>, or type 'more' to see more pizzas</#if></#if>"

O Item de Resposta de Anexo

O item de resposta attachment inclui as propriedades a seguir.

Propriedade Descrição 0brigatório?
attachmentType O tipo de anexo: image, audio, video e file. Sim
attachmentURL O URL de download ou a origem do anexo. Sim
O estado Confirmation do CrcPizzaBot usa um item de resposta do anexo para exibir a imagem da ordem, uma que é diferente do item retratado no menu.
metadata:
  responseItems:
  - text: "Thank you for your order, your ${pizzaSize} ${orderedPizza} pizza\
      \ will be delivered in 30 minutes at GPS position ${location.value.latitude},${location.value.longitude}!"
    type: "text"
    name: "conf"
    separateBubbles: true
  - type: "attachment"
    attachmentType: "image"
    name: "image"
    attachmentUrl: "${orderedPizzaImage}"

Ação

Uma ação representa algo que o usuário pode selecionar.
Nome Descrição Tipo 0brigatório?
type O tipo de ação string Sim
label O texto descritivo do label da ação. string Pelo menos um label ou imageUrl deve ser incluído.
imageUrl A imagem da ação string Pelo menos uma única propriedade label ou imageUrl deve ser incluída.
style O estilo de renderização do botão "primary", "danger", "default" No
displayType A renderização para o tipo de elemento de ação (botão, link ou ícone) "button", "link", "icon" No
channelExtensions As propriedades de extensão específicas do canal associadas à ação JSONObject No

Campo

Um elemento Field contém as seguintes propriedades:
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo String No
label O rótulo do campo String Sim
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Map<ChannelType, JSONObject> No
marginTop A quantidade de espaço vertical entre este campo e o campo anterior na mesma coluna. Os valores permitidos são none, medium (o padrão) e large. String No
labelFontSize O tamanho da fonte usado para o rótulo do campo. Os valores permitidos são small, medium (o padrão) e large. String No
labelFontWeight A espessura da fonte usada para o rótulo do campo. Os valores permitidos são light, medium (o padrão) e negrito. String No
displayInTable Uma expressão booliana FreeMarker que permite incluir condicionalmente um campo no layout da tabela em um item de resposta dataSet. String Não (o padrão é true)
displayInForm Uma expressão booliana FreeMarker que permite incluir condicionalmente um campo em um Item de Resposta editForm ou no layout do formulário em um item de resposta dataSet String Não (o padrão é true)

Campo ReadOnly

Representa um campo somente leitura. Todos os campos somente leitura herdam as propriedades Field e têm as seguintes propriedades adicionais:
Nome Descrição Tipo 0brigatório?
value O valor do campo string Sim
width A porcentagem sugerida da largura total disponível que o campo deve ocupar em um layout de tabela. número No
alignment O alinhamento do valor em uma coluna de tabela. O alinhamento padrão é right. "left", "center" e "right" No
Observação

Na Versão 23.06 do Oracle Digital Assistant, os campos somente para leitura não são renderizados nos formulários de entrada, mesmo que sejam recebidos no payload da mensagem.
TextField
O elemento TextField herda todas as propriedades do campo ReadOnly. O displayType para esse elemento é "text". Ele tem as seguintes propriedades adicionais:
Nome Descrição Tipo 0brigatório?
truncateAt A posição na qual o texto extenso é truncado e são adicionadas reticências para indicar que o valor foi truncado. Um inteiro No
fontSize O tamanho da fonte usado para o valor field. Os valores permitidos são small, medium (o padrão) e large. String No
fontWeight A espessura da fonte usada para o valor field. Os valores permitidos são leve, médio (o padrão) e negrito. String No
LinkField
O elemento LinkField herda todas as propriedades do campo ReadOnly. Ele tem as seguintes propriedades adicionais:
Nome Descrição Tipo 0brigatório?
linkLabel O rótulo usado para o hiperlink String No
imageUrl O URL da imagem que abre um link quando clicado. String No
MediaField
O elemento MediaField herda todas as propriedades do campo ReadOnly. Ele tem as seguintes propriedades adicionais:
Nome Descrição Tipo 0brigatório?
mediaType O tipo de mídia de campo ("video", "audio", "image") String Sim
ActionField
O elemento ActionField herda todas as propriedades do campo ReadOnly. Ele tem as seguintes propriedades adicionais:
Nome Descrição Tipo 0brigatório?
action A ação que deve ser executada quando o usuário clica no botão de ação. Ação Sim

Form

Representa uma matriz de campos junto com um título.
Nome Descrição Tipo 0brigatório?
title O título exibido acima do layout do formulário String No
fields Uma lista de campos somente leitura no formulário Lista<ReadOnlyField> Sim
formRows Uma lista de linhas exibidas no formulário. Lista<FormRow>  
actions Uma lista de ações Listar<Ação> No
selectAction A ação executada quando o formulário foi selecionado. Quando os usuários passam o mouse sobre o formulário, o rótulo da ação é exibido como uma dica de ferramenta (quando suportado pelo canal). Ação No
channelExtensions As propriedades de extensão específicas do canal associadas à mensagem JSONObject No

FormRow

Nome Descrição Tipo 0brigatório?
columns Uma lista de colunas exibidas na linha do formulário. Listar <Coluna> Sim
selectAction As ações que são executadas quando o formulário é selecionado. Quando os usuários passam o mouse sobre o formulário, o rótulo da ação, ele é exibido como uma dica de ferramenta (quando suportado pelo canal). Ação No
separator Definir esta propriedade como verdadeira insere uma linha separadora acima do conteúdo na linha do formulário. Boolean No
channelExtensions As propriedades de extensão específicas do canal associadas à mensagem JSONObject No

Coluna

Nome Descrição Tipo 0brigatório?
fields Uma lista de campos que são exibidos verticalmente dentro da coluna. Esses campos devem ser instâncias ReadOnlyField quando a coluna for usada em um FormRow dentro de um Form. Os campos podem ser somente leitura e editáveis quando o FormRow é usado em um EditFormMessagePayload. Lista<Campo> Sim
verticalAlignment O alinhamento vertical da coluna em relação às outras colunas na mesma linha do formulário. String No
width Determina a largura da coluna na linha do formulário. Os valores permitidos são auto (o padrão) e stretch. Quando definida como stretch, a coluna usa toda a largura restante depois que qualquer coluna de largura automática é renderizada. Se houver várias colunas definidas como stretch, elas dividirão uniformemente a largura restante. String No
channelExtensions As propriedades de extensão específicas do canal associadas à mensagem JSONObject No

O Item de Resposta editForm

Este item de resposta forma o EditFormMessagePayload que é retransmitido por meio de um canal para o cliente.
Nome Descrição Tipo 0brigatório?
type O tipo de item de resposta. editform Sim
title O título do form String No
items Uma lista de campos, somente para leitura e editáveis. Lista<field> Sim
formColumns O número de colunas usadas para o layout do formulário. O padrão é uma coluna. Inteiro No
actions Uma lista de ações relacionadas ao cartão. Lista<Action> No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo textInput

Um campo para inserir texto livre. Você pode definir os caracteres mínimo e máximo para esse campo e impor a formatação usando expressões regulares.

Este trecho de código ilustra a coleta da entrada do usuário fazendo referência à variável submittedFields gerada (um mapa).
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Description)!''}"
        minLength: 10
        name: Description
        label: Description
        placeholder: What is the expense justification?
        clientErrorMessage: "Description must be 10 characters minimum, 50 characters maximum."
        maxLength: 50
        required: true
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Notes)!''}"
        minLength: 10
        name: Notes
        inputStyle: email
        label: Notes
        placeholder: Expense notes (optional)
        maxLength: 50
        required: false
Este trecho de código ilustra a coleta da entrada do usuário fazendo referência a uma variável composta.
Observação

O item do repositório composto referenciado pode ser uma STRING.
      - displayType: textInput
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Tip'])!''}"
        defaultValue: "${(expense.value.Tip.originalString)!''}"
        displayInForm: "${(((expense.value.TipIncluded.yesno)!'') == 'NO')?then(true, false)}"
        name: Tip
        label: Tip
        placeholder: Enter the tip
        clientErrorMessage: Tip is required
        required: true
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo. textInput (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label O rótulo do campo String Número
defaultValue O valor inicial. De acordo com a expressão FreeMarker no modelo, o valor é uma string quando o item de repositório referenciado (representado por myText) não tem valor ("${(submittedFields.value.myText)!''}"). String Número
validationRegularExpression Uma expressão regular que especifica o formato da entrada de texto. String Número
multiline A definição dessa propriedade como true permite que os usuários insiram várias linhas de texto. Boolean Número
minlength O número mínimo de caracteres necessários para validar o campo. Os usuários receberão uma mensagem de erro se inserirem poucos caracteres. Número Inteiro Número
maxLength O número máximo ou o limite dos caracteres. Número Inteiro Número
inputStyle O formato aplicado ao cliente. Os formatos são:
  • text
  • email
  • url
  • tel
  • password
O formato padrão é texto quando esta propriedade não foi definida.
String Número
placeholder Uma dica que descreve como usar esse campo. Este texto é exibido quando os usuários ainda não inseriram nenhuma entrada. Por exemplo :
What is the expense justification? Enter between 10 and 50 characters.
String Número
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String Número
required Se o envio do formulário requer entrada do usuário neste campo boolean No
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String No
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo datePicker

Um campo com um calendário suspenso que permite que os usuários selecionem um dia, mês e ano. As propriedades maxDate e minDate do componente validam a entrada do usuário.
Observação

O canal do Slack não suporta essa validação de valor mínimo e máximo.
Este trecho de código ilustra como capturar a entrada do usuário usando a variável submittedFields gerada (um mapa).
 - displayType: datePicker
        defaultValue: "${(submittedFields.value.Date)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Este trecho de código ilustra como capturar a entrada do usuário fazendo referência a uma variável composta.
     - displayType: datePicker
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Date'])!''}"
        defaultValue: "${(expense.value.Date.date?number_to_date?iso_utc)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo datePicker (uma String) Sim
id Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label Um rótulo descritivo. String No
defaultValue O valor padrão para o campo, formatado como AAAA-MM-DD. O modelo define essa String como uma expressão FreeMarker do Apache que retorna uma string vazia quando o item do repositório composto referenciado (representado por myDate) tem um valor nulo.
"${(submittedFields1.value.myDate)!''}"
String No
minDate A primeira data no intervalo de dias permitidos. O canal do Slack não suporta essa validação do cliente. String No
maxDate A última data no intervalo de dias permitidos. O modelo define esta String como o dia atual ("${.now?iso_utc[0..9]}"). O canal do Slack não suporta essa validação do cliente. String No
placeholder Uma descrição da entrada esperada que é exibida quando o usuário ainda não selecionou uma data. String No
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String No
required Se o envio do formulário requer entrada do usuário neste campo booleano No
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String No
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo timePicker

Permite que o usuário insira um valor de tempo dentro de um intervalo especificado. As propriedades maxTime e minTime do componente validam a entrada do usuário.
Observação

O canal do Slack não suporta validação de valor mínimo e máximo.
O campo do seletor de horas lê e grava o valor no formato de 24 horas. O formato de exibição no canal do cliente pode usar o formato de 12 horas com uma indicação de AM/PM, mas deve sempre retornar uma hora formatada de 24 horas.
O trecho de código a seguir ilustra como capturar a entrada do usuário usando a variável submittedFields gerada (um mapa).
      - displayType: timePicker
        defaultValue: "${(submittedFields.value.Time.value?time.xs?string['hh:mm a'])!''}"
        maxTime: "23:00"
        minTime: "13:00"
        name: Time
        label: Expense Time
        placeholder: What time was the expense?
        clientErrorMessage: This time is outside the limits.
        required: true
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo timePicker (uma String) Sim
id Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label Um rótulo que descreve os parâmetros de seleção de tempo. String Sim
defaultValue O valor inicial deste campo, no formato de 24 horas. O modelo define essa String como uma expressão FreeMarker do Apache que retorna uma string vazia quando o item do repositório composto referenciado (representado por myTime) tem um valor nulo.
"${(submittedFields.value.myTime)!''}"
String No
minTime Define as primeiras horas permitidas, inseridas como HH:MM no formato de 24 horas. Por exemplo, 00:00 String No
maxTime Define as últimas horas permitidas, inseridas como HH:MM, no formato de 24 horas. Por exemplo, 13:00. String No
placeholder Uma dica para a entrada. De acordo com o modelo, o exemplo placeholder é Pick a time in the morning, que reflete os valores minTime e maxTime de exemplo do modelo de 00:00 e 12:00. String Número
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String Número
required Se o envio do formulário requer entrada do usuário neste campo boolean Número
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. Por exemplo, Time must be in the morning. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String Número
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String Número
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo numberInput

Coleta a entrada de número dentro de um intervalo especificado.
      - displayType: numberInput
        minValue: 5
        serverErrorMessage: "${(amountError.value)!''}"
        maxValue: 500
        defaultValue: "${(submittedFields.value.Amount)!''}"
        name: Amount
        label: Amount
        placeholder: Enter the expense amount (do not include currency symbol)
        clientErrorMessage: Amount is required and must be between 5 and 500 characters
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo numberInput (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label Um rótulo descritivo para o valor de data necessário do usuário. String No
defaultValue O valor inicial. O modelo define esta String como uma expressão FreeMarker do Apache que retorna uma string vazia quando o item do repositório composto referenciado (representado por myNumber) tem um valor nulo. "${(submittedFields.value.myNumber)!''}" String No
maxvalue O maior número permitido. O canal do Slack não suporta validação de valor mínimo ou máximo. Número Inteiro No
minvalue Um menor número permitido Número Inteiro No
placeholder Uma dica que descreve como usar o campo. Este texto é exibido quando o usuário ainda não inseriu um número. String No
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String No
required Se o envio do formulário requer entrada do usuário neste campo boolean No
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String No
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo singleSelect

Permite que os usuários selecionem um único valor de uma lista predefinida. Você pode estilizar esse controle como uma lista que os usuários podem consultar e selecionar, ou como um conjunto de botões de opção. Este elemento tem renderização específica do canal:
  • No canal do Microsoft Teams, esse elemento sempre é renderizado como uma lista (mesmo quando layoutStyle está definido como radioGroup) porque Cartões Adaptáveis não suportam botões de opção.
  • No canal do Slack, esse elemento é renderizado como uma lista em vez de um grupo de rádio quando há mais de dez opções.
O trecho de código a seguir ilustra o preenchimento da lista usando a variável submittedFields gerada (uma variável de mapa)
 - displayType: singleSelect
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true

Dica:

Embora clientErrorMessage seja um atributo opcional, recomendamos que você o defina para habilidades em execução no canal do Microsoft Teams porque Cartões Adaptáveis não geram uma mensagem quando a validação do cliente falha.
Este trecho de código ilustra como preencher a lista fazendo referência a uma entidade composta:
     - autoSubmit: true
        displayType: singleSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Type'])!''}"
        defaultValue: "${(expense.value.Type.value)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo singleSelect (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label O texto do rótulo do campo que descreve o conteúdo da lista de seleção única. String Sim
defaultValue A seleção default. O modelo define esse valor de String como uma expressão FreeMarker do Apache que retorna uma string vazia quando o item do repositório composto referenciado (representado por mySingleSelect) tem um valor nulo. "${(submittedFields.value.mySingleSelect)!''}" String No
options Uma matriz das opções disponíveis. O modelo define essas opções estaticamente com pares individuais label e value com valores de String, mas você pode preencher as opções de seleção dinamicamente usando as propriedades iteratorVariable e iteratorExpression:
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
Nesse trecho de código, os valores do tipo de despesa retornados pelas propriedades type e enum são sequenciados na lista usando o incorporado split.
Lista<opção> Sim
layoutStyle Como as opções de seleção única são apresentadas no formulário. Eles podem ser agrupados como uma lista (layoutStyle: list) ou como botões de opção (layoutStyle: radioGroup). String  
placeholder Uma dica que descreve como usar o campo. Ela é exibida quando o usuário ainda não fez a seleção. Por exemplo :
label: 
        placeholder: Select an expense type. You can pick only one.
Este espaço reservado é exibido somente para a renderização do layout da lista.
String No
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String No
required Se o envio do formulário requer entrada do usuário neste campo boolean No
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String No
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo multiSelect

Permite que os usuários escolham um ou mais valores de uma lista predefinida. Você pode estilizar isso como uma lista de opções que os usuários podem consultar ou como um conjunto de caixas de seleção. Este elemento tem renderização específica do canal:
  • No canal do Microsoft Teams, esse elemento sempre é renderizado como uma lista (mesmo quando layoutStyle está definido como checkboxes) porque Cartões Adaptáveis não suportam caixas de seleção múltipla.
  • No canal do Slack, esse elemento é renderizado como uma lista em vez de um conjunto de caixas de seleção múltipla quando há mais de dez opções.
Este trecho de código ilustra como preencher a lista fazendo referência à variável submittedFields gerada (um mapa).
 - displayType: multiSelect
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select one or more attendees

Este trecho de código ilustra como fazer referência a uma entidade composta para preencher a lista.
     - displayType: multiSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Attendees'])!''}"
        displayInForm: "${(((expense.value.Type.value)!'') == 'Meal')?then(true, false)}"
        defaultValue: "${(expense.value.Attendees?map(a -> a.value)?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select attendees
        clientErrorMessage: Attendees are required when expense type is a Meal
        required: true
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo multiselect (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label O label de campo que descreve o conteúdo da lista multiSelect. String Sim
defaultValue A seleção default. O modelo define essa String como uma expressão FreeMarker do Apache que retorna uma string vazia quando o item do repositório composto referenciado (representado por myMultiSelect) tem um valor nulo.
"${(submittedFields.value.myMultiSelect?join(','))!''}"
List<String> Número
options Uma matriz das opções disponíveis. O modelo define essas opções estaticamente com pares individuais label e value com valores de String, mas você pode preencher as opções de seleção dinamicamente usando as propriedades iteratorVariable e iteratorExpression:
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
List<option> Sim
placeholder Uma dica que descreve como usar o campo. Ele é exibido quando o usuário não fez nenhuma seleção.
label: Attendees
        placeholder: Select one or more attendees
Este espaço reservado é exibido somente para o layout da lista. Não está disponível para layouts de caixa de seleção.
String No
layoutStyle O layout das opções multiSelect. As opções são list e checkboxes. String No
autoSubmit Quando definido como true, o formulário é enviado parcialmente quando o usuário informa um valor para o campo. Em FormSubmissionMessagePayload, partialSubmitField é definido como o nome do campo em que autoSubmit é definido como true. Recomendamos que você configure o envio automático para campos dependentes condicionalmente. Por exemplo, defina essa propriedade quando um campo precisar ser exibido ou oculto com base no valor de outro campo ou quando os valores permitidos de um campo dependerem do valor definido em outro campo. Ao enviar automaticamente um campo do qual outros campos dependem, o formulário pode ser atualizado imediatamente com as alterações relevantes nos campos dependentes. String No
required Se o envio do formulário requer entrada do usuário neste campo booleano No
clientErrorMessage A mensagem usada por alguns clientes (MS Teams, Apple Business Messaging) quando a validação do lado do cliente falha. No Slack, essa propriedade só é usada quando o formulário editável é exibido na página de conversa. Ele não é exibido em uma caixa de diálogo modal. String No
serverErrorMessage Uma mensagem de erro que é enviada ao cliente quando a validação do servidor de um valor de campo de formulário falha. Quando ocorrerem erros do servidor dessa classificação, recomendamos que a mensagem de formulário atual seja substituída, em vez de uma nova mensagem adicionada à conversa configurando a propriedade channelExtensions para indicar que a última mensagem de formulário deve ser substituída. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O campo de alternância

Apresenta um switch para duas opções. No canal do Slack, esse controle é renderizado como caixas de seleção.
Observação

No canal do Slack, esse elemento é renderizado como um par de botões de opção.
Este trecho de código ilustra a captura da entrada do usuário fazendo referência à variável submittedForms gerada (um mapa).
      - displayType: toggle
        defaultValue: "false"
        name: TipIncluded
        labelOn: Tip
        label: Tip Included?
        valueOff: "false"
        labelOff: No Tip
        valueOn: "true"
Este trecho de código ilustra a captura da entrada do usuário fazendo referência a uma variável composta.
      - autoSubmit: true
        displayType: toggle
        defaultValue: "${(expense.value.TipIncluded.yesno)!'YES'}"
        name: TipIncluded
        labelOn: "Yes"
        label: Tip Included?
        valueOff: "NO"
        labelOff: "No"
        required: false
        valueOn: "YES"
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo toggle (uma String) Sim
id Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
label Um label que descreve o que acontece quando a alternância é ativada. String Sim
defaultValue O valor inicial. Se quiser que a alternância seja ativada inicialmente, defina-a com o valor valueOn. O modelo define esta String como uma expressão FreeMarker do Apache que alterna a alternância quando o item do repositório composto referenciado (representado por myToggle) tem um valor nulo.
"${(submittedFields.value.myToggle)!'true'}"
String Sim
valueOff O valor quando a alternância é desativada. O valor padrão, de acordo com o modelo, é false (valueOff: "false" ). String Sim
valueOn O valor quando a alternância é ativada. O valor default no modelo é true (value On: "true" ) String Sim
labelOn Um rótulo para a posição da alternância String No
labelOff Um rótulo para a posição desativada da alternância. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O Campo de texto

Um elemento de campo contém as seguintes propriedades:
Nome Descrição Tipo 0brigatório?
displayType O tipo de elemento. text (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
value O valor bruto do campo String Sim
width A porcentagem da largura total disponível que o item deve ocupar em um layout de tabela. A largura restante, a partir de 100 menos os itens com uma largura especificada, é igualmente dividida sobre os itens sem uma largura especificada. Inteiro No
alignment O alinhamento do valor com uma coluna de tabela. left, center e right. O padrão é right. No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

O campo de link

Um elemento de campo contém as seguintes propriedades:
Nome Descrição Tipo 0brigatório?
displayType O tipo de campo link (uma String) Sim
name Um nome exclusivo para o campo no formulário de entrada. Este nome é usado como um identificador no runtime. String Sim
value O endereço do URL. Por exemplo: http:www.oracle.com String Sim
width A porcentagem da largura total disponível que o item deve ocupar em um layout de tabela. A largura restante, a partir de 100 menos os itens com uma largura especificada, é igualmente dividida sobre os itens sem uma largura especificada. Número Inteiro No
alignment O alinhamento do valor com uma coluna de tabela. Os valores permitidos são left, center e right. O padrão é right. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No

EditFormMessagePayload

Este payload define o formulário editável que é enviado aos canais.
Nome Descrição Tipo 0brigatório?
type O tipo de payload da mensagem. editForm (uma String) Sim
headerText O texto do cabeçalho exibido acima do formulário. String No
footerText O texto que é exibido abaixo do formulário e das ações, mas acima das ações globais. String No
title O título do form String No
formRows Uma lista de linhas exibidas no formulário. Lista<FormRow> No
fields Uma lista de campos, somente para leitura e editáveis. Lista<field> Sim
formColumns O número de colunas usadas para o layout do formulário. O padrão é uma coluna. Número Inteiro No
actions Uma lista de ações. Lista<Action> No
globalActions Uma lista de ações globais. A renderização dessas ações é específica do canal. Por exemplo, as ações no Facebook são renderizadas por reply_actions. Lista<Action> No
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No
Envio automático de um campo
Quando um campo tem a propriedade autoSubmit definida como true, o cliente envia um FormSubmissionMessagePayload com o mapa submittedField contendo os valores de campo válidos que foram informados até agora ou apenas o valor do campo enviado automaticamente (a implementação é específica do canal). Todos os campos que ainda não foram definidos (independentemente de serem obrigatórios) ou campos que violam uma validação do cliente não são incluídos no mapa submittedField. Se o próprio campo enviado automaticamente contiver um valor que não seja válido, o FormSubmissionMessagePayload não será enviado e a mensagem de erro do cliente será exibida.
Observação

O Microsoft Teams não suporta o envio automático.

SubmitFormAction

Nome Descrição Tipo 0brigatório?
type O tipo de ação submitForm (uma String) Sim
postback O payload de postback, que pode incluir uma propriedade de ação para acionar a navegação. Recomendamos que o valor dessa propriedade seja obtido do objeto de postback FormSubmissionMessagePayload. JSONObject No
variable O nome da variável que armazena os valores enviados. Esses valores estão em FormSubmissionMessagePayload. String No
processingMethod As instruções de processamento usadas pelo componente Resolver Entidades para os valores de campo enviados. Você pode definir isso como FormSubmissionMessagePayload, mas também pode definir:
  • mapVariable
  • separateVariables
  • compositeBag
.
String Sim
label O rótulo da ação de exibição. String Sim - Você deve especificar pelo menos um valor label ou imageUrl.
imageUrl A imagem da ação de exibição. String Você deve especificar pelo menos um valor label ou imageUrl.
channelExtensions Um conjunto de propriedades de extensão específicas do canal. Por exemplo, talvez você queira definir a altura máxima para o Facebook Messenger. Mapa<ChannelType, JSONObject> No
FormSubmissionMessagePayload
Esse payload volta pelos canais para o pipeline do ODA quando o usuário submeteu um formulário clicando em um botão SubmitFormAction. Ela tem as seguintes propriedades:
Nome Descrição Tipo 0brigatório?
type O tipo do payload. "formSubmission" (um valor de String) Sim
submittedFields Pares de chave/valor dos valores de campo enviados. A chave é o nome (ID) do campo. Mapa<String, Objeto> Sim
postback O payload de postback, que pode incluir uma propriedade de ação para acionar a navegação. Recomendamos que o valor seja obtido do SubmitFormAction JSONObject No
partialSubmitField O nome do campo que aciona um envio parcial do formulário. Campos com o envio automático ativado (autoSubmit: true) podem acionar um envio parcial de formulário. String No

Atualizando o Form de Entrada

Quando o usuário final envia o formulário, porque um campo tem autosubmit definido como true ou porque o usuário tocou no botão de ação submitForm, pode haver situações em que o usuário não forneceu todas as informações necessárias ou alguns valores de campo contêm um valor inválido. Nesse caso, o mecanismo de caixa de diálogo enviará um novo EditFormMessagePayload, mas essa mensagem deverá substituir a mensagem de formulário anterior. Para instruir o canal do cliente a substituir a mensagem de formulário anterior, em vez de adicionar uma nova mensagem de formulário à conversa, configure a propriedade de extensão de canal replaceMessage da seguinte forma:
- channel: ${system.channelType}
  properties:
    replaceMessage: "${system.message.messagePayload.type == 'formSubmission'}"
No runtime, essa propriedade é adicionada ao elemento channelExtensions no nível raiz do payload do componente de resposta comum:
...,
"channelExtensions": { "replaceMessage": "true"}

TableMessagePayload

Apresenta os dados em formato tabular e de formulário.
Nome Descrição Tipo 0brigatório?
type O tipo de payload da mensagem "table" Sim
headings Uma lista de cabeçalhos de colunas de tabela Lista<TableHeading> Sim
rows Uma lista de linhas de tabelas Listar<Linha> Sim
forms Uma lista de formulários Lista Sim
formColumns O número de colunas usadas no layout do formulário. O padrão é 1. Número Inteiro Sim
paginationInfo Informações de paginação que podem ser usadas para renderizar botões do conjunto anterior ou seguinte PaginationInfo Sim

Linha

Nome Descrição Tipo 0brigatório?
fields Uma lista de campos somente leitura Listar <ReadOnly Campo> Sim
selectAction As ações que são executadas quando o formulário é selecionado. Quando os usuários passam o mouse sobre o formulário, o rótulo da ação, ele é exibido como uma dica de ferramenta (quando suportado pelo canal). Ação No
channelExtensions As propriedades de extensão específicas do canal associadas à mensagem Mapa<ChannelType>,JSONObject No

TableHeading

Um cabeçalho de tabela contém as seguintes propriedades:
Nome Descrição Tipo 0brigatório?
label O rótulo do cabeçalho String Sim
width A largura da etiqueta do cabeçalho String No
alignment O alinhamento do valor da coluna (left, right ou center). O padrão é right. String No
channelExtensions Um conjunto de propriedades de extensão específicas do canal.
Map<ChannelType>, JSONObject>
No

PaginationInfo

Representa as informações de paginação dos resultados nos objetos Table, Form e Table-Form.

Nome Descrição Tipo 0brigatório?
totalCount A contagem total de resultados número Sim
rangeSize O tamanho do intervalo dos resultados por página número Sim
status A mensagem de status de paginação string Sim
currentRangeSize O tamanho da faixa de resultados atual número Sim
rangeStart O deslocamento inicial do intervalo atual de resultados número Sim
nextRangeSize O tamanho do próximo intervalo de resultados número Sim
hasPrevious Indica se há um conjunto de resultados anterior booleano Sim
hasNext Indica se há um próximo conjunto de resultados booleano Sim

tableFormMessageLayout

Apresenta os dados em formato tabular e de formulário.
Nome Descrição Tipo 0brigatório?
type O tipo de payload da mensagem "tableForm" Sim
headings Uma lista de cabeçalhos de colunas de tabela Lista<TableHeading> Sim
rows Uma lista de linhas de tabelas Listar<Linha> Sim
forms Uma lista de formulários Lista Sim
formColumns O número de colunas usadas no layout do formulário. O padrão é 1. Número Inteiro Sim
showFormButtonLabel O rótulo do botão usado para mostrar o layout do formulário de uma linha específica. String Sim
paginationInfo Informações de paginação que podem ser usadas para renderizar botões do conjunto anterior ou seguinte PaginationInfo Sim

O Item de Resposta dataSet

O item de resposta dataSet permite criar tabelas e formulários. Inclui as propriedades a seguir.

Propriedade Descrição 0brigatório?
layout O estilo de layout usado para renderizar o dataSet. Os valores permitidos são table, form e tableForm. Sim
formColumns O número de colunas usadas para renderizar itens em um layout de formulário. Só é aplicável quando o layout é form ou tableForm. O padrão é 1. No
showFormButtonLabel O label usado para abrir a caixa de diálogo do formulário em um estilo de layout tableForm. No momento, ele só é usado em canais do Slack. Os outros canais suportam a expansão da linha da tabela para mostrar os itens adicionais em um layout de formulário No
data Usado para definir uma entrada de dados no dataSet. Consulte DataSet Propriedades de dados Sim

DataSet Propriedades dos dados

A propriedade data do item de resposta dataSet inclui as seguintes subpropriedades.

Propriedade Descrição 0brigatório?
iteratorExpression Define uma expressão do Freemarker que retorna uma lista de entradas para iteração, permitindo que você adicione dinamicamente várias entradas de dados ao dataSet. No
iteratorVariable Especifica o nome da variável de iterador que você pode usar para fazer referência à entrada de dados atual na lista de entradas de dados que são iteradas. No
rangeSize O número de entradas de dados que serão exibidas ao mesmo tempo quando você tiver especificado as propriedades iteratorExpression e iteratorVariable. No
visible Determina como as mensagens são exibidas por entrada e canal do usuário. Consulte A Propriedade visível. No
formTitle O título usado para a caixa de diálogo do formulário no layout tableForm no canal do Slack. O padrão é View details. No
items Os itens de dados que devem ser exibidos para cada entrada de dados. Consulte DataSet Propriedades do Item de Dados. Sim

DataSet Propriedades do Item de Dados

Propriedade Descrição 0brigatório?
width A porcentagem (expressa como um inteiro) da largura total disponível que o item deve usar em um layout de tabela. A largura restante, a partir de 100 menos os itens com uma largura especificada, é igualmente dividida sobre os itens sem uma largura especificada. No
alignment O alinhamento do valor com uma coluna de tabela. Os valores permitidos são left, center e right. O padrão é left. No
displayType O tipo de exibição do item. Os valores permitidos são text e link. O padrão é text. No
linkLabel O label usado para o hiperlink quando o tipo de exibição é definido como link. O padrão é o valor da propriedade value do item. Número
displayInTable Define se o item deve ser exibido como uma coluna na tabela. Essa propriedade só é aplicável no layout tableForm. O padrão é false. Número
displayInForm Define se o item deve ser exibido como um campo no formulário. Essa propriedade só é aplicável no layout tableForm. O padrão é false. Número
label O label do item de dados. Sim
value O valor do item de dados Sim

A Variável system.entityToResolve

A variável system.entityToResolve fornece informações sobre o status atual do processo de resolução de entidade, conforme executado pelos componentes Resolver Entidades e Resposta Comum. Normalmente, você fará referência às propriedades desse valor de variável nos metadados do componente Resposta Comum quando quiser personalizar mensagens. Você pode usá-la para definir a lógica da mensagem de erro de uma entidade ou para várias propriedades que pertencem aos componentes Resolver Entidades e Resposta Comum. Anexe as seguintes propriedades para retornar o valor da entidade atual:
  • userInput
  • prompt
  • promptCount
  • updatedEntities
  • outOfOrderMatches
  • disambiguationValues
  • enumValues
  • needShowMoreButton
  • rangeStartVar
  • nextRangeStart
Você também pode fazer referência às propriedades nas expressões FreeMarker usadas nas propriedades do item do repositório, como prompt, errorMessage e regras de validação.
Veja um exemplo de uso dessa variável para retornar a entrada do usuário atual em uma mensagem de erro da entidade:
Sorry,'${system.entityToResolve.value.userInput!'this'}' is not a valid pizza size.
Veja um exemplo do uso de várias definições de system.entityToResolve. Entre elas está uma mensagem definida para a propriedade text, que confirma uma atualização feita em um valor de entidade definido anteriormente usando uma diretiva list do Apache FreeMarker e a propriedade updatedEntities.
    metadata:
      responseItems:        
      - type: "text" 
        text: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
      - type: "text" 
        text: "${system.entityToResolve.value.prompt}"
        actions:
        - label: "${enumValue}"
          type: "postback"
          iteratorVariable: "system.entityToResolve.value.enumValues"
Para ações globais, essa variável controla a ação global Mostrar Mais com as propriedades needShowMoreButton, rangeStartVar e nextRangeStart:
        globalActions: 
        - label: "Show More"
          type: "postback" 
          visible:
            expression: "${system.entityToResolve.value.needShowMoreButton}"
          payload:
            action: "system.showMore"
            variables: 
              ${system.entityToResolve.value.rangeStartVar}: ${system.entityToResolve.value.nextRangeStart} 
        - label: "Cancel"
          type: "postback" 
          visible:
            onInvalidUserInput: true
          payload:
            action: "cancel"
O label Mostrar Mais deve incluir um system.showMore (action: "system.showMore"). Caso contrário, ele não funcionará.

Validação da Mensagem do Usuário

Os componentes de Resposta Comum validam o valor de texto livre fornecido pelo usuário que é definido para a propriedade variable. Por exemplo, quando a propriedade variable é definida como tipo primitivo (string, booliano, flutuante, duplo), esses componentes tentam reconciliar o valor com um dos tipos primitivos. Quando a propriedade da variável é definida para uma variável de tipo de entidade, esses componentes chamam o Mecanismo NLP para resolver o valor como uma das entidades. Mas, quando esses componentes não puderem validar um valor, seu bot poderá exibir uma mensagem de erro. A referência da variável system.invalidUserInput permite que você adicione uma mensagem de erro condicional às respostas do bot. Essa variável é um booliano, de modo que você pode usá-la como condição com a diretiva if do FreeMarker para só exibir a mensagem quando um usuário informar um valor inválido. Caso contrário, a mensagem será ocultada. O estado AskPizzaSize do CrcPizzaBot referenciado no trecho de código a seguir demonstra isso adicionando essa variável como condição em um modelo FreeMarker avaliado pela diretiva if. Como está definido como true, o bot adiciona uma mensagem de erro à mensagem padrão (Qual tamanho você deseja?) quando o usuário informa um valor inválido.
metadata:
  responseItems:
  - type: "text"
    text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
      \ </#if>What size do you want?"
    name: "What size"
    separateBubbles: true