Partilhar via


Ações do cartão

Os cartões utilizados por bots e extensões de mensagens no Microsoft Teams suportam os seguintes tipos de atividade CardAction :

Observação

As CardAction ações diferem das dos cartões de potentialActions conector dos Grupos do Microsoft 365 quando utilizadas a partir de conectores.

Digitar Ação
openUrl Abre uma URL no navegador padrão.
messageBack Envia uma mensagem e conteúdo para o bot do usuário que selecionou o botão ou tocou no cartão. Envia uma mensagem separada para o fluxo de chat.
imBack Envia uma mensagem para o bot do usuário que selecionou o botão ou tocou no cartão. Essa mensagem do usuário para o bot é visível para todos os participantes da conversa.
invoke Envia uma mensagem e conteúdo para o bot do usuário que selecionou o botão ou tocou no cartão. Esta mensagem não está visível.
signin Inicia o fluxo OAuth, permitindo que os bots se conectem com serviços seguros.

Observação

  • O Teams não dá suporte aos tipos CardAction não listados na tabela anterior.
  • O Teams não dá suporte à propriedade potentialActions.
  • As ações de cartão são diferentes das ações sugeridas no Bot Framework ou Serviço de Bot do Azure.
  • Se você estiver usando uma ação de cartão como parte de uma extensão de mensagem, as ações não funcionarão até que o cartão seja enviado ao canal. As ações não funcionam enquanto o cartão está na caixa de mensagem de redação.

Tipo de ação openUrl

O tipo de ação openUrl especifica uma URL a ser iniciada no navegador padrão.

Observação

  • O bot não recebe qualquer aviso sobre o botão selecionado.
  • Os URLs não suportam nomes de máquinas que incluam números. Por exemplo, um nome de anfitrião, como userhostname123 , não é suportado.

Com openUrl, você pode criar uma ação com as seguintes propriedades:

Propriedade Descrição
title Aparece como o rótulo do botão.
value Esse campo deve conter uma URL completa e corretamente formada.

O código a seguir mostra um exemplo do tipo de ação openUrl em JSON:

{
    "type": "openUrl",
    "title": "Tabs in Teams",
    "value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}

Tipo de ação messageBack

Com messageBack, você pode criar uma ação totalmente personalizada com as seguintes propriedades:

Propriedade Descrição
title Aparece como o rótulo do botão.
displayText Opcional. Usado pelo usuário no fluxo de chat quando a ação é executada. Este texto não é enviado para o bot.
value Enviado ao bot quando a ação é executada. Você pode codificar o contexto para a ação, como identificadores exclusivos ou um objeto JSON.
text Enviado ao bot quando a ação é executada. Use essa propriedade para simplificar o desenvolvimento de bots. Seu código pode verificar uma única propriedade de nível superior para expedir a lógica do bot.

A flexibilidade de messageBack significa que o seu código não pode deixar uma mensagem de utilizador visível no histórico simplesmente por não utilizar displayText.

O código a seguir mostra um exemplo do tipo de ação messageBack em JSON:

{
  "buttons": [
    {
    "type": "messageBack",
    "title": "My MessageBack button",
    "displayText": "I clicked this button",
    "text": "User just clicked the MessageBack button",
    "value": "{\"property\": \"propertyValue\" }"
    }
  ]
}

A propriedade value pode ser uma cadeia de caracteres JSON serializada ou um objeto JSON.

Exemplo de mensagem de entrada

replyToId contém a ID da mensagem de origem da ação do cartão. Use-o se quiser atualizar a mensagem.

O código a seguir mostra um exemplo de mensagem de entrada:

{
   "text":"User just clicked the MessageBack button",
   "value":{
      "property":"propertyValue"
   },
   "type":"message",
   "timestamp":"2017-06-22T22:38:47.407Z",
   "id":"f:5261769396935243054",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
   "from":{
      "id":"29:102jd210jd010icsoaeclaejcoa9ue09u",
      "name":"John Smith"
   },
   "conversation":{
      "id":"19:malejcou081i20ojmlcau0@thread.skype;messageid=1498171086622"
   },
   "recipient":{
      "id":"28:76096e45-119f-4736-859c-6dfff54395f7",
      "name":"MyBot"
   },
   "entities":[
      {
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo" 
      }
   ],
   "channelData":{
      "channel":{
         "id":"19:malejcou081i20ojmlcau0@thread.skype"
      },
      "team":{
         "id":"19:12d021jdoijsaeoaue0u@thread.skype"
      },
      "tenant":{
         "id":"bec8e231-67ad-484e-87f4-3e5438390a77"
      }
   },
        "replyToId": "1575667808184",
}

Tipo de ação imBack

A ação imBack aciona uma mensagem de retorno para o bot, como se o usuário a tivesse digitado em uma mensagem de chat normal. O usuário e todos os outros usuários em um canal podem ver a resposta do botão.

Com imBack, você pode criar uma ação com as seguintes propriedades:

Propriedade Descrição
title Aparece como o rótulo do botão.
value Esse campo deve conter a cadeia de caracteres de texto usada no chat e, portanto, enviada de volta para o bot. Esse é o texto da mensagem que você processa no bot para executar a lógica desejada.

Observação

O campo value é uma cadeia de caracteres simples. Não há suporte para formatação ou caracteres ocultos.

O código a seguir mostra um exemplo do tipo de ação imBack em JSON:

{
    "type": "imBack",
    "title": "More",
    "value": "Show me more"
}

Invocação de tipo de ação

A invoke ação é utilizada para invocar caixas de diálogo (referidas como módulos de tarefas no TeamsJS v1.x).

A ação invoke contém três propriedades, type, titlee value.

Com invoke, você pode criar uma ação com as seguintes propriedades:

Propriedade Descrição
title Aparece como o rótulo do botão.
value Essa propriedade pode conter uma cadeia de caracteres, um objeto JSON com cadeia de caracteres ou um objeto JSON.

O código a seguir mostra um exemplo do tipo de ação invokeem JSON:

{
    "type": "invoke",
    "title": "Option 1",
    "value": {
        "option": "opt1"
    }
}

Quando um usuário seleciona o botão, o bot recebe o objeto value com algumas informações adicionais.

Observação

O tipo de atividade é invoke em vez de message que é activity.Type == "invoke".

Exemplo de mensagem de invocação de entrada

A propriedade de nível superior replyToId contém a ID da mensagem de origem da ação do cartão. Use-o se quiser atualizar a mensagem.

O código a seguir mostra um exemplo de mensagem de invocação de entrada:

{
    "type": "invoke",
    "value": {
        "option": "opt1"
    },
    "timestamp": "2017-02-10T04:11:19.614Z",
    "localTimestamp": "2017-02-09T21:11:19.614-07:00",
    "id": "f:6894910862892785420",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1Eniglq0-uVL83xNB9GU6w_G5a4SZF0gcJLprZzhtEbel21G_5h-
    NgoprRw45mP0AXUIZVeqrsIHSYV4ntgfVJQ",
        "name": "John Doe"
    },
    "conversation": {
        "id": "19:97b1ec61-45bf-453c-9059-6e8984e0cef4_8d88f59b-ae61-4300-bec0-caace7d28446@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:8d88f59b-ae61-4300-bec0-caace7d28446",
        "name": "MyBot"
    },
    "entities": [
        {
            "locale": "en-US",
            "country": "US",
            "platform": "Web",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "channel": {
            "id": "19:dc5ba12695be4eb7bf457cad6b4709eb@thread.skype"
        },
        "team": {
            "id": "19:712c61d0ef384e5fa681ba90ca943398@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}

Início de sessão do tipo de ação

O tipo de ação signin inicia um fluxo OAuth que permite que os bots se conectem com serviços seguros. Para obter mais informações, consulte fluxos de autenticação em bots.

O Teams também dá suporte a Ações de Cartões Adaptáveis que são usadas apenas por Cartões Adaptáveis.

O código a seguir mostra um exemplo do tipo de ação signin em JSON:

{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}

Ações de Cartões Adaptáveis

Os Cartões Adaptáveis dão suporte a quatro tipos de ação:

  • Action.OpenUrl: abra o URL especificado.
  • Action.Submit: envia o resultado da ação submeter para o bot.
  • Action.ShowCard: invoca uma caixa de diálogo e compõe o sub card nessa caixa de diálogo. Só tem de lidar com isto se ShowCardActionMode estiver definido como pop-up.
  • Action.ToggleVisibility: mostra ou oculta um ou mais elementos no cartão.
  • Action.Execute: recolhe os campos de entrada, intercala com o campo de dados opcional e envia um evento para o cliente.

Action.Submit

Action.Submit o tipo é utilizado para recolher a entrada, combinar as data propriedades e enviar um evento para o bot. Quando um utilizador seleciona a ação submeter, o Teams envia uma atividade de mensagem para o bot, que inclui a entrada do utilizador em pares chave-valor para todos os campos de entrada e dados ocultos definidos no payload do cartão.

No esquema cartão ajustável, a data propriedade de Action.Submit é a string ou uma object. Uma ação de submissão tem um comportamento diferente para cada propriedade de dados:

  • string: uma ação de submissão de cadeia envia automaticamente uma mensagem do utilizador para o bot e fica visível no histórico de conversações.
  • object: uma ação de submissão de objeto envia automaticamente uma mensagem invisível do utilizador para o bot que contém dados ocultos. Uma ação de submissão de objeto preenche a propriedade de valor da atividade enquanto a propriedade de texto está vazia.

Action.Submit é equivalente às ações do Bot Framework. Você também pode modificar a carga do Cartão Adaptável Action.Submit para dar suporte a ações de Bot Framework existentes usando uma propriedade msteams no objeto data de Action.Submit. Quando define a msteams propriedade em data, o cliente do Teams define o comportamento de Action.Submit. Se a msteams propriedade não estiver definida no esquema, Action.Submit funciona como uma ação de invocação normal do Bot Framework, em que. A ação de submissão aciona uma chamada de invocação para o bot e o bot recebe o payload com todos os valores de entrada definidos nos campos de entrada.

Observação

  • O bot não recebe a entrada do utilizador, a menos que o utilizador submeta as suas ações no Cartão Ajustável através de um botão, como Guardar ou Submeter. Por exemplo, o bot não considera as ações do utilizador, como selecionar uma opção a partir de múltiplas opções ou preencher campos num formulário, como entradas, a menos que o utilizador os submeta.
  • Adicionar msteams a dados com uma ação do Bot Framework não funciona com uma caixa de diálogo Cartão Ajustável.
  • O principal ou destrutivo ActionStyle não é suportado no Teams.
  • A sua aplicação tem cinco segundos para responder à mensagem de invocação.

Exemplo

Segue-se um exemplo de um Action.Submit payload de cartão:

O payload é composto por um campo "id": "text-1" de entrada de texto e payload de dados ocultos "hiddenKey": 123.45.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "fallbackText": "fallback text for sample 01",
  "speak": "This is adaptive card sample 1",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "id": "text-1",
          "type": "Input.Text"
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "data": {
        "hiddenKey": 123.45
      }
    }
  ]
}

Captura de ecrã a mostrar um exemplo de um Cartão Ajustável com o botão submeter.

Segue-se um exemplo da atividade de entrada para um bot quando o utilizador escreve algo no campo de entrada e seleciona Submeter. O value atributo inclui a entrada do utilizador na text-1 propriedade e um payload de dados ocultos na hiddenKey propriedade:


{
 "type": "message",
 "timestamp": "2023-07-18T23:45:41.699Z",
 "localTimestamp": "2023-07-18T16:45:41.699-07:00",
 "id": "f:9eb18f56-2259-8fa4-7dfc-111ffff58e67",
 "channelId": "msteams",
 "serviceUrl": "https://smba.trafficmanager.net/amer/",
 "from": {
   "id": "29:1E0NZYNZFQOCUI8zM9NY_EhlCsWgNbLGTHUNdBVX2ob8SLjhltEhQMPi07Gr6MLScFeS8SrKH1WGvJSiVKThnyw",
   "name": "Megan Bowen",
   "aadObjectId": "97b1ec61-45bf-453c-9059-6e8984e0cef4"
 },
 "conversation": {
   "conversationType": "personal",
   "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
   "id": "a:1H-RowZ3FrIheyjTupPnoCC6JvOLB5pCWms1xwqvAJG97j61D18EuSennYZE6tyfbQrnfIN3uIcwpOx73mg10hHp_uoTMMQlXhXosIu_q7QVCaYiW6Ch3bPWAitUw4aSX"
 },
 "recipient": {
   "id": "28:159e1c0f-15ef-4597-a8c6-44ba1fd89b78",
   "name": "Mushroom"
 },
 "entities": [
   {
     "locale": "en-US",
     "country": "US",
     "platform": "Web",
     "timezone": "America/Los_Angeles",
     "type": "clientInfo"
   }
 ],
 "channelData": {
   "tenant": {
     "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
   },
   "source": {
     "name": "message"
   },
   "legacy": {
     "replyToId": "1:1XFuAl7wF96vl6iAQk9tqus0uFrB89uujGpld-Qm-XEw"
   }
 },
 "replyToId": "1689723936016",
 "value": {
   "hiddenKey": 123.45,
   "text-1": "HELLO"
 },
 "locale": "en-US",
 "localTimezone": "America/Los_Angeles"
}

A secção seguinte fornece detalhes sobre como utilizar ações do Bot Framework existentes com Cartões Ajustáveis.

Comentários de preenchimento do formulário

Pode criar comentários sobre a conclusão do formulário com um Cartão Ajustável. A mensagem de conclusão do formulário é apresentada em Cartões Ajustáveis ao enviar uma resposta para o bot. A mensagem pode ser de dois tipos, erro ou êxito:

  • Erro: quando uma resposta enviada para o bot não é bem-sucedida, ocorreu um erro, é apresentada a mensagem Tentar novamente . O erro ocorre devido a vários motivos, tais como:

    • Demasiados pedidos

    • Várias operações simultâneas na mesma conversação

    • Problema de dependência do serviço

    • Tempo Limite do Gateway (Gateway Timeout)

      Captura de ecrã a mostrar uma mensagem de Erro num Cartão Ajustável.

  • Êxito: quando é apresentada uma resposta enviada para o bot com êxito, a resposta foi enviada para a mensagem da aplicação .

    Captura de ecrã a mostrar uma mensagem de êxito num Cartão Ajustável.

    Pode selecionar Fechar ou mudar de chat para dispensar a mensagem.

    Se não quiser apresentar a mensagem de êxito, defina o atributo hide como true na msTeamsfeedback propriedade . Segue-se um exemplo:

       "content": {
           "type": "AdaptiveCard",
           "title": "Card with hidden footer messages",
           "version": "1.0",
           "actions": [
           {
               "type": "Action.Submit",
               "title": "Submit",
               "msTeams": {
                   "feedback": {
                   "hide": true
                   }
               }
           }
           ]
       } 
    

Para obter mais informações sobre cartões e cartões em bots, veja a documentação dos cartões.

Cartões Adaptáveis com a ação messageBack

Para incluir uma messageBack ação com um Cartão Ajustável, inclua os seguintes detalhes no msteams objeto:

Observação

Você pode incluir propriedades ocultas adicionais no objeto data, se necessário.

Propriedade Descrição
type Definido como messageBack
displayText Opcional. Usado pelo usuário no fluxo de chat quando a ação é executada. Este texto não é enviado para o bot.
value Enviado ao bot quando a ação é executada. Você pode codificar o contexto para a ação, como identificadores exclusivos ou um objeto JSON.
text Enviado ao bot quando a ação é executada. Use essa propriedade para simplificar o desenvolvimento de bots. Seu código pode verificar uma única propriedade de nível superior para expedir a lógica do bot.

O código a seguir mostra um exemplo de Cartões Adaptáveis com a ação messageBack:

{
  "type": "Action.Submit",
  "title": "Click me for messageBack",
  "data": {
    "msteams": {
        "type": "messageBack",
        "displayText": "I clicked this button",
        "text": "text to bots",
        "value": "{\"bfKey\": \"bfVal\", \"conflictKey\": \"from value\"}"
    }
  }
}

Cartões Adaptáveis com a ação imBack

Para incluir uma imBack ação com um Cartão Ajustável, inclua os seguintes detalhes no msteams objeto:

Observação

O value campo é uma cadeia simples que não suporta formatação ou carateres ocultos.

Propriedade Descrição
type Definido como imBack
value Cadeia de caracteres que precisa ser ecoada novamente no chat.

O código a seguir mostra um exemplo de Cartões Adaptáveis com a ação imBack:

{
  "type": "Action.Submit",
  "title": "Click me for imBack",
  "data": {
    "msteams": {
        "type": "imBack",
        "value": "Text to reply in chat"
    }
  }
}

Cartões Ajustáveis com ação de início de sessão

Para incluir uma signin ação com um Cartão Ajustável, inclua os seguintes detalhes no msteams objeto:

Observação

Você pode incluir propriedades ocultas adicionais no objeto data, se necessário.

Propriedade Descrição
type Definido como signin.
value Defina como a URL para a qual você deseja redirecionar.

O código a seguir mostra um exemplo de Cartões Adaptáveis com ação signin:

{
  "type": "Action.Submit",
  "title": "Click me for signin",
  "data": {
    "msteams": {
        "type": "signin",
        "value": "https://signin.com"
    }
  }
}

Cartões Adaptáveis com a ação de invocação

Para incluir uma invoke ação com um Cartão Ajustável, inclua os seguintes detalhes no msteams objeto:

Observação

Você pode incluir propriedades ocultas adicionais no objeto data, se necessário.

Propriedade Descrição
type Definido como task/fetch.
data Defina o valor.

O código a seguir mostra um exemplo de Cartões Adaptáveis com a ação invoke:

{
  "type": "Action.Submit",
  "title": "submit",
  "data": {
    "msteams": {
        "type": "task/fetch"
    }
  }
}
Propriedade Descrição
type Definido como invoke.
value Defina o valor a apresentar.

O código a seguir mostra um exemplo de Cartões Adaptáveis com a ação invoke com dados de conteúdo adicionais:

[
  {
    "type": "Action.Submit",
    "title": "submit with object value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": { "a": "b" }
      }
    }
  },
  {
    "type": "Action.Submit",
    "title": "submit with stringified json value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": "{ \"a\": \"b\"}"
      }
    }
  }
]

Exemplos de código

S.No. Cartão Descrição .NET Node.js Python Java Manifesto
1 Ações de Cartão Ajustável Este exemplo apresenta diferentes ações suportadas em Cartões Ajustáveis. View Exibir NA NA View
2 Utilizar cartões Apresenta todos os tipos de cartões, incluindo miniatura, áudio, multimédia, etc. Baseia-se no bot utilizador acolhedor + multi-prompt ao apresentar um cartão com botões na mensagem de boas-vindas que encaminham para a caixa de diálogo adequada. View View View Exibir NA
3 Cartões ajustáveis Demonstra como a caixa de diálogo de várias curvas pode utilizar um cartão para obter a entrada do utilizador para o nome e a idade. View View View View NA

Próximas etapas

Confira também