> For the complete documentation index, see [llms.txt](https://help.twinr.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.twinr.dev/push/personalized-push-notification.md).

# Twinr Push API

Send a push notification to one specific person from your own backend, using their device token.

Campaigns in Engage send to everyone, or to a segment. The Twinr Push API is for the other case: a notification aimed at one person, sent by your own code when something happens — an order ships, a message arrives, a booking is confirmed.

{% hint style="info" %}
The Push API is included with every premium plan.
{% endhint %}

## What you need to set up

Three things, in this order:

1. **Turn on Personalized push notification** in Engage.
2. **Collect device tokens** from the app with the JS bridge, and store them against your users.
3. **Send from your backend**, authenticating with an account secret.

## 1. Turn it on in Engage

Open **Engage**, click **+ Create campaign**, and choose **Personalized push notification**.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-21c1fc1d1e20da7db19ff3b974b9b4e064b1e16b%2Fpersonalized-push-webhook.png?alt=media" alt="The Personalized push notification panel with its enable toggle and Webhook URL field"><figcaption></figcaption></figure>

Enter your **Webhook URL** — the endpoint on your own server that receives the app's device IDs — and click **Save as draft**.

## 2. Get the device token

Inside the app, ask for the token and save it against the signed-in user:

```javascript
if (typeof twinr_push_token_fetch === 'function') {
  const result = await twinr_push_token_fetch();
  if (result?.token) {
    await saveTokenForCurrentUser(result.token, result.platform);
  }
}
```

It returns the token and the platform (`android` or `ios`), or nothing if push is not available on that device.

Store tokens against the user, not the session, and allow more than one — a person with a phone and a tablet has a token for each.

{% hint style="warning" %}
**Guard the call.** `twinr_push_token_fetch` exists only inside the Twinr app. The `typeof` check keeps your website working normally in an ordinary browser.
{% endhint %}

See [Push Notification - Device Token](https://help.twinr.dev/js-bridge/push-notification-device-token.md) for more on the bridge call.

## 3. Send the notification

### Create an account secret

The API authenticates with an account secret. Go to **My Profile → Account secrets**, click **Create secret**, and scope it to the organization — or to just the apps this server should be able to reach.

Copy the secret before closing the dialog. Twinr shows it once and cannot show it again.

See [Account Secrets](https://help.twinr.dev/twinr-account/account-secrets.md) for the full walkthrough.

### Make the call

Pass the secret as a Bearer token:

```
POST https://msengageapi.twinr.dev/v3/send-notifications
Authorization: Bearer twnr_live_xxxxxxxxxxxx
Content-Type: application/json
```

```json
{
  "application_id": "your-twinr-application-id",
  "push_tokens": ["token1", "token2"],
  "push_title": "Your order has shipped",
  "push_message": "Track it in the app.",
  "click_action": { "type": "open_app" }
}
```

`application_id`, `push_tokens`, `push_title`, `push_message` and `click_action` are required. `push_image` is optional and takes an image URL.

Your `application_id` is in your Twinr dashboard: open your app in the [Twinr Builder](https://builder.twinr.dev/) and copy the ID from the address bar. The secret must be scoped to this app or to its whole organization.

{% hint style="warning" %}
**Send from your server, never from the browser.** Anything in your website's JavaScript is visible to visitors, and anyone holding your secret can send notifications that appear to come from your app. Keep it in an environment variable on the server and send from there.
{% endhint %}

## What tapping the notification does

`click_action` takes one of exactly three shapes.

{% tabs %}
{% tab title="Open the app" %}

```json
{ "type": "open_app" }
```

Opens the app wherever the person left it.
{% endtab %}

{% tab title="Open a tab" %}

```json
{ "type": "open_tab", "tab_name": "Home" }
```

Opens a specific tab. `tab_name` must match the tab's name in your Twinr dashboard exactly, capitalisation included — a name that does not match simply opens the app.
{% endtab %}

{% tab title="Open a URL" %}

```json
{ "type": "url", "url": "https://example.com/orders/123" }
```

Opens a URL inside the app. Use this for anything about a specific order or record — it is the only shape that can carry an identifier.
{% endtab %}
{% endtabs %}

## Example

Sending to one user from a Node backend:

```javascript
async function notifyUser(userId, title, message, url) {
  const tokens = await getTokensForUser(userId);
  if (tokens.length === 0) return;

  await fetch('https://msengageapi.twinr.dev/v3/send-notifications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TWINR_SECRET}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      application_id: process.env.TWINR_APPLICATION_ID,
      push_tokens: tokens,
      push_title: title,
      push_message: message,
      click_action: url ? { type: 'url', url } : { type: 'open_app' },
    }),
  });
}
```

## Common Questions

<details>

<summary>Nothing arrives when I test.</summary>

Work through these in order: **Personalized push notification** must be enabled in Engage, your account secret must be scoped to this app, the person must have allowed notifications on the device, you must have a stored token for them, and the test must run on a real device — push does not work in a browser or the previewer.

A `401` means the secret is wrong, revoked or expired. A `403` means the secret is valid but not scoped to this app.

</details>

<details>

<summary>How many tokens can I send to at once?</summary>

`push_tokens` takes a list, so one call can reach several devices. Send a person's own devices together rather than one call each.

</details>

<details>

<summary>What if someone signs out, or reinstalls?</summary>

Tokens change. Save the token each time someone signs in, and remove tokens for a user when they sign out so their notifications do not follow them to a shared device.

</details>

<details>

<summary>Can I use Zapier or a similar tool?</summary>

Yes. Anything that can send a POST request with a JSON body and an `Authorization` header will work.

</details>

<details>

<summary>Is this the same as a campaign?</summary>

No. Campaigns are set up in Engage and sent to everyone or to a segment. The Push API is for notifications your own code triggers for one person. See [Push](https://help.twinr.dev/push/overview.md).

</details>
