Send and receive files using bot

Article
02/25/2025

Important

This article is based on the v4 Bot Framework SDK.
Bots don't support sending and receiving files in Government Community Cloud High (GCC High), Department of Defense (DoD), and Teams operated by 21Vianet environments.

There are two ways to send files to and receive files from a bot:

Use the Microsoft Graph APIs: This method works for bots in all Microsoft Teams scopes:
- personal
- channel
- groupchat
Use the Teams bot APIs: These only support files in personal context.

The following video demonstrates how a bot simplifies the process of sending and receiving files with ease and efficiency:

Use the Graph APIs

Post messages with card attachments that refer to existing SharePoint files, using the Graph APIs for OneDrive and SharePoint. To use the Graph APIs, obtain access to either of the following through the standard OAuth 2.0 authorization flow:

A user's OneDrive folder for personal and groupchat files.
The files in a team's channel for channel files.

Graph APIs work in all Teams scopes. For more information, see send chat message file attachments.

Alternately, you can send files to and receive files from a bot using the Teams bot APIs.

Use the Teams bot APIs

Teams bot APIs work only in the personal context. They don't work in the channel or groupchat context.

Using Teams APIs, the bot can directly send and receive files with users in the personal context, also known as personal chats. Implement features, such as expense reporting, image recognition, file archival, and e-signatures involving the editing of file content. Files shared in Teams typically appear as cards and allow rich in-app viewing.

The next sections describe how to send file content as direct user interaction, like sending a message. This API is provided as part of the Teams bot platform.

Configure the bot to support files

To send and receive files in the bot, set the supportsFiles property in the manifest to true. This property is described in the bots section of the manifest reference.

The definition looks like this, "supportsFiles": true. If the bot does not enable supportsFiles, the features listed in this section do not work.

Receive files in personal chat

When a user sends a file to the bot, the file is first uploaded to the user's OneDrive for business storage. The bot then receives a message activity notifying the user about the user upload. The activity contains file metadata, such as its name and the content URL. The user can directly read from this URL to fetch its binary content.

Message activity with file attachment example

The following code shows an example of message activity with file attachment:

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"
    }
  }]
}

The following table describes the content properties of the attachment:

Property	Purpose
`downloadUrl`	OneDrive URL for fetching the content of the file. The user can issue an `HTTP GET` directly from this URL.
`uniqueId`	Unique file ID. This is the OneDrive drive item ID, in case the user sends a file to the bot.
`fileType`	Type of file, such as .pdf or .docx.

As a best practice, acknowledge the file upload by sending a message back to the user.

Upload files to personal chat

To upload a file to a user:

Send a message to the user requesting permission to write the file. This message must contain a FileConsentCard attachment with the name of the file to be uploaded.
If the user accepts the file download, the bot receives an invoke activity with a location URL.
To transfer the file, the bot performs an HTTP POST directly into the provided location URL.
Optionally, remove the original consent card if you do not want the user to accept further uploads of the same file.

Message requesting permission to upload

The following desktop message contains a simple attachment object requesting user permission to upload the file:

The following mobile message contains an attachment object requesting user permission to upload the file:

Consent card requesting user permission to upload file on mobile

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": {
      }
    }
  }]
}

The following table describes the content properties of the attachment:

Property	Purpose
`description`	Describes the purpose of the file or summarizes its content.
`sizeInBytes`	Provides the user an estimate of the file size and the amount of space it takes in OneDrive.
`acceptContext`	Additional context that is silently transmitted to the bot when the user accepts the file.
`declineContext`	Additional context that is silently transmitted to the bot when the user declines the file.

Invoke activity when the user accepts the file

An invoke activity is sent to the bot when a user accepts the file. It contains the OneDrive for Business placeholder URL that the bot can then issue a PUT to transfer the file contents. For information on uploading to the OneDrive URL, see upload bytes to the upload session.

The following code shows an example of a concise version of the invoke activity that the bot receives:

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"
    }
  }
}

Similarly, if the user declines the file, the bot receives the following event with the same overall activity name:

JSON

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

Notifying the user about an uploaded file

After uploading a file to the user's OneDrive, send a confirmation message to the user. The message must contain the following FileCard attachment that the user can select, either to preview or open it in OneDrive, or download locally:

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",
    }
  }]
}

The following table describes the content properties of the attachment:

Property	Purpose
`uniqueId`	OneDrive or SharePoint drive item ID.
`fileType`	Type of file, such as .pdf or .docx.

Fetch inline images from message

Fetch inline images that are part of the message using the Bot's access token.

Inline image

The following code shows an example of fetching inline images from message:

.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,
    )

Basic example

The following code shows an example of how to handle file uploads and send file consent requests in the bot's dialog:

.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,
    )

Code sample

The following code sample demonstrates how to obtain file consent and upload files to Teams from a bot:

Sample name	Description	.NET	Node.js	Python	Manifest
File upload	This sample shows how to obtain file consent and upload files to Teams using bot. Also, how to receive a file sent to a bot.	View	View	View	View

Step-by-step guide

Follow the step-by-step guide to upload file in Teams using bot.

Next step

Optimize your bot with rate limiting in Teams

Additional resources

Documentation

Send and receive files from a bot - Teams

Learn send and receive files from bot using Graph APIs for personal, channel, groupchat scopes. Use Teams bot APIs using code samples based on v3 Bot Framework SDK.
Tutorial - Upload Files Using Bot - Teams

Learn how to create a file upload bot using Microsoft Teams API and interact with the bot to upload files to Teams and receive file as attachment.
Send and receive messages with a bot - Teams

In this module, learn to have a conversation with a Microsoft Teams bot, Proactive messages, Conversation basics, Message content and formatting
Conversations with a Bot - Teams

Learn about sending and receiving messages using a bot app
Send proactive messages - Teams

Learn how to send proactive messages with your Teams bot, install your app using Microsoft Graph, and check code samples based on Bot Framework SDK v4.
Handle bot events - Teams

In this module, learn how to handle events in bots for Microsoft Teams, Teams member or bot addition, Team member or bot removed and more.

Training

Module

Download and upload files in a JavaScript app with Microsoft Graph - Training

Learn how to list, download, and upload a user's files from a single-page application by using Microsoft Graph.

AI Skills Fest

Share via

Send and receive files using bot

Use the Graph APIs

Use the Teams bot APIs

Configure the bot to support files

Receive files in personal chat

Message activity with file attachment example

Upload files to personal chat

Message requesting permission to upload

Invoke activity when the user accepts the file

Notifying the user about an uploaded file

Fetch inline images from message

Basic example

Code sample

Step-by-step guide

Next step

See also

Additional resources