Adicionar anexos de cartão avançados a mensagens com a API do Bot Connector
Alguns canais permitem que seu bot envie cartões avançados aos 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 podem ser anexados a uma mensagem. Consulte 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 obter mais informações sobre quais recursos são compatíveis com cada canal, confira 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 | Type | 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 |
| tipo | string | tipo de ação (um dos valores especificados na tabela a seguir) |
| title | string | título do botão |
| imagem | 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 para cada item clicável em um cartão de destaque. Esta tabela lista e descreve os tipos de ação disponíveis e quais devem estar na propriedade de valor associada.
A ação do cartão messageBack tem um significado mais generalizado do que as outras ações do cartão. Confira a seção Ação de cartão do Esquema de atividade para obter mais informações sobre o messageBack e outros tipos de ação de cartão.
| Tipo | Descrição | Valor |
|---|---|---|
| call | 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 enviado por meio do sistema de chat. | Um valor programático opcional a ser incluído nas 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 avançado a uma mensagem:
- Crie um objeto que represente o tipo de cartão que você deseja adicionar à mensagem.
- Crie um objeto Attachment :
- Defina sua
contentTypepropriedade como o tipo de mídia do cartão. - Defina sua
contentpropriedade como o objeto que você criou para representar o cartão.
- Defina sua
- Adicione o
Attachmentobjeto àattachmentsmatriz da mensagem.
Dica
As mensagens que contêm anexos de cartão avançados 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 Activity 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 ao formato carrossel, ele exibirá os rich cards no formato de lista, mesmo que a attachmentLayout propriedade especifique "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/teams 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/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, 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 de anexo de Cartão Adaptável, representando uma atribuição de trabalho. Para enviar isso a um usuário, você precisaria 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 sobre a atribuição de trabalho ou visualizá-la:
