Skip to content

Show images and videos in a carousel

When your agent returns two or more images or videos, show them as one card instead of several attachments. People swipe, tap the arrows or use the keyboard to step through the items one at a time, play videos, open an item full screen and download it. The tool is show_media_carousel, part of the Streams MCP server.

show_media_carousel posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card.

  • Display only. Nothing is answered and nothing comes back. The call returns at once, viewing the card never starts a turn, and the card does not count toward the forms and boards creation limit.
  • Uploaded files only. Upload each file first with create_upload and complete_upload, then pass the ids. Web addresses are not accepted. The files you pass become readable by the stream’s members, and appear in the stream’s Media tab.
  • All or nothing. If any item is invalid, nothing is posted and the error lists each problem by item position.
  • Safe to retry. requestId is a UUID you generate once per card. Calling again with the same requestId and the same content returns the card already posted (created: false). The same requestId with different content is refused with 409 chat.media_carousel_request_conflict, and so is a retry after the card’s message was deleted.
  • Rate limit. At most 5 new cards per minute per stream and agent: 429 chat.media_carousel_rate_limited with a Retry-After header. Retries of an existing card do not count.
  • Deleting the message removes the card, not the files.
Field Type Notes
requestId UUID Generate once per card; reuse it on a retry.
streamId UUID The stream to post in. Your agent must be a member.
threadSessionId UUID, optional Put the card in that thread, by its session id.
replyToMessageId UUID, optional Put the card in the thread of that message. With threadSessionId too, both must name the same thread.
heading string, optional Up to 200 characters. Names the whole card in the text caption.
items array 1 to 10 items, in the order to show.

Each item:

Field Type Notes
assetId UUID An uploaded file you can read, ready and not blocked by the scan.
title string, optional Up to 200 characters, shown under the media.
description string, optional Up to 2000 characters of plain text.
alt string, optional Up to 1000 characters for screen readers. Describe what the picture shows; falls back to the title, then the file name.
posterAssetId UUID, optional A JPEG, PNG, WebP or AVIF file shown before a video plays. Videos only.

The kind of each item (image, GIF, video) comes from the file’s content type, not from you. Supported: JPEG, PNG, GIF, WebP, AVIF, HEIC, HEIF, SVG, MP4, WebM and MOV. Images and GIFs can be up to 20 MB and videos up to 200 MB (the upload limits). A file may appear once per card.

{
"requestId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e",
"streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2f",
"heading": "Launch shoot",
"items": [
{
"assetId": "0197f2c5-0000-7000-8000-000000000001",
"title": "Hero banner",
"alt": "The product on a wooden table"
},
{
"assetId": "0197f2c5-0000-7000-8000-000000000002",
"title": "Onboarding walkthrough",
"posterAssetId": "0197f2c5-0000-7000-8000-000000000003"
}
]
}

{ interactionId, messageId, itemCount, created }. There is nothing to read back later.

400 chat.media_carousel_invalid_items carries details.issues, one entry per problem with the 1-based position, the role (primary or poster) and a reason:

Reason Meaning
not_found No such file, or you cannot read it (the two are not told apart).
not_ready The upload is not complete yet.
blocked The virus scan flagged the file.
unsupported_type Not an image, GIF or video the card can show.
poster_not_allowed A poster was given for something that is not a video.
poster_not_image The poster is not a JPEG, PNG, WebP or AVIF file.
duplicate The file is already in this card.

Fix the listed items and call again with a new requestId (nothing was posted, so the old one is also fine if the content is unchanged).