Skip to main content
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:
Webhook Payload
{
  "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:
Get Media by ID
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:
Media Response
{
  "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
You can configure your media retention period in the organization settings.

​
Best Practices

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.
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.
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.
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.

​
Supported Platforms

PlatformMedia TypesNotes
SMS/MMSImages, videos, audioMMS media is downloaded and stored when received
WhatsAppImages, videos, audio, documents, stickersAll media types except contacts and location