Adicionando anexos de cartão rich a mensagens com a API do Bot Connector

Alguns canais permitem que seu bot envie cartões rich para os usuários. Um cartão rico é 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 rich 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 avançados

Um cartão avançado é formado por um título, descrição, link e imagens. Uma mensagem pode conter vários cartões avançados, exibidos em formato de carrossel ou de lista. Atualmente, o Bot Framework dá suporte a oito tipos de cartões avançados:

Tipo de cartão Descrição
AdaptiveCard Um cartão personalizável que pode conter qualquer combinação de texto, fala, imagens, botões e campos de entrada. Confira suporte por canal.
AnimationCard Um cartão que pode reproduzir GIFs animados ou vídeos curtos.
AudioCard Um cartão que pode reproduzir um arquivo de áudio.
HeroCard Um cartão que geralmente contém uma única imagem grande, um ou mais botões e um texto.
ThumbnailCard Um cartão que geralmente contém uma única imagem em miniatura, um ou mais botões e um texto.
ReceiptCard Um cartão que permite a um bot fornecer um recibo para o usuário. Normalmente, contém a lista de itens a serem incluídos no recibo, informações fiscais e de totais e outros textos.
SignInCard Um cartão que permite a um bot solicitar a entrada do usuário. Normalmente, contém um texto e um ou mais botões nos quais o usuário pode clicar para iniciar o processo de entrada.
VideoCard Um cartão que pode reproduzir vídeos.

Dica

Para tabelas que descrevem quais recursos são compatíveis com cada canal, consulte o artigo referência de canais.

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 objeto CardAction contém estas propriedades:

Propriedade Tipo Descrição
channelData string dados específicos do canal associados a esta ação
displayText string texto a ser exibido no feed do chat se o botão receber um clique
text string texto da ação
type string tipo de ação (um dos valores especificados na tabela a seguir)
título string título do botão
image string URL da imagem do botão
value string valor necessário para executar o tipo de ação especificado

Observação

Botões dentro de Cartões Adaptáveis não são criados usando objetos CardAction, mas usando o esquema definido pelos Cartões Adaptáveis. Consulte Adicionar um Cartão Adaptável a uma mensagem para obter um exemplo que mostra como adicionar botões a um Cartão Adaptável.

Para funcionar corretamente, atribua um tipo de ação a cada item clicável em um cartão Hero. Esta tabela lista e descreve os tipos de ação disponíveis e quais devem estar na propriedade de valor 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 da atividade para obter mais informações sobre o messageBack e outros tipos de ação do cartão.

Tipo Descrição Valor
chamada Inicia uma chamada telefônica. Destino de uma chamada telefônica nesse formato: tel:123123123123.
downloadFile Baixa um arquivo. A URL do arquivo para download.
imBack Envia uma mensagem para o bot e posta uma resposta visível no bate-papo. Texto da mensagem a ser enviada.
messageBack Representa uma resposta de texto a ser enviada por meio do sistema de bate-papo. Um valor opcional de programação para incluir em mensagens geradas.
openUrl Abre uma URL no navegador interno. A URL para abrir.
playAudio Reproduz áudio. A URL do áudio para reproduzir.
playVideo Reproduz um vídeo. A URL do vídeo para reproduzir.
postBack Envia uma mensagem para o bot e não pode postar uma resposta visível no bate-papo. Texto da mensagem a ser enviada.
showImage Exibe uma imagem. A URL da imagem para exibir.
signin Inicia um processo de entrada do OAuth. A URL do fluxo de OAuth para iniciar.

Adicionar um cartão Hero a uma mensagem

Para adicionar um anexo de cartão rico a uma mensagem:

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

Dica

As mensagens que contêm de cartão avançado normalmente não especificam text.

Alguns canais permitem que você adicione vários cartões avançados à matriz attachments dentro de uma mensagem. Esse recurso pode ser útil em situações nas quais você deseja apresentar várias opções ao usuário. Por exemplo, se o seu bot permitir que os usuários reservem quartos de hotel, ele poderia apresentar uma lista de cartões avançados com 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 um cartão ou clicando em um botão.

Dica

Para exibir vários cartões avançados em formato de lista, defina a propriedade attachmentLayout do objeto Atividade como "lista". Para exibir vários cartões avançados em formato de carrossel, defina a propriedade Activity do objeto attachmentLayout como "carrossel". Se o canal não der suporte para formato de carrossel, ele exibirá os cartões avançados no formato de lista, mesmo se a propriedade attachmentLayout especificar "carrossel".

O exemplo a seguir mostra uma mensagem completa que contém um único anexo de cartão Hero. Nessa solicitação de exemplo, https://smba.trafficmanager.net/apis representa o URI base; o URI base das solicitações emitidas pelo bot pode ser diferente. Para obter detalhes sobre como definir o URI base, confira Referência de API.

POST https://smba.trafficmanager.net/apis/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, o que fornece a você controle total sobre o conteúdo e o formato do cartão.

Aproveite as informações dentro do site Cartões Adaptáveis para compreender o esquema de Cartão Adaptável, explore os elementos do Cartão Adaptável e veja exemplos de JSON que podem ser usados para criar cartões de composição e complexidade variadas. Além disso, você pode usar o Visualizador Interativo para criar o conteúdo de Cartão Adaptável e visualizar a saída do cartão.

O exemplo a seguir mostra um único objeto anexo de Cartão Adaptável, que representa uma atribuição de trabalho. Para enviar isso a um usuário, você precisará 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. Também há botões que podem ser clicados para comentar a atribuição de trabalho ou exibi-la:

Lembrete de calendário do Cartão Adaptável

Recursos adicionais