Envío y recepción de archivos mediante el bot

Artículo
23/01/2025

Importante

Este artículo se basa en el SDK de Bot Framework v4.
Los bots no admiten el envío y la recepción de archivos en Government Community Cloud High (GCC High), el Departamento de Defensa (DoD) y Teams operados por entornos de 21Vianet.

Hay dos maneras de enviar y recibir archivos de un bot:

Usar las API de Microsoft Graph: Este método funciona para bots en todos los ámbitos de Microsoft Teams:
- personal
- channel
- groupchat
Usar las API de bot de Teams: solo admiten archivos en personal contexto.

En el vídeo siguiente se muestra cómo un bot simplifica el proceso de envío y recepción de archivos con facilidad y eficacia:

Uso de graph API

Publique mensajes con datos adjuntos de tarjeta que hagan referencia a archivos de SharePoint ya existentes, mediante Graph API para OneDrive y SharePoint. Para usar graph API, obtenga acceso a cualquiera de las siguientes opciones a través del flujo de autorización estándar de OAuth 2.0:

Carpeta de OneDrive de un usuario para archivos personal y groupchat.
Los archivos del canal de un equipo para channel archivos.

Las API de Graph funcionan en todos los ámbitos de Teams. Para obtener más información, vea enviar datos adjuntos de archivos de mensajes de chat.

Como alternativa, puede enviar y recibir archivos de un bot mediante las API de bot de Teams.

Uso de las API de bot de Teams

Las API de bot de Teams solo funcionan en el contexto de personal. No funcionan en el channel contexto o groupchat .

Con las API de Teams, el bot puede enviar y recibir archivos directamente con los usuarios en el contexto de personal, también conocido como chats personales. Implemente funcionalidades, como son informes de gastos, reconocimiento de imágenes, archivado de archivos y firmas electrónicas que implican la edición del contenido del archivo. Los archivos compartidos en Teams suelen aparecer como tarjetas y permiten una visualización enriquecida desde la aplicación.

En las secciones siguientes se describe cómo enviar contenido de archivo como interacción directa del usuario, como el envío de un mensaje. Esta API se proporciona como parte de la plataforma de bots de Teams.

Configuración del bot para admitir archivos

Para enviar y recibir archivos en el bot, establezca la propiedad supportsFiles del manifiesto en true. Esta propiedad se describe en la sección bots de la referencia del manifiesto.

La definición tiene este aspecto, "supportsFiles": true. Si el bot no habilita supportsFiles, las características enumeradas en esta sección no funcionarán.

Recibir archivos en un chat personal

Cuando un usuario envía un archivo al bot, el archivo se carga primero en el almacenamiento de OneDrive para la empresa del usuario. A continuación, el bot recibe una actividad de mensaje que notifica al usuario sobre la carga del usuario. La actividad contiene metadatos de archivo, como es su nombre y la dirección URL de contenido. El usuario puede leer directamente desde esta dirección URL para capturar su contenido binario.

Ejemplo de actividad de mensaje con datos adjuntos de archivo

El código siguiente muestra un ejemplo de actividad de mensaje con datos adjuntos de archivo:

JSON

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.file.download.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "downloadUrl" : "https://download.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C9D",
      "fileType": "txt",
      "etag": "123"
    }
  }]
}

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Propiedad	Objetivo
`downloadUrl`	Dirección URL de OneDrive para capturar el contenido del archivo. El usuario puede emitir un `HTTP GET` directamente desde esta dirección URL.
`uniqueId`	Identificador de archivo único. Este es el identificador de elemento de unidad de OneDrive, en caso de que el usuario envíe un archivo al bot.
`fileType`	Tipo de archivo, como .pdf o .docx.

Como procedimiento recomendado, confirme la carga del archivo mediante el envío de un mensaje al usuario.

Cargar archivos en un chat personal

Para cargar un archivo en un usuario:

Envíe un mensaje al usuario que solicita permiso para escribir el archivo. Este mensaje debe contener FileConsentCard datos adjuntos con el nombre del archivo que se va a cargar.
Si el usuario acepta la descarga del archivo, el bot recibe una actividad de invocación con una dirección URL de ubicación.
Para transferir el archivo, el bot realiza una HTTP POST directamente en la dirección URL de ubicación proporcionada.
Opcionalmente, quite la tarjeta de consentimiento original si no desea que el usuario acepte más cargas del mismo archivo.

Mensaje que solicita permiso para cargar

El siguiente mensaje de escritorio contiene un objeto de datos adjuntos simple que solicita permiso de usuario para cargar el archivo:

El siguiente mensaje móvil contiene un objeto de datos adjuntos que solicita permiso de usuario para cargar el archivo:

Tarjeta de consentimiento que solicita permiso de usuario para cargar el archivo en el móvil

JSON

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.consent",
    "name": "file_example.txt",
    "content": {
      "description": "<Purpose of the file, such as: this is your monthly expense report>",
      "sizeInBytes": 1029393,
      "acceptContext": {
      },
      "declineContext": {
      }
    }
  }]
}

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Propiedad	Objetivo
`description`	Describe el propósito del archivo o resume su contenido.
`sizeInBytes`	Proporciona al usuario una estimación del tamaño del archivo y la cantidad de espacio que ocupa en OneDrive.
`acceptContext`	Contexto adicional que se transmite silenciosamente al bot cuando el usuario acepta el archivo.
`declineContext`	Contexto adicional que se transmite silenciosamente al bot cuando el usuario rechaza el archivo.

Invocación de la actividad cuando el usuario acepta el archivo

Una actividad de invocación se envía al bot cuando un usuario acepta el archivo. Contiene la dirección URL del marcador de posición OneDrive para la Empresa que el bot puede emitir después un PUT para transferir el contenido del archivo. Para obtener información sobre cómo cargar en la dirección URL de OneDrive, vea cargar bytes en la sesión de carga.

En el código siguiente se muestra un ejemplo de una versión concisa de la actividad de invocación que recibe el bot:

JSON

{
  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "accept",
    "context": {
    },
    "uploadInfo": {
      "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
      "name": "file_example.txt",
      "uploadUrl": "https://upload.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
      "etag": "123"
    }
  }
}

Del mismo modo, si el usuario rechaza el archivo, el bot recibe el siguiente evento con el mismo nombre de actividad general:

JSON

{
  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "decline",
    "context": {
    }
  }
}

Notificar al usuario sobre un archivo cargado

Después de cargar un archivo en el OneDrive del usuario, envíe un mensaje de confirmación al usuario. El mensaje debe contener los siguientes datos adjuntos FileCard que el usuario puede seleccionar, ya sea para obtener una vista previa o para abrirlo en OneDrive, o descargarlo localmente:

JSON

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
    }
  }]
}

En la tabla siguiente se describen las propiedades de contenido de los datos adjuntos:

Propiedad	Objetivo
`uniqueId`	Id. de elemento de unidad de OneDrive o SharePoint.
`fileType`	Tipo de archivo, como .pdf o .docx.

Capturar imágenes alineadas del mensaje

Capture imágenes alineadas que forman parte del mensaje mediante el token de acceso del bot.

Imagen alineada

En el código siguiente se muestra un ejemplo de captura de imágenes alineadas del mensaje:

.NET
Python

private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var responseMessage = await client.GetAsync(attachment.ContentUrl);
    // Save the inline image to Files directory.
    var filePath = Path.Combine("Files", "ImageFromUser.png");
    using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None))
    {
        await responseMessage.Content.CopyToAsync(fileStream);
    }
    // Create reply with image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { 
        GetInlineAttachment() 
    };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

Python


async def process_inline_image(self, turn_context: TurnContext):
    file = turn_context.activity.attachments[0]
    file_download = FileDownloadInfo.deserialize(file.content)
    file_path = "files/" + file.name

    response = requests.get(file_download.download_url, allow_redirects=True)
    open(file_path, "wb").write(response.content)

    reply = self._create_reply(
        turn_context.activity, f"Complete downloading <b>{file.name}</b>", "xml"
    )
    await turn_context.send_activity(reply)

def _create_reply(self, activity, text=None, text_format=None):
    return Activity(
        type=ActivityTypes.message,
        timestamp=datetime.utcnow(),
        from_property=ChannelAccount(
            id=activity.recipient.id, name=activity.recipient.name
        ),
        recipient=ChannelAccount(
            id=activity.from_property.id, name=activity.from_property.name
        ),
        reply_to_id=activity.id,
        service_url=activity.service_url,
        channel_id=activity.channel_id,
        conversation=ConversationAccount(
            is_group=activity.conversation.is_group,
            id=activity.conversation.id,
            name=activity.conversation.name,
        ),
        text=text or "",
        text_format=text_format or None,
        locale=activity.locale,
    )

Ejemplo básico

En el código siguiente se muestra un ejemplo de cómo controlar las cargas de archivos y enviar solicitudes de consentimiento de archivos en el cuadro de diálogo del bot:

.NET
Python


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Attachments?[0].ContentType.Contains("image/*") == true)
    {
        // Inline image.
        await ProcessInlineImage(turnContext, cancellationToken);
    }
    else
    {
        string filename = "teams-logo.png";
        string filePath = Path.Combine("Files", filename);
        long fileSize = new FileInfo(filePath).Length;
        await SendFileCardAsync(turnContext, filename, fileSize, cancellationToken);
    }
}
private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var responseMessage = await client.GetAsync(attachment.ContentUrl);
    // Save the inline image to Files directory.
    var filePath = Path.Combine("Files", "ImageFromUser.png");
    using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None))
    {
        await responseMessage.Content.CopyToAsync(fileStream);
    }
    // Create reply with image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { GetInlineAttachment() };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}
private async Task SendFileCardAsync(ITurnContext turnContext, string filename, long filesize, CancellationToken cancellationToken)
{
    var consentContext = new Dictionary<string, string>
    {
        { 
            "filename", filename 
        },
    };
    var fileCard = new FileConsentCard
    {
        Description = "This is the file I want to send you",
        SizeInBytes = filesize,
        AcceptContext = consentContext,
        DeclineContext = consentContext,
    };
    var asAttachment = new Attachment
    {
        Content = fileCard,
        ContentType = FileConsentCard.ContentType,
        Name = filename,
    };
    var replyActivity = turnContext.Activity.CreateReply();
    replyActivity.Attachments = new List<Attachment>() { asAttachment };
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Python


async def on_message_activity(self, turn_context: TurnContext):
    message_with_file_download = (
        False
        if not turn_context.activity.attachments
        else turn_context.activity.attachments[0].content_type == ContentType.FILE_DOWNLOAD_INFO
    )

    if message_with_file_download:
        # Save an uploaded file locally
        file = turn_context.activity.attachments[0]
        file_download = FileDownloadInfo.deserialize(file.content)
        file_path = "files/" + file.name

        response = requests.get(file_download.download_url, allow_redirects=True)
        open(file_path, "wb").write(response.content)

        reply = self._create_reply(
            turn_context.activity, f"Complete downloading <b>{file.name}</b>", "xml"
        )
        await turn_context.send_activity(reply)
    else:
        # Attempt to upload a file to Teams. This will display a confirmation to
        # the user (Accept/Decline card). If they accept, on_teams_file_consent_accept
        # will be called, otherwise on_teams_file_consent_decline.
        filename = "teams-logo.png"
        file_path = "files/" + filename
        file_size = os.path.getsize(file_path)
        await self._send_file_card(turn_context, filename, file_size)

async def _send_file_card(self, turn_context: TurnContext, filename: str, file_size: int):
    """
    Send a FileConsentCard to get permission from the user to upload a file.
    """

    consent_context = {"filename": filename}

    file_card = FileConsentCard(
        description="This is the file I want to send you",
        size_in_bytes=file_size,
        accept_context=consent_context,
        decline_context=consent_context
    )

    as_attachment = Attachment(
        content=file_card.serialize(), content_type=ContentType.FILE_CONSENT_CARD, name=filename
    )

    reply_activity = self._create_reply(turn_context.activity)
    reply_activity.attachments = [as_attachment]
    await turn_context.send_activity(reply_activity)

def _create_reply(self, activity, text=None, text_format=None):
    return Activity(
        type=ActivityTypes.message,
        timestamp=datetime.utcnow(),
        from_property=ChannelAccount(
            id=activity.recipient.id, name=activity.recipient.name
        ),
        recipient=ChannelAccount(
            id=activity.from_property.id, name=activity.from_property.name
        ),
        reply_to_id=activity.id,
        service_url=activity.service_url,
        channel_id=activity.channel_id,
        conversation=ConversationAccount(
            is_group=activity.conversation.is_group,
            id=activity.conversation.id,
            name=activity.conversation.name,
        ),
        text=text or "",
        text_format=text_format or None,
        locale=activity.locale,
    )

Ejemplo de código

En el ejemplo de código siguiente se muestra cómo obtener el consentimiento del archivo y cargar archivos en Teams desde un bot:

Ejemplo de nombre	Descripción	.NET	Node.js	Python	Manifiesto
File upload	En este ejemplo se muestra cómo obtener el consentimiento de los archivos y cargar archivos en Teams mediante el bot. Además, cómo recibir un archivo enviado a un bot.	View	View	View	View

Guía paso a paso

Siga la guía paso a paso para cargar archivos en Teams mediante bot.

Paso siguiente

Optimizar un bot con la limitación de volumen en Teams

Vea también

Colaborar con nosotros en GitHub

El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.

Comentarios de Platform Docs

Platform Docs es un proyecto de código abierto. Seleccione un vínculo para proporcionar comentarios:

Abrir incidencia con la documentación Proporcionar comentarios sobre el producto

Recursos adicionales

Documentación

Envío y recepción de archivos desde un bot - Teams

Obtenga información sobre cómo enviar y recibir archivos desde el bot mediante las API de Graph para ámbitos personales, de canal y de chat de grupo. Use las API de bot de Teams mediante ejemplos de código basados en el SDK de Bot Framework v3.
Tutorial: Carga de archivos mediante bot - Teams

Obtenga información sobre cómo crear un bot de carga de archivos mediante la API de Microsoft Teams e interactuar con el bot para cargar archivos en Teams y recibir archivos como datos adjuntos.
Bot de chat de conversación de canal o grupo - Teams

Obtenga información sobre cómo crear nuevos subprocesos de conversación, menciones de usuario y etiqueta, y enviar mensajes durante la instalación. Explore el ejemplo de carga de archivos de Teams (.NET, JavaScript y Python).
Conversaciones con un bot - Teams

Más información sobre el envío y la recepción de mensajes mediante una aplicación de bot
Eventos de conversación - Teams

Obtenga información sobre la actualización de la conversación, la reacción de mensajes, los eventos de actualización de instalación de aplicaciones, el comportamiento de desinstalación y los eventos y el control de errores de los bots de Microsoft Teams.
Obtener todos los mensajes de conversación con RSC - Teams

Permitir que los bots reciban todos los mensajes de conversación sin @mentioned mediante permisos de RSC. Lea en webApplicationInfo o en la sección de autorización en el manifiesto.

Cursos

Módulo

Descargar y cargar archivos en una aplicación de JavaScript con Microsoft Graph - Training

Aprenda cómo obtener una lista de archivos de usuario, y descargarlos y cargarlos desde una aplicación de página única mediante Microsoft Graph.

Certificación

Microsoft 365 Certified: Teams Administrator Associate - Certifications

Demostrar aptitudes para planear, implementar, configurar y administrar Microsoft Teams para centrarse en la colaboración y la comunicación eficientes y eficaces en un entorno de Microsoft 365.

AI Skills Fest

Compartir a través de

Envío y recepción de archivos mediante el bot

Uso de graph API

Uso de las API de bot de Teams

Configuración del bot para admitir archivos

Recibir archivos en un chat personal

Ejemplo de actividad de mensaje con datos adjuntos de archivo

Cargar archivos en un chat personal

Mensaje que solicita permiso para cargar

Invocación de la actividad cuando el usuario acepta el archivo

Notificar al usuario sobre un archivo cargado

Capturar imágenes alineadas del mensaje

Ejemplo básico

Ejemplo de código

Guía paso a paso

Paso siguiente

Vea también

Recursos adicionales