Ações do cartão
Os cartões usados por bots e extensões de mensagem no Microsoft Teams dão suporte aos seguintes tipos de atividade CardAction :
Observação
As CardAction ações diferem de para cartões de potentialActions conector para Grupos do Microsoft 365 quando usadas 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. Essa 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
CardActionnã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 nenhum aviso em qual botão foi selecionado.
- As URLs não dão suporte a nomes de máquina que incluem números. Por exemplo, não há suporte para um nome de host como userhostname123 .
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 seu código não pode deixar uma mensagem de usuário visível no histórico simplesmente por não usar 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 é usada para invocar caixas de diálogo (conhecidas como módulos de tarefa 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"
}
Entrada 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 a url especificada.
- Action.Submit: envia o resultado da ação de envio para o bot.
- Action.ShowCard: invoca uma caixa de diálogo e renderiza o sub-cartão nessa caixa de diálogo. Você só precisa lidar com isso se
ShowCardActionModeestiver definido como pop-up. - Action.ToggleVisibility: mostra ou oculta um ou mais elementos no cartão.
- Action.Execute: reúne os campos de entrada, mescla com o campo de dados opcional e envia um evento para o cliente.
Action.Submit
Action.Submit o tipo é usado para coletar a entrada, combinar as data propriedades e enviar um evento para o bot. Quando um usuário seleciona a ação de envio, o Teams envia uma atividade de mensagem para o bot, que inclui a entrada do usuário em pares de valor-chave para todos os campos de entrada e dados ocultos definidos no conteúdo cartão.
No esquema Cartão Adaptável, a data propriedade para Action.Submit é um string ou um object. Uma ação de envio se comporta de forma diferente para cada propriedade de dados:
string: uma ação de envio de cadeia de caracteres envia automaticamente uma mensagem do usuário para o bot e fica visível no histórico de conversas.object: uma ação de envio de objeto envia automaticamente uma mensagem invisível do usuário para o bot que contém dados ocultos. Uma ação de envio 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 você 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 funcionará como uma ação de invocação regular do Bot Framework, em que; a ação de envio dispara uma chamada de invocação para o bot e o bot recebe a carga com todos os valores de entrada definidos nos campos de entrada.
Observação
- O bot não recebe entrada do usuário, a menos que o usuário envie suas ações no Cartão Adaptável por meio de um botão, como Salvar ou Enviar. Por exemplo, o bot não considera ações do usuário, como selecionar uma opção de várias opções ou preencher campos em um formulário, como entradas, a menos que o usuário as envie.
- Adicionar
msteamsdados com uma ação do Bot Framework não funciona com uma caixa de diálogo Cartão Adaptável. - Não há suporte para primárias ou destrutivas
ActionStyleno Teams. - Seu aplicativo tem cinco segundos para responder à mensagem de invocação.
Exemplo
Veja a seguir um exemplo de uma Action.Submit carga de cartão:
O conteúdo consiste em um campo "id": "text-1" de entrada de texto e carga 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
}
}
]
}
A seguir está um exemplo da atividade de entrada em um bot quando o usuário digita algo no campo de entrada e seleciona Enviar. O value atributo inclui a entrada do usuário na text-1 propriedade e um conteúdo 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": "Robin Liao",
"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 próxima seção fornece detalhes sobre como usar ações existentes do Bot Framework com Cartões Adaptáveis.
Comentários de preenchimento do formulário
Você pode criar comentários de conclusão de formulário usando um Cartão Adaptável. A mensagem de conclusão do formulário aparece em Cartões Adaptáveis ao enviar uma resposta ao bot. A mensagem pode ser de dois tipos, erro ou êxito:
Erro: quando uma resposta enviada ao bot não tiver êxito, algo deu errado, a mensagem Tente novamente será exibida. O erro ocorre devido a vários motivos, como:
Muitas solicitações
Várias operações simultâneas na mesma conversa
Problema de dependência de serviço
Tempo Limite do Gateway (Gateway Timeout)
Êxito: quando uma resposta enviada ao bot é bem-sucedida, sua resposta foi enviada para a mensagem do aplicativo será exibida.
Você pode selecionar Fechar ou alternar chat para descartar a mensagem.
Se você não quiser exibir a mensagem de sucesso, defina o atributo
hidecomotruenamsTeamsfeedbackpropriedade. A seguir está 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, confira documentação de cartões.
Cartões Adaptáveis com a ação messageBack
Para incluir uma messageBack ação com um Cartão Adaptá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 Adaptá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 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 Adaptáveis com ação de entrada
Para incluir uma signin ação com um Cartão Adaptá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 Adaptá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 ser exibido. |
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 Adaptável | Este exemplo mostra diferentes ações com suporte em Cartões Adaptáveis. | View | View | NA | NA | View |
| 2 | Usando cartões | Apresenta todos os tipos de cartão, incluindo miniatura, áudio, mídia etc. Compilações no usuário de boas-vindas + bot multi-prompt apresentando um cartão com botões na mensagem de boas-vindas que roteiam para a caixa de diálogo apropriada. | View | View | View | View | NA |
| 3 | Cartões adaptáveis | Demonstra como a caixa de diálogo de várias voltas pode usar um cartão para obter a entrada do usuário para nome e idade. | View | View | View | View | NA |
Observação
Não há suporte para elementos de mídia para Cartão Adaptável no Teams.
Próximas etapas
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de