Skip to content

Rich Media

Attach an image, video, or audio file. iOS downloads and renders the attachment inline when the user expands the notification.

Notification with rich media attachment on the lock screen
PushWard app detail view of the notification with an inline video player and tap link

The media object

FieldTypeRequiredDescription
media.urlstringYesHTTPS URL to the asset (max 2048 chars). HTTP is rejected.
media.typestringYesOne of image, video, or audio.
ℹ Info

The request takes a nested media object, but the server flattens it on the way back out — responses return media_url and media_type as top-level fields rather than a nested object.

⚠ Warning

Apple enforces strict size caps on notification attachments — image 10 MB, audio 5 MB, video 50 MB. Larger files are silently dropped by the iOS notification service extension and the notification falls back to a plain alert with no media.

Image

JPEG, PNG, GIF, and HEIC are supported. iOS shows the image inline on the lock screen and in the expanded notification.

Image attachment 
curl -X POST https://api.pushward.app/notifications \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Front Door",
    "body": "Someone is at the front door",
    "level": "time-sensitive",
    "media": {
      "url": "https://example.com/snapshots/doorbell.jpg",
      "type": "image"
    },
    "push": true
  }'

Video

MP4 (H.264) is the most reliable format. iOS shows a play button on the inline preview and plays the clip when the user expands the notification.

Video attachment 
curl -X POST https://api.pushward.app/notifications \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Garage Camera",
    "body": "10 seconds of motion captured",
    "level": "time-sensitive",
    "media": {
      "url": "https://example.com/clips/motion.mp4",
      "type": "video"
    },
    "push": true
  }'

Audio

MP3, WAV, and M4A are supported. The expanded notification shows audio playback controls directly.

Audio attachment 
curl -X POST https://api.pushward.app/notifications \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Voice memo",
    "body": "Tap to expand and play",
    "media": {
      "url": "https://example.com/voice/memo-15s.mp3",
      "type": "audio"
    },
    "push": true
  }'
💡 Tip

Host media on a CDN with cache headers — iOS downloads the attachment on every device that receives the push, and slow downloads can cause the notification to fall back to a plain alert before the asset arrives.