Skip to documentation content

Links and tap actions

In the iOS app version 1.1, url sets what happens when a newly sent notification is tapped. It is independent of the optional imageUrl attachment.

Open a website

bash
curl -X POST "https://push.palmpush.com/send/<listener-token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Build finished","body":"Read the next steps.","url":"https://www.palmpush.com/docs"}'

Replace <listener-token> with your listener token and use your own destination URL. The backend does not fetch this URL; the receiving device opens it on tap.

Open another app

An HTTPS Universal Link can open the destination's app if it is installed and supports that link. Otherwise, iOS normally opens the website. palmpush cannot force an arbitrary website link to open a particular app.

You can also use an installed app's documented URL scheme. For example, a Telegram link can use:

json
{
  "title": "Open Telegram",
  "body": "Continue in Telegram.",
  "url": "tg://resolve?domain=telegram"
}

The target app must support the scheme and destination. If iOS cannot open the link, palmpush shows an error and falls back to the message's History entry.

Open History instead

Omit url to open the matching entry in the listener's History. The app finds its page, scrolls to the entry, and highlights it. This works when palmpush is already open, in the background, or closed.

If the entry is unavailable, recent events are shown instead. A removed listener subscription must be added again before its History can be used.

Older app versions keep their previous tap behavior. Notifications sent before the routing update may open the app normally, even after updating. Previously delivered notifications cannot gain a new destination retroactively.

URL requirements

  • Use an absolute URL, up to 2,048 characters.
  • Do not include a username, password, spaces, or control characters.
  • Encode spaces as %20 where needed.
  • HTTP(S) and supported app schemes are accepted. Executable or local schemes such as javascript:, data:, and file: are rejected.
  • The URL contributes to the push payload size; keep long tracking URLs short enough for the provider limit.

The HTTP API accepts url directly. JavaScript supports it starting with palmpush 0.3.0; MCP supports it starting with @palmpush/mcp 0.2.0. Older versions only forward title/body; use the HTTP API until you can upgrade. PWA setup documents HTTP(S) destinations and the PWA-root fallback for browser notifications.