# Files and multimodal input

> Pass managed Slack and Teams attachments to multimodal agents and post supported files back to the conversation.

Managed Channels can download provider attachments into
`message.contentParts`. The SDK carries text, images, audio, video, and PDF
documents in one provider-neutral prompt shape.

## Pass attachments to the agent [#pass-attachments-to-the-agent]

On managed Channels, the agent history already holds the current message. When
the message has files, the SDK adds them to that message as content parts. Call
`runAgent()` without a `prompt` to send both:

```ts title="channel.ts"
channel.onMessage(async ({ thread }) => {
  await thread.runAgent();
});
```

`message.contentParts` holds the same parts: the message text first, then one
part for each file. Read it when your handler must check the files before the
run.

## Understand the content mapping [#understand-the-content-mapping]

| Provider file     | `AgentContentPart`                                             |
| ----------------- | -------------------------------------------------------------- |
| Image MIME type   | `{ type: "image", source: { type: "data", value, mimeType } }` |
| Audio MIME type   | `{ type: "audio", source: ... }`                               |
| Video MIME type   | `{ type: "video", source: ... }`                               |
| PDF               | `{ type: "document", source: ... }`                            |
| `text/*`          | UTF-8 `{ type: "text", text }`                                 |
| Other binary type | A text note naming the attachment and MIME type                |

The binary `value` is base64. Whether the agent actually understands a media
part depends on its selected model and framework. Choose a multimodal model and
test the exact media types you accept.

File download is best-effort. A provider-ingest failure can omit the
attachment before the SDK receives a file handle. If Intelligence sends a file
handle but the SDK cannot download the file, the SDK adds a short failure note
(`[attached file <name> could not be retrieved]`) instead of failing the whole
turn.

<Callout type="info" title="Managed file-size ceiling">
  Intelligence currently accepts individual inbound and outbound Channel files
  up to 25 MiB. Provider limits can be lower.
</Callout>

## Teams file access [#teams-file-access]

Teams exposes files differently by surface:

- Personal 1:1 chat uploads can arrive as downloadable `file.download.info`
  attachments.
- Inline media such as images, audio, video, and PDFs with a Bot Connector
  `contentUrl` can download in chats or channels through the connector token.
  This path does not require Graph consent.
- In team channels, SharePoint-reference uploads and inline pasted images use
  Microsoft Graph. Intelligence reads the channel message, then downloads its
  reference files or hosted content.
- Other group-chat file-upload shapes remain unsupported. Test every
  attachment shape your workflow accepts.

The generated Teams package already declares the supported `personal` and
`team` bot scopes, sets `supportsFiles: true`, and requests
`ChannelMessage.Read.Group` resource-specific consent. Upload that generated
package as-is. Do not add `groupChat`; managed group chats are not supported.
A team owner grants the resource-specific permission during installation.

For Graph-backed team-channel messages:

- The app manifest's `ChannelMessage.Read.Group` resource-specific consent lets
  Intelligence read the channel message and inline hosted content. A team owner
  grants it during installation; it does not need tenant-admin Graph consent.
  Microsoft documents it as a
  [resource-specific consent permission](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent).
- `Files.Read.All` lets Intelligence read files uploaded to a Team channel.
  These files arrive as SharePoint references. It is an **application**
  permission and needs tenant-admin consent, so Teams setup offers it and skips
  it by default. A tenant that already consented to `Files.ReadWrite.All` needs
  no second grant.

This permission is optional and its absence does not hold the connection back
from reporting ready. Without it the text turn still runs and the message is
still delivered; only the referenced file is omitted or represented by a
failure note. Files shared in a 1:1 chat and images pasted into a
channel do not go through SharePoint and are unaffected.

Test each of these separately:

- Personal chat.
- Standard and private team channels.
- Inline media.
- Pasted images.
- SharePoint-reference uploads.

## Post a file [#post-a-file]

`thread.postFile()` takes bytes and returns a result instead of throwing for an
unsupported provider capability:

```ts title="export-report.ts"
const csv = new TextEncoder().encode(
  ["id,status", "INC-421,investigating"].join("\n"),
);

const result = await thread.postFile({
  bytes: csv,
  filename: "incident-report.csv",
  title: "Incident report",
  altText: "CSV export of the incident report",
});

if (!result.ok) {
  await thread.post(`The report could not be attached: ${result.error}`);
}
```

On managed Channels, `result.ok` means Intelligence stored the managed asset,
the provider acknowledged the file or image effect, and the SDK recorded the
asset in canonical Thread history.

Managed Teams supports general outbound files. In standard and private Team
channels, Intelligence uploads the original bytes to the channel's SharePoint
files area and sends a visible card or link. In personal chat, the same
`postFile()` call starts Microsoft's native consent-card flow when required;
acceptance completes the trusted upload and a decline remains a normal user
choice. Images may use the inline Bot Connector path. Always check `result.ok`
and send a text fallback when delivery is rejected.

## Treat attachments as untrusted input [#treat-attachments-as-untrusted-input]

- Validate declared MIME type and file signature before application-side
  processing.
- Put limits on decompression, parsing, page count, and extracted text.
- Do not execute macros or uploaded code.
- Resolve the provider user to an authenticated application identity before a
  file can trigger a consequential write.
- Avoid logging base64 content, signed download URLs, or document text.

See the [`IncomingMessage`
reference](/reference/channels/types/IncomingMessage) and
[`AgentContentPart` reference](/reference/channels/types/AgentContentPart) for
the exact public shapes.
