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

# Media Access

> How to access media files from messages with presigned URLs and the Media API

When you receive messages containing media (images, videos, audio, documents), Chirp provides two ways to access the files:

1. **`mediaUrl`** - A presigned URL that expires after 1 hour
2. **`mediaId`** - A permanent identifier for fetching fresh URLs via the Media API

## Webhook Payload

Message webhooks include both fields for media content:

```json icon="code" title="Webhook Payload" theme={null}
{
  "event": "messages.whatsapp.received",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "message": {
      "id": "msg_abc123",
      "direction": "inbound",
      "from": "+15551234567",
      "to": "+15559876543",
      "type": "image",
      "text": null,
      "mediaUrl": "https://media.buildwithchirp.com/org_xxx/app_yyy/med_zzz.jpg?X-Amz-...",
      "mediaId": "med_zzz",
      "receivedAt": "2024-01-15T10:30:00.000Z"
    },
    "app": {
      "id": "app_yyy"
    }
  }
}
```

## Immediate vs. Long-term Access

### Use `mediaUrl` for Immediate Access

The `mediaUrl` is a presigned URL valid for **1 hour** from when the webhook is sent. Use it when you need to:

* Download the file immediately when receiving the webhook
* Display the media in real-time notifications
* Process the file right away (e.g., image analysis, transcription)

### Use `mediaId` for Long-term Access

The `mediaId` is a permanent identifier that you can use to fetch fresh presigned URLs at any time (until the media expires based on your organization's retention settings). Use it when you need to:

* Store a reference to retrieve the file later
* Build a media gallery or message history
* Access the file after the initial URL expires

## Fetching Media with the API

To get a fresh presigned URL for stored media, use the Media API:

```bash icon="terminal" title="Get Media by ID" theme={null}
curl -X GET "https://api.buildwithchirp.com/v1/media/{mediaId}" \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

The response includes a new presigned URL valid for 1 hour:

```json icon="code" title="Media Response" theme={null}
{
  "id": "med_zzz",
  "url": "https://media.buildwithchirp.com/org_xxx/app_yyy/med_zzz.jpg?X-Amz-...",
  "mimeType": "image/jpeg",
  "fileSize": 245678,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "expiresAt": "2024-04-15T10:30:00.000Z"
}
```

## Media Retention

Media files are stored according to your organization's `mediaRetentionDays` setting (default: 90 days). After this period:

* The media file is permanently deleted from storage
* Requests for the `mediaId` will return a `404 Not Found` response
* You should handle this case in your application

<Info>
  You can configure your media retention period in the [organization settings](https://dashboard.buildwithchirp.com/redirect/settings).
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Store the mediaId, not the mediaUrl">
    Since presigned URLs expire after 1 hour, always store the `mediaId` in your database. You can fetch a fresh URL whenever you need to display or download the file.
  </Accordion>

  <Accordion title="Download immediately if you need the original file">
    If you need to keep a permanent copy of the media file (e.g., for compliance, backup, or offline access), download it immediately when you receive the webhook using the `mediaUrl`.
  </Accordion>

  <Accordion title="Handle expired media gracefully">
    After your organization's retention period, media requests return `404 Not Found`. Your application should handle this case by showing a placeholder or message indicating the media is no longer available.
  </Accordion>

  <Accordion title="Use app keys for media access">
    Media is scoped to your application. Use your app API key (`sk_live_app_*` or `sk_test_app_*`) to access media - each app can only access its own media files.
  </Accordion>
</AccordionGroup>

## Supported Platforms

| Platform | Media Types                                | Notes                                            |
| -------- | ------------------------------------------ | ------------------------------------------------ |
| SMS/MMS  | Images, videos, audio                      | MMS media is downloaded and stored when received |
| WhatsApp | Images, videos, audio, documents, stickers | All media types except contacts and location     |

## Related

* [Webhooks](/concepts/webhooks) - Configure webhooks for your application
* [Media API](/api_reference/media) - Full API reference for media operations
* [Receiving SMS/MMS](/sms/receiving-messages) - Handle incoming SMS and MMS messages
* [Receiving WhatsApp](/whatsapp/receiving-messages) - Handle incoming WhatsApp messages