---
title: Push
description: Send a notification from the backend to an application's users on iPhone and Android, see what the send accepted, and test the sends with a test double.
slug: /backend-packages/push
order: 10
visibility: public
redirects_from: []
---

# Push

Push lets your application's backend send a notification to your users' phones and tablets. Turn Zero Cloud delivers it to iPhones through Apple and to Android devices through Google. Your backend lists the users or the devices, and the platform finds each device your app registered.

This package is your backend's side of that service. Its client sends one message under your application's [platform credential](/cloud/concepts/glossary/#platform-credential). It reports what the platform accepted from the send, and it throws a typed refusal that includes the platform's refusal name.

## Use it when

Use Push when your backend must tell a signed-in user something while the app is closed: a game ended, an order shipped, a turn is waiting. Your app must sign its users in through your application's [realm](/cloud/concepts/glossary/#realm) and register each device after sign-in. [Send push notifications](/cloud/guides/send-push-notifications/) covers the credentials, the declaration, the device registration, and the send route.

Do not use it for a web page in a browser or for a text message. Neither is offered.

## What it provides

- **A client**, `createPushClient`, which [The client](#the-client) describes. The module has no dependencies and keeps no state.
- **A send to users.** The method `send(users, message)` sends one message to every registered device of the named users. The user identifier is the one the realm returns for the signed-in user.
- **A send to devices.** The method `sendToDevices(installations, message)` sends one message to the named installations, the identifiers your app registered its devices under.
- **The response.** Each send returns `messageId`, `accepted` (the count of deliveries queued), and `unknownUsers` or `unknownDevices`, the users or devices that had no registration.
- **A typed refusal.** Any other response makes the send throw a `PushRefusal`. Its `refusal` member is the platform's refusal name, and `members` contains the refusal's other values.
- **A [test double](/cloud/concepts/glossary/#test-double)**, `createPushDouble` at `@turnzero/push/testing`, which responds to a send as the platform does and records every send. [Test with the double](#test-with-the-double) shows it in use.

| Message member | Required | What it contains |
| --- | --- | --- |
| `notification.title` | Yes | Up to 256 characters. |
| `notification.body` | Yes | Up to 4,000 characters. |
| `notification.badge` | No | The count on the app's icon. |
| `notification.sound` | No | A sound the app bundles, or `default`. |
| `data` | No | String values for the app, at most 4,096 bytes serialized. The key `aps` is reserved. |
| `ttlSeconds` | No | How long an offline device's notification is kept, a day by default and four weeks at most. |
| `collapseId` | No | An identifier the provider uses to combine notifications. It does not prevent every duplicate delivery. |
| `priority` | No | `high` by default, or `normal`. |

## Availability

Version 0.5.4 is the package's current version, and this page describes it. Until the library's next publish, `read_library` can return an earlier version without every change described here. Use the version it returns.

The entry includes the `testing` subpath. It also contains the compiled modules, the [product statement and detailed contract](/cloud/concepts/glossary/#product-statement-and-detailed-contract), and the integration guide. Turn Zero Cloud runs the push service. Call `read_push` to see device counts, the last hour's outcomes, and the month's count against the application's push ceiling.

## Related feature packages

[Account](/cloud/backend-packages/account/) signs users in and tells your backend who they are. [Secrets](/cloud/backend-packages/secrets/) stores the Apple key and the Google service-account file by name. [Logging](/cloud/backend-packages/logging/) records the delivery counters and one line per delivery.

## The client

The package is published in the library as the npm package `@turnzero/push`, not on the npm registry; [Use the library](/cloud/guides/use-the-library/#5-install-a-package-s-compiled-code) installs it with one line. [Send from the backend](/cloud/guides/send-push-notifications/#5-send-from-the-backend) shows a send from a backend route, and a test runs it.

The function `createPushClient(options)` builds the client from one of two forms:

| Option | Meaning |
| --- | --- |
| `api`, `token` | The platform's origin and the application's platform credential, from `TURNZERO_CLOUD_API` and `TURNZERO_CLOUD_APP_TOKEN`. |
| `environment` | `development` or `production`, the environment header's value, where a credential needs one. The platform credential takes none, and the route refuses a value that contradicts it. |
| `fetch` | The fetch-shaped function the client sends through, the global `fetch` by default. |
| `transport` | In place of `api` and `token`: a function of your own, `(path, init)`, that adds the origin and the credential, such as the test double's `transport`. |

Give `transport`, or `api` and `token`, never both. When you build the client with both forms, without a `token`, or with an `api` that is not an http or https address, it throws `PushClientError`, code `client_options`. The two sends, `send(users, message, { signal })` and `sendToDevices(installations, message, { signal })`, return a promise of `{ messageId, accepted, unknownUsers, unknownDevices }`. A send the platform refuses rejects with `PushRefusal`; [Refusals](#refusals) lists its members and names.

## Refusals

Branch on the refusal's name, never on its message. A `PushRefusal` has `refusal`, `status`, `detail`, and `members`. These are the refusals a send meets most often; the [refusals page](/cloud/reference/refusals/) lists all of the platform's refusals, with the cause and remedy of each.

| Refusal | Status | Meaning |
| --- | --- | --- |
| `invalid_request` | 400 | A member of the message is malformed, and the detail identifies it; or a member contains a NUL character (U+0000) or an unpaired UTF-16 surrogate, which the detail identifies instead. |
| `end_user_credential_not_admitted` | 403 | The request used an end-user session. The platform refuses it before checking the push route itself. |
| `platform_credential_required` | 403 | The send request used a session or a minted token. |
| `push_not_configured` | 409 | The environment has no provider configured. |
| `realm_not_declared` | 404 | The application declares no accounts service. |
| `usage_over_quota` | 429 | The send would pass the application's monthly push ceiling. |
| `push_answer_unreadable` | As received | The response does not confirm whether the notification was queued. Read `tzcloud_read_push` to check recent outcomes. Do not retry automatically: the person could receive the notification twice. |

A send refused `usage_over_quota` queued nothing. Its `members` give the month's count, the ceiling, and the send's own deliveries.

## What an application must do

Set the service up as [Send push notifications](/cloud/guides/send-push-notifications/) describes in its steps 1 to 4, and register each device from your app after sign-in.

Send once for each event. The client does not retry: if a response is lost, the platform may already have queued the notification. A `collapseId` lets the provider combine notifications, but does not make resending safe.

Keep a refused send from failing the request that made it. Record the refusal, and respond to the request.

## Test with the double

The factory `createPushDouble(options)` from `@turnzero/push/testing` responds to a send as the platform does, from the devices and the monthly `quota` the test gives it. Build the client with `createPushClient({ transport: double.transport })`, or pass `double.fetch` as the client's `fetch`. Register devices with `double.register(device)`, and read what was sent in `double.sends`. A test runs this sample over the double.

```js
import assert from 'node:assert/strict';
import { createPushClient, PushRefusal } from '@turnzero/push';
import { createPushDouble } from '@turnzero/push/testing';

// A monthly allowance of one delivery, and one registered phone.
const push = createPushDouble({ quota: 1 });
push.register({ installation: 'phone-1', user: 'user-1', platform: 'ios' });
const client = createPushClient({ transport: push.transport });

const sent = await client.send(['user-1', 'user-2'], { notification: { title: 'Game over', body: 'You stumped it.' } });
assert.equal(sent.accepted, 1);
assert.deepEqual(sent.unknownUsers, ['user-2']);
assert.equal(push.sends.length, 1);
// The month's one delivery is spent, so the next send is refused by name and queues nothing.
await assert.rejects(client.send(['user-1'], { notification: { title: 'Again', body: 'One more.' } }), (error) => error instanceof PushRefusal && error.refusal === 'usage_over_quota');
```

The double uses the push route's own refusal names, which [Refusals](#refusals) lists. These come from the double's own setup:

| Refusal | Cause | Remedy |
| --- | --- | --- |
| `push_not_configured` | The double was created with both providers off, `providers: { apns: false, fcm: false }`. | Leave a provider on. |
| `realm_not_declared` | The double was created with `accounts: false`. | Leave the accounts service declared. |
| `platform_credential_required`, `end_user_credential_not_admitted` | The double was created with `credential: 'session'`, `'minted'`, or `'end_user'`. | Leave the credential at the default, `'platform'`. |
| `usage_over_quota` | The sends passed the `quota` the test gave. | Raise `quota`, or `reset()` between tests. |
| A scripted name | `refuseNext(name)` named a refusal, or `failNext()` an unreachable route. | Assert the name the test scripted. |
