Skip to documentation content

JavaScript

Use the palmpush package in a script or backend service to send messages with optional images and tap destinations. The package requires Node.js 18 or newer for its built-in fetch, or a supplied fetch implementation.

Install and send

bash
npm install palmpush

Use the listener ID from Copy id in the iOS app. Replace the example ID:

js
import palmpush from 'palmpush';

const client = palmpush({
  listenerId: 'abc123abc123abc123abc123abc123ab',
});

const result = await client.pushStrict({
  title: 'Build finished',
  body: 'The deployment completed successfully.',
});

console.log(result.delivery.sentCount);

pushStrict(...) returns a promise and rejects on validation errors, failed HTTP requests, and reported provider failures, including partial failures in legacy HTTP 200 responses. Check delivery.sentCount if you need to distinguish an accepted send from an intentional skip, such as a disabled listener. Acceptance does not confirm that an alert appeared on the phone.

Keep listener tokens in your backend or script configuration. Putting one in a public browser bundle makes it available to every visitor. Tokens also permit subscription and shared listener changes; they are not send-only credentials.

Send without waiting

Use push(...) for a notification that should not interrupt the rest of a job:

js
client.push({
  title: 'Agent done',
  body: 'The draft is ready for review.',
  onError: (error) => console.error(error.message),
});

By default, push(...) is fire-and-forget: it returns without a delivery result and handles failures internally. Use onError to observe failures, or pushStrict(...) when your code needs to await a result. Awaiting the default push(...) does not turn it into strict mode.

Send to several listeners

js
const result = await client.pushStrict({
  listenerIds: [
    'abc123abc123abc123abc123abc123ab',
    'def456def456def456def456def456de',
  ],
  title: 'Maintenance finished',
  body: 'All checks passed.',
});

console.log(result.results);

A per-call destination overrides the client's default. Pass only one of listenerId, listenerIds, listenerToken, or listenerTokens. The token and ID names are aliases for the same value.

Images and tap links

These optional fields require palmpush 0.3.0 or newer. Version 0.2.0 only forwards title and body; updating the iOS app does not update an installed npm package. Until you can install 0.3.0, use the HTTP API.

After upgrading, use either field, both, or neither with any push method:

js
const result = await client.pushStrict({
  title: 'Image test',
  body: 'Open the documentation.',
  imageUrl: 'https://www.palmpush.com/favicon/web-app-manifest-512x512.png',
  url: 'https://www.palmpush.com/docs',
});

console.log(result.delivery.sentCount);

imageUrl attaches the image; url sets the tap destination. Omit unused fields instead of passing null or empty strings. Invalid URLs fail validation before sending: strict calls reject and default calls invoke onError. The SDK does not download either URL. Image downloads happen on the receiving device, while the destination opens only when tapped.

The title and body retain their 120 and 4,096 character limits. Each URL is limited to 2,048 characters. Provider limits count the combined payload in bytes; passing the field limits does not guarantee provider acceptance.

See the HTTP API, image requirements, and tap behavior. Listener avatars are configured in the app and work with text sends without a new SDK field.