Adicionando anexos de cartão avançado a mensagens com a API do Bot Connector

Alguns canais permitem que seu bot envie cartões avançados para os usuários. Um cartão avançado é um anexo que contém elementos interativos, como botões, texto, imagens, áudio, vídeo e assim por diante.

Este artigo descreve como criar cartões avançados que você pode anexar a uma mensagem. Veja como adicionar anexos de mídia a mensagens para obter instruções específicas sobre como adicionar um anexo a uma mensagem.

Tipos de cartões ricos

Um cartão rico é composto por um título, descrição, link e imagens. Uma mensagem pode conter vários cartões ricos, exibidos em formato de lista ou carrossel. O Bot Framework atualmente suporta oito tipos de cartões ricos:

Processar eventos em cartões avançados

Para processar eventos em cartões avançados, use objetos CardAction para especificar o que deve acontecer quando o usuário clica em um botão ou toca em uma seção do cartão. Cada CardAction objeto contém estas propriedades:

Para funcionar corretamente, atribua um tipo de ação a cada item clicável em um cartão de herói. Esta tabela lista e descreve os tipos de ação disponíveis e o que deve estar na propriedade value associada.

A messageBack ação do cartão tem um significado mais generalizado do que as outras ações do cartão. Consulte a seção Ação do cartão do esquema de atividade para obter mais informações sobre o messageBack e outros tipos de ação do cartão.

Adicionar um cartão de herói a uma mensagem

Para adicionar um anexo de cartão avançado a uma mensagem:

1. Crie um objeto que represente o tipo de cartão que você deseja adicionar à mensagem.
2. Crie um objeto Attachment :
   • Defina sua contentType propriedade para o tipo de mídia do cartão.
   • Defina sua content propriedade para o objeto que você criou para representar o cartão.
3. Adicione o Attachment objeto à attachments matriz da mensagem.

Alguns canais permitem que você adicione vários cartões avançados à matriz dentro de attachments uma mensagem. Esse recurso pode ser útil em cenários em que você deseja fornecer ao usuário várias opções. Por exemplo, se o bot permitir que os usuários reservem quartos de hotel, ele poderá apresentar ao usuário uma lista de cartões avançados que mostre os tipos de quartos disponíveis. Cada cartão pode conter uma imagem e uma lista de comodidades correspondentes ao tipo de quarto e o usuário pode selecionar um tipo de quarto tocando em um cartão ou clicando em um botão.

O exemplo a seguir mostra uma mensagem completa que contém um único anexo de cartão Hero. Neste exemplo de solicitação, representa o URI base, https://smba.trafficmanager.net/teams o URI base para solicitações que seus problemas de bot podem ser diferentes. Para obter detalhes sobre como definir o URI base, consulte Referência da API.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.hero",
            "content": {
                "title": "title goes here",
                "subtitle": "subtitle goes here",
                "text": "descriptive text goes here",
                "images": [
                    {
                        "url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
                        "alt": "picture of a duck",
                        "tap": {
                            "type": "playAudio",
                            "value": "url to an audio track of a duck call goes here"
                        }
                    }
                ],
                "buttons": [
                    {
                        "type": "playAudio",
                        "title": "Duck Call",
                        "value": "url to an audio track of a duck call goes here"
                    },
                    {
                        "type": "openUrl",
                        "title": "Watch Video",
                        "image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
                        "value": "url goes here of the duck in flight"
                    }
                ]
            }
        }
    ],
    "replyToId": "5d5cdc723"
}

Adicionar um cartão adaptável a uma mensagem

O Cartão adaptável pode conter qualquer combinação de texto, fala, imagens, botões e campos de entrada. Os Cartões Adaptáveis são criados usando o formato JSON especificado em Cartões Adaptáveis, que lhe dá controle total sobre o conteúdo e o formato do cartão.

Aproveite as informações no site do Adaptive Cards para entender o esquema do Adaptive Card , explorar os elementos do Adaptive Card e ver exemplos JSON que podem ser usados para criar cartões de composição e complexidade variáveis. Além disso, você pode usar o Visualizador Interativo para projetar cargas úteis do Adaptive Card e visualizar a saída do cartão.

O exemplo a seguir mostra um único objeto de anexo Adaptive Card, representando uma atribuição de trabalho. Para enviar isso a um usuário, você precisa adicioná-lo como um anexo em uma mensagem.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Publish Adaptive Card schema",
          "weight": "bolder",
          "size": "medium"
        },
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
                  "size": "small",
                  "style": "person"
                }
              ]
            },
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Matt Hidinger",
                  "weight": "bolder",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "spacing": "none",
                  "text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
                  "isSubtle": true,
                  "wrap": true
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
          "wrap": true
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Board:",
              "value": "Adaptive Card"
            },
            {
              "title": "List:",
              "value": "Backlog"
            },
            {
              "title": "Assigned to:",
              "value": "Matt Hidinger"
            },
            {
              "title": "Due date:",
              "value": "Not set"
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.ShowCard",
      "title": "Comment",
      "card": {
        "type": "AdaptiveCard",
        "body": [
          {
            "type": "Input.Text",
            "id": "comment",
            "isMultiline": true,
            "placeholder": "Enter your comment"
          }
        ],
        "actions": [
          {
            "type": "Action.Submit",
            "title": "OK"
          }
        ]
      }
    },
    {
      "type": "Action.OpenUrl",
      "title": "View",
      "url": "https://adaptivecards.io"
    }
  ]
}

O cartão resultante contém um título, informações sobre quem criou o cartão (seu nome e avatar), quando o cartão foi criado, uma descrição das atribuições de trabalho e informações relacionadas à atribuição. Há também botões que podem ser clicados para comentar a atribuição de trabalho ou visualizá-la:

Recursos adicionais

• Criar mensagens
• Enviar e receber mensagens
• Adicionar anexos de mídia a mensagens
• Referência do canal
• Esquema de atividade do Bot Framework
• Esquema de Bot Framework Cards