Ações do cartão
Os cartões usados por bots e extensões de mensagem no Teams são compatíveis com os 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.
- Não há suporte para nomes de máquina com números na URL.
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 ação invoke é usada para invocar módulos de tarefa.
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 Action.Submit comportamento é definido pelo cliente do Teams. 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
- Adicionar
msteamsdados com uma ação do Bot Framework não funciona com um módulo de tarefa cartão adaptável. - Não há suporte para primárias ou destrutivas
ActionStyleno Microsoft 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.
Cartões Adaptáveis com a ação messageBack
Para incluir uma açãomessageBack com um Cartão Adaptável, inclua os seguintes detalhes no objeto msteams:
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 ação imBack com um Cartão Adaptável, inclua os seguintes detalhes no objetomsteams:
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 ação signin com um Cartão Adaptável, inclua os seguintes detalhes no objeto msteams:
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 ação invoke com um Cartão Adaptável, inclua os seguintes detalhes no objeto msteams:
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"
}
}
}
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"
"data": {
"msteams": {
"type": "task/fetch"
},
"Value1": "some value"
}
}
Exemplos de código
| S.No. | Cartão | Descrição | .NET | Node.js | Python | Java | Manifesto |
|---|---|---|---|---|---|---|---|
| 1 | Ações de cartão adaptáveis | 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.