Message Attachments

Message attachments are handled by the message command group. Use this for files or inline images that are attached to a Teams chat or channel message. Use teams file only when you want to manage the channel file library directly.

Send inline images

Inline images are uploaded as Teams hosted content and are rendered in the message body.

teams message send --chat "$CHAT_ID" --image ./screenshot.png --output json

teams message send \
  --team "$TEAM_ID" \
  --channel "$CHANNEL_ID" \
  --body "Screenshot attached" \
  --image ./screenshot.png \
  --output json

--image is repeatable, and --body is optional when at least one image or file is supplied. Media messages are sent as HTML; a text body is escaped before the CLI adds the image or attachment markup.

Each inline image must be 3 MB or smaller. Because all hosted images share one Graph JSON request, their combined base64-encoded size must also remain at or below 4 MB. Use --attach for larger images.

Send file attachments

File attachments are uploaded first, then referenced from the Teams message. Chat attachments are stored in the sender's OneDrive Microsoft Teams Chat Files folder. Channel attachments are stored in the team's SharePoint-backed files area.

teams message send --chat "$CHAT_ID" --body "Report attached" --attach ./report.pdf --output json

teams message send \
  --team "$TEAM_ID" \
  --channel "$CHANNEL_ID" \
  --body "Logs attached" \
  --attach ./logs.zip \
  --output json

File attachments use Microsoft Graph's simple-upload path and are limited to 250 MB per file. Uploads use rename-on-conflict behavior, so an existing file with the same name is not overwritten.

Reply to channel messages with attachments

Channel replies support the same --image and --attach flags as top-level messages.

teams message reply \
  --team "$TEAM_ID" \
  --channel "$CHANNEL_ID" \
  --message "$MESSAGE_ID" \
  --body "Adding the trace" \
  --attach ./trace.txt \
  --image ./detail.png \
  --output json

List attachments

Use message get --with-attachments when you want a channel message payload and attachment metadata together.

teams message get --team "$TEAM_ID" --channel "$CHANNEL_ID" "$MESSAGE_ID" --with-attachments --output json

Use message attachments list when an automation only needs attachment metadata.

teams message attachments list --chat "$CHAT_ID" "$MESSAGE_ID" --output json

teams message attachments list \
  --team "$TEAM_ID" \
  --channel "$CHANNEL_ID" \
  --reply "$REPLY_ID" \
  "$MESSAGE_ID" \
  --output json

For a channel reply, the positional MESSAGE_ID is the parent thread message and --reply is the reply message ID.

The inventory can include hosted-content images, file references, code snippets, adaptive cards, and other attachment metadata. Every item has a stable index; check its downloadable field before downloading it.

Download attachments

Download all attachments into a directory:

teams message attachments download --chat "$CHAT_ID" "$MESSAGE_ID" --dir ./assets --output json

Download one attachment by index:

teams message attachments download --chat "$CHAT_ID" "$MESSAGE_ID" --index 0 --path ./image.png --output json

Write bytes to stdout when the surrounding script handles the destination:

teams message attachments download --chat "$CHAT_ID" "$MESSAGE_ID" --index 0 --path - > image.png

--path requires --index. When --path - is used, stdout contains only the raw file bytes: the command deliberately does not print a JSON success envelope. File downloads are staged to a .part file and renamed atomically. When the CLI chooses the filename (no --path), unsafe filename characters are removed and an existing destination is preserved by adding a numeric suffix.

Required scopes

Inline hosted-content images use the same message permissions as reading or sending the message. File attachments require additional file permissions:

Operation	Delegated scope
Read inline images	Same message-read scope
Download file attachments	Files.Read.All
Send chat file attachments	Files.ReadWrite
Send channel file attachments	Files.ReadWrite.All

Add scopes to the profile that needs the capability, then refresh the token:

[profiles.attachments]
tenant_id = "common"
scopes = "User.Read Chat.ReadWrite ChannelMessage.Send ChannelMessage.Read.All Files.Read.All Files.ReadWrite Files.ReadWrite.All offline_access"

teams auth refresh --profile attachments

If the tenant requires admin consent, generate a scoped consent URL first:

teams auth consent-url --profile attachments