Send and receive files

Use ListAsync() to access every supported file attached to the current message:

teamsApp.OnMessage(async (context, cancellationToken) =>
{
    IList<IncomingFile> files =
        await context.Files.ListAsync(cancellationToken);

    if (files.Count == 0)
    {
        await context.ReplyAsync(
            "Attach a file and I will read it.",
            cancellationToken);
        return;
    }

    string names = string.Join(", ", files.Select(file => file.Name));
    await context.ReplyAsync(
        $"You sent {files.Count} file(s): {names}",
        cancellationToken);
});

Key APIs and values:

• context.Files.ListAsync: Return file metadata without downloading file bytes.
• file.Name: Read the uploader-provided name for display only.

ListAsync() preserves attachment order. It returns an empty collection for activities without supported files and skips malformed file entries. Use FirstAsync() when your handler expects one file:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    await context.ReplyAsync(
        $"Reading {file.Name}...",
        cancellationToken);
}

Key APIs and values:

• FirstAsync: Return the first supported file or null.
• file.Name: Display the received file's uploader-provided name.

Use list() to access every supported file attached to the current message:

app.on('message', async ({ files, send }) => {
  const attached = await files.list();

  if (attached.length === 0) {
    await send('Attach a file and I will read it.');
    return;
  }

  const names = attached.map((file) => file.name).join(', ');
  await send(`You sent ${attached.length} file(s): ${names}`);
});

Key APIs and values:

• files.list: Return file metadata without downloading file bytes.
• file.name: Read the uploader-provided name for display only.

list() preserves attachment order. It returns an empty array for activities without supported files and skips malformed file entries. Use first() when your handler expects one file:

const file = await files.first();

if (file) {
  await send(`Reading ${file.name}...`);
}

Key APIs and values:

• first: Return the first supported file or undefined.
• file.name: Display the received file's uploader-provided name.

Use list() to access every supported file attached to the current message:

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
    attached = await ctx.files.list()

    if not attached:
        await ctx.reply("Attach a file and I will read it.")
        return

    names = ", ".join(file.name for file in attached)
    await ctx.reply(f"You sent {len(attached)} file(s): {names}")

Key APIs and values:

• ctx.files.list: Return file metadata without downloading file bytes.
• file.name: Read the uploader-provided name for display only.

list() preserves attachment order. It returns an empty list for activities without supported files and skips malformed file entries. Use first() when your handler expects one file:

file = await ctx.files.first()

if file:
    await ctx.reply(f"Reading {file.name}...")

Key APIs and values:

• first: Return the first supported file or None.
• file.name: Display the received file's uploader-provided name.

Use DownloadAsync() to download a file into a reusable in-memory copy:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    DownloadedFile downloaded =
        await file.DownloadAsync(cancellationToken);

    await context.ReplyAsync(
        $"Downloaded {downloaded.Filename} " +
        $"({downloaded.Bytes.Length} bytes, {downloaded.ContentType}).",
        cancellationToken);
}

Key APIs and values:

• DownloadAsync: Fetch and buffer one reusable copy of bytes.
• downloaded.Bytes: Access the downloaded file's complete binary content.
• downloaded.ContentType: Use the resolved MIME type for processing.
• downloaded.Filename: Use the resolved name for display purposes.

Other read options include:

• TextAsync(): Download and decode text as UTF-8 by default.
• StreamAsync(): Process large files without buffering them completely.
• SaveAsAsync(path): Stream bytes directly to a safe local path.

TextAsync() replaces invalid byte sequences with U+FFFD. Supply an Encoding for non-UTF-8 text and process binary files as bytes or streams.

An IncomingFile doesn't cache bytes. Every call to DownloadAsync(), TextAsync(), StreamAsync(), or SaveAsAsync() performs another network request. Download once and reuse DownloadedFile when you need the same content more than once:

DownloadedFile downloaded =
    await file.DownloadAsync(cancellationToken);

string text = downloaded.Text();
byte[] bytes = downloaded.Bytes;

await downloaded.SaveAsAsync(
    "./downloads/copy.bin",
    cancellationToken);

Key APIs and values:

• downloaded.Text(): Decode the buffered copy without another download.
• downloaded.Bytes: Reuse buffered bytes for binary processing.
• SaveAsAsync: Save buffered bytes without fetching the file again.

Use download() to download a file into a reusable in-memory copy:

const file = await files.first();

if (file) {
  const downloaded = await file.download();
  await send(
    `Downloaded ${downloaded.filename} ` +
    `(${downloaded.bytes.length} bytes, ${downloaded.contentType}).`
  );
}

Key APIs and values:

• download: Fetch and buffer one reusable copy of bytes.
• downloaded.bytes: Access the downloaded file's binary content.
• downloaded.contentType: Use the resolved MIME type for processing.
• downloaded.filename: Use the resolved name for display purposes.

Other read options include:

• text(): Download and decode text as UTF-8 by default.
• stream(): Process large files without buffering them completely.
• saveAs(path): Stream bytes directly to a safe local path.

An incoming file doesn't cache bytes. Download once and reuse the downloaded file when you need the same content more than once:

const downloaded = await file.download();
const text = downloaded.text();
const buffer = downloaded.arrayBuffer();

await downloaded.saveAs('./downloads/copy.bin');

Key APIs and values:

• downloaded.text(): Decode the buffered copy without another download.
• downloaded.arrayBuffer(): Reuse buffered bytes for binary processing.
• saveAs: Save buffered bytes without fetching the file again.

Use download() to download a file into a reusable in-memory copy:

file = await ctx.files.first()

if file:
    downloaded = await file.download()
    await ctx.reply(
        f"Downloaded {downloaded.filename} "
        f"({len(downloaded.bytes)} bytes, {downloaded.content_type})."
    )

Key APIs and values:

• download: Fetch and buffer one reusable copy of bytes.
• downloaded.bytes: Access the downloaded file's binary content.
• downloaded.content_type: Use the resolved MIME type for processing.
• downloaded.filename: Use the resolved name for display purposes.

Other read options include:

• text(): Download and decode text as UTF-8 by default.
• stream(): Process large files without buffering them completely.
• save_as(path): Stream bytes directly to a safe local path.

An incoming file doesn't cache bytes. Download once and reuse the downloaded file when you need the same content more than once:

downloaded = await file.download()
text = downloaded.text()
data = downloaded.bytes

await downloaded.save_as("./downloads/copy.bin")

Key APIs and values:

• downloaded.text(): Decode the buffered copy without another download.
• downloaded.bytes: Reuse buffered bytes for binary processing.
• save_as: Save buffered bytes without fetching the file again.

Use IncomingFile.Raw only when you need the original protocol payload. The following example logs the attachment name and content type instead of serializing the complete object:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    logger.LogDebug(
        "File attachment received. Name: {Name}; Content type: {ContentType}",
        file.Raw.Name,
        file.Raw.ContentType);
}

Key APIs and values:

• file.Raw: Access original metadata for diagnostics or troubleshooting.
• file.Raw.Name: Log the display name only after validating its sensitivity.
• file.Raw.ContentType: Log the attachment type without exposing its URLs.
• logger.LogDebug: Record selected metadata instead of the complete payload.

Use IIncomingFile.raw only when you need the original protocol payload. The following example logs the attachment name and content type instead of the complete object:

const file = await files.first();

if (file) {
  log.debug('File attachment received', {
    name: file.raw.name,
    contentType: file.raw.contentType
  });
}

Key APIs and values:

• file.raw: Access original metadata for diagnostics or troubleshooting.
• file.raw.name: Log the display name only after validating its sensitivity.
• file.raw.contentType: Log the attachment type without exposing its URLs.
• log.debug: Record selected metadata instead of the complete payload.

Use IncomingFile.raw only when you need the original protocol payload. The following example logs the attachment name and content type instead of the complete object:

file = await ctx.files.first()

if file:
    ctx.logger.debug(
        "File attachment received. Name: %s; Content type: %s",
        file.raw.name,
        file.raw.content_type,
    )

Key APIs and values:

• file.raw: Access original metadata for diagnostics or troubleshooting.
• file.raw.name: Log the display name only after validating its sensitivity.
• file.raw.content_type: Log the attachment type without exposing its URLs.
• ctx.logger.debug: Record selected metadata instead of the complete payload.

using System.Net;
using System.Net.Http.Headers;

async Task UploadToOneDrive(
    string url,
    byte[] content,
    CancellationToken cancellationToken)
{
    if (content.Length == 0)
    {
        throw new ArgumentException(
            "The file content must not be empty.",
            nameof(content));
    }

    using var request = new HttpRequestMessage(HttpMethod.Put, url);
    request.Content = new ByteArrayContent(content);
    request.Content.Headers.ContentType =
        new MediaTypeHeaderValue("application/octet-stream");
    request.Content.Headers.ContentLength = content.Length;
    request.Content.Headers.ContentRange =
        new ContentRangeHeaderValue(0, content.Length - 1, content.Length);

    using HttpResponseMessage response =
        await httpClient.SendAsync(request, cancellationToken);

    if (response.StatusCode is not HttpStatusCode.OK
        and not HttpStatusCode.Created)
    {
        throw new HttpRequestException(
            $"Upload failed with status {response.StatusCode}.");
    }
}

Key parameters and values:

• url: Use the UploadInfo.UploadUrl returned after acceptance.
• content: Provide the exact bytes associated with consent.
• content.Length: Reject an empty upload before creating its byte range.
• ContentType: Set application/octet-stream for binary transfer.
• ContentLength: Set the exact number of uploaded bytes.
• ContentRange: Describe the uploaded byte range and total.
• httpClient.SendAsync: Send the HTTP PUT request to OneDrive.
• response.StatusCode: Accept HTTP 200 or 201 and fail otherwise.

import axios from 'axios';

async function uploadToOneDrive(url: string, content: Buffer): Promise<void> {
  if (content.length === 0) {
    throw new Error('The file content must not be empty.');
  }

  const fileSize = content.length;
  const response = await axios.put(url, content, {
    headers: {
      'Content-Type': 'application/octet-stream',
      'Content-Length': fileSize.toString(),
      'Content-Range': `bytes 0-${fileSize - 1}/${fileSize}`
    }
  });

  if (![200, 201].includes(response.status)) {
    throw new Error(`Upload failed with status ${response.status}`);
  }
}

Key parameters and values:

• url: Use the uploadInfo.uploadUrl returned after acceptance.
• content: Provide the exact bytes associated with consent.
• content.length: Reject an empty upload before creating its byte range.
• Content-Type: Set application/octet-stream for binary file transfer.
• Content-Length: Set the decimal length of uploaded bytes.
• Content-Range: Describe the uploaded byte range and total.
• axios.put: Upload the bytes with an HTTP PUT request.
• response.status: Accept HTTP 200 or 201 and fail on other responses.

import httpx

async def upload_to_onedrive(url: str, content: bytes) -> None:
    if not content:
        raise ValueError("The file content must not be empty.")

    file_size = len(content)
    headers = {
        "Content-Type": "application/octet-stream",
        "Content-Length": str(file_size),
        "Content-Range": f"bytes 0-{file_size - 1}/{file_size}",
    }

    async with httpx.AsyncClient() as client:
        response = await client.put(url, content=content, headers=headers)

    if response.status_code not in (200, 201):
        raise RuntimeError(
            f"Upload failed with status {response.status_code}"
        )

Key parameters and values:

• url: Use the upload_info.upload_url returned after acceptance.
• content: Provide the exact bytes associated with consent.
• if not content: Reject an empty upload before creating its byte range.
• Content-Type: Set application/octet-stream for binary transfer.
• Content-Length: Set the exact number of uploaded bytes.
• Content-Range: Describe the uploaded byte range and total.
• httpx.AsyncClient.put: Upload the bytes with an HTTP PUT request.
• response.status_code: Accept HTTP 200 or 201 and fail otherwise.

A 403 can represent missing consent, missing item access, or a nonexistent item. The SDK doesn't expose a separate file-not-found error for these responses.

try
{
    DownloadedFile downloaded =
        await file.DownloadAsync(cancellationToken);
}
catch (FileCredentialException)
{
    await context.ReplyAsync(
        "The agent isn't configured to access this file.",
        cancellationToken);
}
catch (FileAccessException error)
{
    await context.ReplyAsync(
        $"The storage service denied access ({error.Status}).",
        cancellationToken);
}
catch (FileUrlExpiredException)
{
    await context.ReplyAsync(
        "That file link expired. Attach the file again.",
        cancellationToken);
}
catch (FileScopeNotSupportedException)
{
    await context.ReplyAsync(
        "File download isn't supported in this conversation.",
        cancellationToken);
}
catch (FileException)
{
    await context.ReplyAsync(
        "The file couldn't be read.",
        cancellationToken);
}

Key types and values:

• FileCredentialException: Handle missing agentic-user Graph credential configuration.
• FileAccessException.Status: Distinguish rejected tokens from denied access.
• FileUrlExpiredException: Handle expired bot download URLs.
• FileScopeNotSupportedException: Handle unsupported group or channel retrieval.
• FileException: Provide fallback handling for known SDK failures.

try {
  const downloaded = await file.download();
} catch (error) {
  if (error instanceof FileCredentialError) {
    await send("The agent isn't configured to access this file.");
  } else if (error instanceof FileAccessError) {
    await send(`The storage service denied access (${error.status}).`);
  } else if (error instanceof FileUrlExpiredError) {
    await send('That file link expired. Attach the file again.');
  } else if (error instanceof FileScopeNotSupportedError) {
    await send("File download isn't supported in this conversation.");
  } else if (error instanceof FileError) {
    await send("The file couldn't be read.");
  } else {
    throw error;
  }
}

Key types and values:

• FileCredentialError: Handle missing agentic-user Graph credentials.
• FileAccessError.status: Distinguish rejected tokens from denied access.
• FileUrlExpiredError: Handle expired bot download URLs.
• FileScopeNotSupportedError: Handle unsupported conversation scopes.
• FileError: Provide fallback handling for known SDK failures.

try:
    downloaded = await file.download()
except FileCredentialError:
    await ctx.reply("The agent isn't configured to access this file.")
except FileAccessError as error:
    await ctx.reply(
        f"The storage service denied access ({error.status})."
    )
except FileUrlExpiredError:
    await ctx.reply("That file link expired. Attach the file again.")
except FileScopeNotSupportedError:
    await ctx.reply(
        "File download isn't supported in this conversation."
    )
except FileError:
    await ctx.reply("The file couldn't be read.")

Key types and values:

• FileCredentialError: Handle missing agentic-user Graph credentials.
• FileAccessError.status: Distinguish rejected tokens from denied access.
• FileUrlExpiredError: Handle expired bot download URLs.
• FileScopeNotSupportedError: Handle unsupported conversation scopes.
• FileError: Provide fallback handling for known SDK failures.