docs: receiving files as an agentic user, and sending inline images

[Corina (corinagum)]

Agentic Users can now receive and read files attached in chat. This documents that, plus a new guide for sending inline images.

Related PRs: microsoft/teams.ts#817, microsoft/teams.py#594 and microsoft/teams.net#669

Receiving files as an agentic user

While traditional bots receive a pre-auth URL, Agentic Users do not, and Graph is required to download the file. The SDK handles most of that route wiring invisibly to the developer.

Receiving Files now covers both routes. The call is identical either way. Docs now include more information on setup: an agentic user needs a Graph file permission consented on its blueprint by an administrator, and without it the read fails naming the identity that was refused rather than reporting the file as missing.

Error types

The new retrieval path brings a third error type. Handling errors is now a table of all three and what each carries.

Import and catch samples updated in all three languages.

Sending inline images

New page, filling a separate gap: images can already be sent via the SDK, but there was no guide. Covers hosted URL versus base64 data URI, the platform size and format limits, etc.

Smaller corrections

• webUrl -> contentUrl fix
• Saving to disk now notes that a file's name comes from whoever uploaded it and is not sanitized, so it should not be used directly as a destination.

---

Image size and format limits and the <img> sizing behavior come from Use picture messages. The restricted-cloud note comes from Send and receive files.

[Copilot]

🟡 Changes recommended

Several code samples do not compile, and the documented error handling has unresolved gaps.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This documentation PR adds Agentic User file-retrieval guidance and inline-image sending guidance across TypeScript, Python, and C#.

Changes:

• Adds hosted URL, base64, Adaptive Card, sizing, and platform-limit examples.
• Documents Graph permissions, retrieval routes, error handling, and unsafe uploaded filenames.
• Updates navigation and language-specific snippets.

File summaries

File	Reviewed changes and final comments
teams.md/src/pages/templates/in-depth-guides/file-handling/sending-inline-images.mdx	Adds the inline-image guide. [NIT, severity: nit, 1 vote] Correct the cross-reference to point to Receiving Inline Images.
teams.md/src/pages/templates/in-depth-guides/file-handling/receiving-files.mdx	Documents Agentic User retrieval and errors. Findings concern exact per-language error values, wording, blueprint consent setup, scope qualification, and exported error identifiers.
teams.md/src/pages/templates/in-depth-guides/file-handling/README.mdx	Updates file-handling navigation.
teams.md/src/components/include/in-depth-guides/file-handling/sending-inline-images/typescript.incl.md	Adds TypeScript examples.
teams.md/src/components/include/in-depth-guides/file-handling/sending-inline-images/python.incl.md	Adds Python examples. [HIGH, severity: critical, 3 votes] Add the missing ActivityContext and MessageActivity imports.
teams.md/src/components/include/in-depth-guides/file-handling/sending-inline-images/csharp.incl.md	Adds C# examples. Findings cover the missing schema namespace, undeclared attachments, incorrect ImageSize usage, and inaccurate AttachmentContentTypes wording.
teams.md/src/components/include/in-depth-guides/file-handling/receiving-files/typescript.incl.md	Updates TypeScript error handling.
teams.md/src/components/include/in-depth-guides/file-handling/receiving-files/python.incl.md	Updates Python error handling. [HIGH, severity: moderate, 1 vote] Handle or re-raise the reread expiry case instead of swallowing it.
teams.md/src/components/include/in-depth-guides/file-handling/receiving-files/csharp.incl.md	Updates C# error handling.

Review details

Suppressed comments (7)

teams.md/src/components/include/in-depth-guides/file-handling/receiving-files/python.incl.md:119

• [HIGH] FileUrlExpiredError is caught before the generic FileError clause; when reason is reread, the condition is false and the exception is silently swallowed, so this example does not handle all documented expiry cases. Add an else branch (or re-raise) for the reread case.

except FileError:
    # Any future inbound-file failure lands here rather than escaping unhandled.
    await ctx.reply("That file could not be read.")

teams.md/src/components/include/in-depth-guides/file-handling/sending-inline-images/csharp.incl.md:23

• [NIT] This is inaccurate: AttachmentContentTypes also exposes file and OAuth content-type constants, not only card types. Say it exposes built-in card/file types but no image type.

`AttachmentContentTypes` exposes constants for the card content types only, so an image type is constructed directly: `new AttachmentContentType("image/png")`.

teams.md/src/pages/templates/in-depth-guides/file-handling/receiving-files.mdx:32

• [HIGH] This is not a manifest setting: the required setup is administrator consent for a Graph file permission on the Agentic User's blueprint. The current heading sends readers to the wrong configuration surface.

## Enable file support in your manifest for Agentic Users

teams.md/src/pages/templates/in-depth-guides/file-handling/receiving-files.mdx:95

• [HIGH] This row is both ungrammatical (file needs was refused) and narrower than the public error: FileRetrievalError describes any Graph-based read failure, not only an agentic user's file. Describe the Graph read generically so the table matches the app actor documented below.

| **File retrieval failed** | The Graph read an agentic user's file needs was refused by the storage service, or ruled out before the request because no credential was available. | `reason`: **no Graph credential** or **access denied**<sup><a href="#access-denied">1</a></sup>. <br/> `actor`<sup><a href="#actor">2</a></sup>: the identity that was refused. <br /> `details`: what the service said, if anything. |

teams.md/src/pages/templates/in-depth-guides/file-handling/receiving-files.mdx:125

• [HIGH] This sentence makes agentic-user file handling sound unsupported in every scope, contradicting the personal-chat support described above and the Graph path below. Qualify the limitation to non-personal scopes (or explicitly say group chats/channels) so readers do not miss the newly documented personal-chat path.

In **channels**, the attached file isn't delivered to a traditional bot on the activity (the attachment is dropped), so <LanguageInclude content={{"typescript": "`list()`", "python": "`list()`", "csharp": "`ListAsync()`"}} /> doesn't surface it. Group-chat behavior varies by how the file is stored. Agentic Users will have attachments on the activity but is not explicitly supported by the API today. 

teams.md/src/pages/templates/in-depth-guides/file-handling/receiving-files.mdx:127

• [HIGH] file-scope-not-supported is not a public SDK error identifier; the exported types are FileScopeNotSupportedError for TypeScript/Python and FileScopeNotSupportedException for C#. Readers cannot map the name in this sentence to the catchable API.

When <LanguageInclude content={{"typescript": "`download()`, `stream()`, `text()`, or `saveAs()`", "python": "`download()`, `stream()`, `text()`, or `save_as()`", "csharp": "`DownloadAsync()`, `StreamAsync()`, `TextAsync()`, or `SaveAsAsync()`"}} /> is called on a surfaced file whose scope isn't personal (1:1), it raises the `file-scope-not-supported` error.

teams.md/src/pages/templates/in-depth-guides/file-handling/sending-inline-images.mdx:12

• [NIT] This calls sending inline images the counterpart to Receiving Files, but that page documents uploaded-file handles; the inbound counterpart for this page is Receiving Inline Images. Split the cross-reference so each link describes the correct inbound behavior.

Your agent can send an image that renders directly in the conversation, beside the message text, instead of arriving as a document the user has to open. Teams calls this an inline image. It is the outbound counterpart to [Receiving Files](./receiving-files): receiving gives you a lazy handle you pull bytes from, while sending means putting the image on the message before it goes out.

• Files reviewed: 9/9 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.