Partilhar via

Enviar anexos de mídia com o Bot Framework SDK

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

Para criar agentes com sua escolha de serviços, orquestração e conhecimento de IA, considere usar o SDK de agentes do Microsoft 365. O SDK de agentes tem suporte para C#, JavaScript ou Python. Você pode saber mais sobre o SDK de agentes em aka.ms/agents. Se você estiver procurando por uma plataforma de agente baseada em SaaS, considere o Microsoft Copilot Studio. Se você tiver um bot existente criado com o SDK do Bot Framework, poderá atualizar seu bot para o SDK de agentes. Você pode revisar as principais alterações e atualizações nas diretrizes de migração do SDK do Bot Framework para o SDK de agentes. Os tíquetes de suporte para o SDK do Bot Framework não serão mais atendidos a partir de 31 de dezembro de 2025.

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 propriedade do objeto Attachments contém uma matriz de objetos Activity que representam anexos multimédia e cartões ricos ligados à 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á a configurar a resposta a um anexo em linha.

Bots/AttachmentsBot.cs

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

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

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 de Manipulação de 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 interativos

Para processar eventos em cartões ricos, 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 tipo e valor.

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 secçã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 Descrição valor
chamar Inicia uma chamada telefónica. Destino da chamada telefónica neste formato: tel:123123123123.
descarregar ficheiro Transfere um ficheiro. O URL do ficheiro a transferir.
voltar Envia uma mensagem para o bot e publica uma resposta visível no chat. Texto da mensagem a enviar.
MensagemDeVolta 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 para reproduzir.
Reproduzir ví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.
mostrarImagem 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 seguinte código mostra exemplos usando vários eventos de cartões enriquecidos.

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 pacote NuGet AdaptiveCards.

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 de heróis validando a entrada recebida no campo de texto do cliente que responde. Primeiro, é necessário adicionar a funcionalidade de entrada de texto e 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;

ao 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 depois da chave fechada 'public' 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, na declaração MainDialog acima, altere:

// 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á o seu validador para procurar dados de entrada do Adaptive Card sempre que uma nova solicitação de escolha for criada.

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