Skip to documentation content

Image attachments

Add imageUrl to a send request to attach one image. In the iOS app version 1.1, images can appear in notifications and in the listener's History.

An attachment belongs to one message. To give a listener a persistent photo, set a listener avatar in the app instead.

Send an image

Replace <listener-token> with your listener token:

bash
curl -X POST "https://push.palmpush.com/send/<listener-token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Image test","body":"Expand the notification or open History.","imageUrl":"https://www.palmpush.com/favicon/web-app-manifest-512x512.png"}'

The title and body are still required. You can also add a url to open a website or app when tapped.

Choose an image URL

For the iOS notification attachment, use:

  • An absolute HTTPS URL, up to 2,048 characters, without embedded credentials.
  • A direct JPEG, PNG, or GIF image, not a webpage containing an image.
  • A file no larger than 1 MiB (1,048,576 bytes).
  • A URL accessible without a login, cookies, or custom authorization headers.
  • A correct image content type, such as image/png. If the server uses application/octet-stream, the URL must have a recognized image file extension.

Host the image somewhere the receiving iPhone can reach. Expiring URLs must remain valid long enough for notification delivery and later viewing in History. A short-lived download URL may work at first and fail when opened again.

You can also send imageUrl with JavaScript using palmpush 0.3.0 or newer, or with MCP using @palmpush/mcp 0.2.0 or newer. Older versions do not forward this field; use the HTTP API until you can upgrade. The updated PWA worker supports images where the browser does.

Notification and History display

iOS controls the compact thumbnail and may crop it. Expand the notification to inspect the attachment. palmpush preserves the image's proportions rather than adding padding or permanently making it square.

In History, the image appears above the message in a centered preview with a maximum height. Tap it to open the full-screen viewer and zoom.

If the image cannot be downloaded, is too large, or has an unsupported format, the notification can still arrive with its title and body. An accepted send does not confirm that the image downloaded successfully. Check the image troubleshooting steps if the attachment is missing.

Where the image is stored

The send API stores the image URL in event History and passes it to the push service. It does not upload or copy the attachment file into palmpush storage. The iPhone downloads the attachment for the notification; History loads it from the same URL when needed.

If the original file is changed or removed, later History views may change or lose the image. The image host receives download requests from the viewer's device. Only include image URLs from sources you trust.

Listener avatars use a separate upload and storage flow described in Listeners and History.