Enviar anexos de mídia com o Bot Framework SDK

  • Artigo

APLICA-SE A: SDK v4

As mensagens trocadas entre o usuário e o bot podem conter anexos de mídia, como imagens, vídeo, áudio e arquivos. O SDK do Bot Framework suporta a tarefa de enviar mensagens avançadas para o usuário. Para determinar o tipo de mensagens avançadas que um canal (Facebook, Slack e assim por diante) suporta, consulte a documentação do canal para obter informações sobre limitações.

Nota

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o Java SDK está sendo desativado com suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes construídos com o Java SDK continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copilot certa.

Para obter mais informações, consulte O futuro da criação de bots.

Pré-requisitos

Enviar anexos

Para enviar o conteúdo do usuário, como uma imagem ou um vídeo, você pode adicionar um anexo ou uma lista de anexos a uma mensagem.

Consulte Projetar a experiência do usuário para obter exemplos de cartões disponíveis.

Consulte também Qual é o limite de tamanho de um arquivo transferido usando canais? nas Perguntas frequentes.

Todo o código-fonte mostrado nesta seção é baseado no exemplo Manipulando anexos .

A Attachments propriedade do Activity objeto contém uma matriz de objetos que representam os anexos de Attachment mídia e cartões avançados anexados à mensagem. Para adicionar um anexo de mídia a uma mensagem, crie um Attachment objeto para a reply atividade e defina as ContentTypepropriedades , ContentUrle Name .

Para criar a mensagem de resposta, defina o texto e, em seguida, configure os anexos. A atribuição dos anexos à resposta é a mesma para cada tipo de anexo, no entanto, os vários anexos são configurados e definidos de forma diferente, como visto nos trechos a seguir. O código abaixo está configurando a resposta para um anexo embutido:

Bots/AttachmentsBot.cs

{
    reply = MessageFactory.Text("This is an inline attachment.");

Em seguida, examinamos os tipos de anexos. O primeiro é um anexo embutido:

Bots/AttachmentsBot.cs

{
    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

Em seguida, um anexo carregado:

Bots/AttachmentsBot.cs

{
    if (string.IsNullOrWhiteSpace(serviceUrl))
    {
        throw new ArgumentNullException(nameof(serviceUrl));
    }

    if (string.IsNullOrWhiteSpace(conversationId))
    {
        throw new ArgumentNullException(nameof(conversationId));
    }

    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");

    var connector = turnContext.TurnState.Get<IConnectorClient>() as ConnectorClient;
    var attachments = new Attachments(connector);
    var response = await attachments.Client.Conversations.UploadAttachmentAsync(
        conversationId,
        new AttachmentData
        {
            Name = @"Resources\architecture-resize.png",
            OriginalBase64 = File.ReadAllBytes(imagePath),
            Type = "image/png",
        },
        cancellationToken);

    var attachmentUri = attachments.GetAttachmentUri(response.Id);

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = attachmentUri,
    };
}

Por último, um anexo Internet:

Bots/AttachmentsBot.cs

    {
        // ContentUrl must be HTTPS.
        return new Attachment
        {
            Name = @"Resources\architecture-resize.png",
            ContentType = "image/png",
            ContentUrl = "https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png",
        };
    }
}

Se um anexo for uma imagem, áudio ou vídeo, o serviço Connector comunicará os dados do anexo ao canal de uma forma que permita que o canal processe esse anexo dentro da conversa. Se o anexo for um arquivo, a URL do arquivo será processada como um hiperlink dentro da conversa.

Enviar um cartão de herói

Além de simples anexos de imagem ou vídeo, você pode anexar um cartão herói, que permite combinar imagens e botões em um objeto, e enviá-los para o usuário. Markdown é suportado para a maioria dos campos de texto, mas o suporte pode variar de acordo com o canal.

Para compor uma mensagem com um cartão herói e um botão, você pode anexar um HeroCard objeto a uma mensagem.

O código-fonte a seguir é do exemplo Manipulando anexos .

Bots/AttachmentsBot.cs


      private static async Task DisplayOptionsAsync(ITurnContext turnContext, CancellationToken cancellationToken)
      {
          // Create a HeroCard with options for the user to interact with the bot.
          var card = new HeroCard
          {
              Text = "You can upload an image or select one of the following choices",
              Buttons = new List<CardAction>
              {
                  // Note that some channels require different values to be used in order to get buttons to display text.
                  // In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
                  // need to provide a value for other parameters like 'text' or 'displayText'.
                  new CardAction(ActionTypes.ImBack, title: "1. Inline Attachment", value: "1"),
                  new CardAction(ActionTypes.ImBack, title: "2. Internet Attachment", value: "2"),
                  new CardAction(ActionTypes.ImBack, title: "3. Uploaded Attachment", value: "3"),
              },
          };

          var reply = MessageFactory.Attachment(card.ToAttachment());
          await turnContext.SendActivityAsync(reply, cancellationToken);

Processar eventos em cartões avançados

Para processar eventos em cartões avançados, use objetos de ação do cartão para especificar o que deve acontecer quando o usuário seleciona um botão ou toca em uma seção do cartão. Cada ação de cartão tem uma propriedade type e value .

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.

Tipo Description valor
call Inicia uma chamada telefónica. Destino da chamada telefónica neste formato: tel:123123123123.
baixarArquivo Transfere um ficheiro. O URL do ficheiro a transferir.
imVoltar Envia uma mensagem para o bot e publica uma resposta visível no chat. Texto da mensagem a enviar.
messageVoltar Representa uma resposta de texto a ser enviada através do sistema de chat. Um valor programático opcional para incluir nas mensagens geradas.
openUrl Abre um URL no navegador integrado. O URL a abrir.
reproduzirÁudio Reproduz áudio. O URL do áudio a ser reproduzido.
reproduzirVídeo Reproduz um vídeo. O URL do vídeo a ser reproduzido.
postVoltar Envia uma mensagem para o bot e pode não publicar uma resposta visível no chat. Texto da mensagem a enviar.
showImage Exibe uma imagem. O URL da imagem a ser exibida.
iniciar sessão Inicia um processo de entrada OAuth. A URL do fluxo OAuth para iniciar.

Cartão de herói usando vários tipos de evento

O código a seguir mostra exemplos usando vários eventos de cartão avançado.

Para obter exemplos de todos os cartões disponíveis, consulte o Exemplo de uso de cartões .

Cards.cs

public static HeroCard GetHeroCard()
{
    var heroCard = new HeroCard
    {
        Title = "BotFramework Hero Card",
        Subtitle = "Microsoft Bot Framework",
        Text = "Build and connect intelligent bots to interact with your users naturally wherever they are," +
               " from text/sms to Skype, Slack, Office 365 mail and other popular services.",
        Images = new List<CardImage> { new CardImage("https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg") },
        Buttons = new List<CardAction> { new CardAction(ActionTypes.OpenUrl, "Get Started", value: "https://docs.microsoft.com/bot-framework") },
    };

    return heroCard;
}

Cards.cs

public static SigninCard GetSigninCard()
{
    var signinCard = new SigninCard
    {
        Text = "BotFramework Sign-in Card",
        Buttons = new List<CardAction> { new CardAction(ActionTypes.Signin, "Sign-in", value: "https://login.microsoftonline.com/") },
    };

    return signinCard;
}

Enviar um cartão adaptável

Embora você possa usar a fábrica de mensagens para criar uma mensagem que contenha um anexo (de qualquer tipo), um Cartão adaptável é um tipo específico de anexo. Nem todos os canais suportam Adaptive Cards, e alguns canais podem suportar apenas parcialmente Adaptive Cards. Por exemplo, se você enviar um cartão adaptável no Facebook, os botões não funcionarão enquanto os textos e as imagens funcionarem bem. A fábrica de mensagens é uma classe auxiliar do SDK do Bot Framework usada para automatizar as etapas de criação para você.

Os Adaptive Cards são um formato aberto de troca de cartões que permite aos desenvolvedores trocar conteúdo da interface do usuário de forma comum e consistente. No entanto, nem todos os canais suportam Adaptive Cards.

O Adaptive Cards Designer oferece uma experiência de design rica e interativa para a criação de cartões adaptáveis.

Nota

Você deve testar esse recurso com os canais que seu bot usará para determinar se esses canais suportam cartões adaptáveis.

Para usar cartões adaptáveis, certifique-se de adicionar o AdaptiveCards pacote NuGet.

O código-fonte a seguir é do exemplo Usando cartões .

Cards.cs

Este exemplo lê o JSON do Adaptive Card de um arquivo e o adiciona como um anexo.

public static Attachment CreateAdaptiveCardAttachment()
{
    // combine path for cross platform support
    var paths = new[] { ".", "Resources", "adaptiveCard.json" };
    var adaptiveCardJson = File.ReadAllText(Path.Combine(paths));

    var adaptiveCardAttachment = new Attachment()
    {
        ContentType = "application/vnd.microsoft.card.adaptive",
        Content = JsonConvert.DeserializeObject(adaptiveCardJson),
    };

    return adaptiveCardAttachment;
}

As mensagens também podem incluir vários anexos em um layout de carrossel, que coloca os anexos lado a lado e permite que o usuário role para frente.

O código-fonte a seguir é do exemplo Usando cartões .

Diálogos/MainDialog.cs

Primeiro, crie a resposta e defina os anexos como uma lista.

// Cards are sent as Attachments in the Bot Framework.
// So we need to create a list of attachments for the reply activity.
var attachments = new List<Attachment>();

// Reply to the activity we received with an activity.
var reply = MessageFactory.Attachment(attachments);

Em seguida, adicione os anexos e defina o tipo de layout como carrossel. Aqui estamos a adicioná-los um de cada vez, mas sinta-se à vontade para manipular a lista para adicionar os cartões como preferir.

// Display a carousel of all the rich card types.
reply.AttachmentLayout = AttachmentLayoutTypes.Carousel;
reply.Attachments.Add(Cards.CreateAdaptiveCardAttachment());
reply.Attachments.Add(Cards.GetAnimationCard().ToAttachment());
reply.Attachments.Add(Cards.GetAudioCard().ToAttachment());
reply.Attachments.Add(Cards.GetHeroCard().ToAttachment());
reply.Attachments.Add(Cards.GetOAuthCard().ToAttachment());
reply.Attachments.Add(Cards.GetReceiptCard().ToAttachment());
reply.Attachments.Add(Cards.GetSigninCard().ToAttachment());
reply.Attachments.Add(Cards.GetThumbnailCard().ToAttachment());
reply.Attachments.Add(Cards.GetVideoCard().ToAttachment());

Uma vez que os anexos são adicionados, você pode enviar a resposta como qualquer outro.

// Send the card(s) to the user as an attachment to the activity
await stepContext.Context.SendActivityAsync(reply, cancellationToken);

Exemplo de código para processar a entrada do Adaptive Card

O exemplo a seguir mostra uma maneira de usar entradas de cartão adaptável em uma classe de diálogo de bot. Ele estende a amostra de cartões heróis validando a entrada recebida no campo de texto do cliente respondente. Primeiro, você precisa adicionar a entrada de texto e a funcionalidade de botão ao cartão adaptável existente, adicionando o seguinte código imediatamente antes do colchete final de adaptiveCard.json, localizado na pasta de recursos:

"actions": [
  {
    "type": "Action.ShowCard",
    "title": "Text",
    "card": {
      "type": "AdaptiveCard",
      "body": [
        {
          "type": "Input.Text",
          "id": "text",
          "isMultiline": true,
          "placeholder": "Enter your comment"
        }
      ],
      "actions": [
        {
          "type": "Action.Submit",
          "title": "OK"
        }
      ]
    }
  }
]

O ID do campo de entrada de texto é definido como "texto". Quando o usuário seleciona OK, a mensagem que o Adaptive Card gera terá uma propriedade value que tem uma propriedade nomeada text que contém as informações que o usuário inseriu no campo de entrada de texto do cartão.

Nosso validador usa Newtonsoft.json para primeiro converter isso em um JObjecte, em seguida, criar uma cadeia de caracteres de texto cortada para comparação. Então adicione:

using System;
using System.Linq;
using Newtonsoft.Json.Linq;

para MainDialog.cs e instalar o pacote NuGet estável mais recente do Newtonsoft.Json. No código do validador, adicionamos o fluxo lógico nos comentários do código. Este ChoiceValidator método é colocado no exemplo Usando cartões logo após o público de chaves fechadas para declaração de MainDialog:

private async Task ChoiceValidator(
    PromptValidatorContext promptContext,
    CancellationToken cancellationToken)
{
    // Retrieves Adaptive Card comment text as JObject.
    // looks for JObject field "text" and converts that input into a trimmed text string.
    var jobject = promptContext.Context.Activity.Value as JObject;
    var jtoken = jobject?["text"];
    var text = jtoken?.Value().Trim();

    // Logic: 1. if succeeded = true, just return promptContext
    //        2. if false, see if JObject contained Adaptive Card input.
    //               No = (bad input) return promptContext
    //               Yes = update Value field with JObject text string, return "true".
    if (!promptContext.Recognized.Succeeded && text != null)
    {
        var choice = promptContext.Options.Choices.FirstOrDefault(
        c => c.Value.Equals(text, StringComparison.InvariantCultureIgnoreCase));
        if (choice != null)
        {
            promptContext.Recognized.Value = new FoundChoice
            {
                Value = choice.Value,
            };
            return true;
        }
    }
    return promptContext.Recognized.Succeeded;
}

Agora acima na alteração da MainDialog declaração:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt)));

para:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt), ChoiceValidator));

Isso invocará seu validador para procurar a entrada do Adaptive Card cada vez que um novo prompt de escolha for criado.

Testar o bot Usando cartões

  1. Execute o exemplo Usando cartões localmente e abra o bot no Emulador do Bot Framework.
  2. Siga as instruções no bot para exibir um tipo de cartão, como um Adaptive Card.

Próximos passos

Adicionar botões para orientar a ação do usuário