> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Media and Attachments

> Understand normalized messaging media, transcripts, file access, and retention in Aion.

Messaging providers represent files and voice recordings differently. Aion normalizes each inbound item into
provider-neutral A2A parts while preserving the provider event for integrations that need native details.

Provider support varies. Check [Messaging feature support](/docs/distributions/messaging/feature-support) before
assuming that an integration supplies attachment metadata, accessible content, or voice transcription.

## Media model

Each retained media item has one URL-backed file part. Its Event metadata is a complete `MessageMediaPayload`, and its
`mediaId` associates that file with an optional transcript part in the same A2A message.

| Part                                 | Purpose                                                                            |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| URL-backed file part                 | Provides temporary access and carries the complete `MessageMediaPayload` metadata. |
| Transcript text part                 | Contains speech-to-text output without changing the provider-authored caption.     |
| `SourceSystemEventPayload` data part | Preserves the parsed provider event and its provider-specific metadata.            |

Adapters and agents must inspect all parts. They must not assume that the first text part is the complete request.
Provider-authored caption text appears before transcript text, and each transcript is linked to its source item by
`mediaId`.

For the complete schemas, see the
[Distribution/Messaging extension](/a2a/extensions/aion/distribution/messaging/1.0.0#messaging-media).

## File identity and immutable history

An accessible media file carries two Aion identifiers:

* `fileId` is the stable File Recording identifier.
* `fileVersionId` is the exact immutable File Recordable identifier represented by the part.

The file URL and its timestamps are historical task facts. Aion does not rewrite a saved task when a grant or object
expires, and a historical URL never drifts to a newer File version. An authorized client may receive a new grant for
the same `fileVersionId` only while those exact bytes are retained and access remains authorized.

File-part metadata includes `accessExpiresAt` for the exact URL and may include `retentionExpiresAt` for the bytes.
After the URL expires, the Files API returns an authorization or expiry response as appropriate. After the retained
bytes expire, the historical URL returns `410 Gone`. If its exact file version no longer exists, clients should treat
the content as expired. The task and its metadata remain unchanged until normal A2A task cleanup.

## Availability and transcription

`MessageMediaPayload.availability` records the file's dispatch-time access facts. The payload appears only on an
accessible file part, so its status is `available`. Availability does not imply that a later client can refresh an
expired grant; the `refreshable` field records that dispatch-time capability.

Automatic transcription has an independent terminal status:

| Status          | Meaning                                                                      |
| --------------- | ---------------------------------------------------------------------------- |
| `not-requested` | The provider item was not eligible for automatic transcription.              |
| `completed`     | A non-empty transcript text part is present for the same `mediaId`.          |
| `no-speech`     | No usable speech was detected.                                               |
| `unsupported`   | The detected format could not be sent directly to the recorded STT provider. |
| `failed`        | Transcription ended with a safe, provider-neutral failure code.              |

Only `completed` has a transcript text part. Other statuses must not fabricate transcript text. Provider pages state
whether `no-speech` suppresses agent dispatch or whether another terminal status still delivers the file.

## Access, safety, and retention

Aion file URLs route through the authenticated Files API rather than exposing provider credentials or object-store
addresses. Access checks use the File's organization and owner association. File egress is measured asynchronously so
authorized downloads can start streaming without waiting for usage publication.

Ingest applies bounded size, MIME/signature, executable-type, and attachment-disposition checks. These controls reduce
obvious type confusion; they are not an Aion-owned malware-scanning service. Agents and downstream applications remain
responsible for deciding whether and how to process untrusted content.

Retention is purpose-specific. Supported Telegram Bot media and Slack native-audio bytes are retained for one hour
after the file becomes ready. Profile images remain until replacement or explicit deletion. Other attachment
categories require an explicit retention policy before content storage is enabled.

When A2A task cleanup encounters retained media, it requests best-effort logical File deletion. Task cleanup continues
if deletion fails; deadline and later orphan reconciliation remain able to remove leftover bytes. File tombstones and
billing facts remain available for audit.

## Provider differences

| Provider     | Attachment metadata                      | Accessible content         | Automatic voice transcription           |
| ------------ | ---------------------------------------- | -------------------------- | --------------------------------------- |
| Email        | Available for bounded attachment fields  | Not supported              | Not supported                           |
| Slack        | Available through events and Slack tools | Native `slack_audio` clips | Native `slack_audio` clips              |
| Telegram Bot | Available for supported inbound media    | Supported                  | Supported for Telegram `voice` messages |

See the [Email](/docs/distributions/messaging/email), [Slack](/docs/distributions/messaging/slack), and
[Telegram Bot](/docs/distributions/messaging/telegram-bot) pages for provider-specific request behavior.