Topic Push Notification APIs

Subscribe registered Indie Push subscribers to custom topic groups. Then send push notifications only to individuals subscribed to those topic groups. Send notifications based on topics.

Required:

You must follow the Indie Registration Guide instructions before using the APIs listed on this page. Topic Push APIs will not work without first following the Indie Registration Guide

Prerequisites

1

Create a free Native Notify account

Create a free NativeNotify.com account to get your Native Notify App ID and App Token.

Create a Topic Group API

Use this API to create a Topic Group that Indie Push subscribers will be able to follow. You can create as many Topic Groups as you want.

Post to this URL:

https://app.nativenotify.com/api/post/follow/master

Use this POST body:

{
  masterSubID: "your Topic Group name",
  appId: app-id-number,
  appToken: "app-token-string",
  isTopicGroup: true
}

It answers 201 with Follower Master Indie ID posted!, or 400 with Master ID already exists. — Topic Group names share one namespace with follow-master IDs (registerFollowMasterID), so a name already used by either is taken.

Subscribe a user to a Topic Group API

API Notes:

  • Use this API to subscribe an Indie Push subscriber to a topic group.
  • Put the name of the Topic Group in the masterSubID key value you want to subscribe an Indie Push subscriber to.
  • Put the Indie Push unique user ID you registered with Native Notify in the followerSubID that you want to subscribe to this Topic Group.

Post to this URL:

https://app.nativenotify.com/api/post/follower

Use this POST body:

{
  masterSubID: "your Topic Group name",
  followerSubID: "the Indie Push unique user ID you want to subscribe to this Topic Group",
  appId: app-id-number,
  appToken: "app-token-string",
}

It answers 201 with Follower Indie ID posted! (or Follower sub id already exists when that ID is already subscribed), and 404 with an empty body when the Topic Group does not exist.

Send a Push Notification to Topic Group Subscribers API

Use this API to send a push notifications to all Indie Push unique user IDs subscribed to a Topic Group.

Post to this URL:

https://app.nativenotify.com/api/follow/notification

Use this POST body:

{
  masterSubID: "your registered Topic Group name",
  appId: app-id-number,
  appToken: "app-token-string",
  title: "push notification title",
  message: "push notification message"
}

The body also accepts pushData, bigPictureURL and Expo's modern message fields — see Rich Notifications.

Responses:

  • 201 with Success! — the send went to the Topic Group's subscribers. (It currently also answers Success! when the account's free trial has ended or the membership does not include group pushes, although nothing is delivered then.)
  • 201 with The ID does not exist or the ID has no followers/subscribers. — nobody is subscribed yet, nothing was sent.
  • 404 with an empty body — no Topic Group with that name.
  • 400 — a missing title / message or an invalid rich field. A payload over Expo's 4 KiB limit answers 500.

Get names of all Topic Groups API

Use this API to get all the names of Topic Groups that have been successfully registered with Native Notify.

Run a GET request to this URL:

https://app.nativenotify.com/api/all/app/topic/group/names/${app-id}/${app-token}

It answers 201 with [{ "topic_group_names": "<name>" }, …], sorted by name — only groups created with isTopicGroup: true.

Notes:

  • Replace "app-id" with your Native Notify App ID.
  • Replace "app-token" with your Native Notify App Token.

Unsubscribe a User from a Topic Group API

Use this API to unsubscribe an Indie Push unique user ID from an existing Topic Group.

Run a PUT request to this URL:

https://app.nativenotify.com/api/unfollow/master

Use this PUT body:

{
  masterSubID: "your Topic Group name",
  followerSubID: "the Indie Push unique user ID you want to unsubscribe from this Topic Group",
  appId: app-id-number,
  appToken: "app-token-string",
}

It answers 201 with Follower ID unfollowed Master ID! (also when the ID was not subscribed), and 404 when the Topic Group does not exist.

Show what Indie Push Ids are subscribed to a Topic Group API

Use this API to get all the Indie Push unique user IDs subscribed to a specific Topic Group.

Run a GET request to this URL:

https://app.nativenotify.com/api/topic/group/${topic-group-name}/${app-id}/${app-token}

It answers 201 with { "topic_group_sub_ids": [...], "topic_group_sub_count": N }, or 400 with There are no Topic Groups with that name.

Notes:

  • Replace "topic-group-name" with the currently registered Topic Group name (URL-encode it — for example with encodeURIComponent — when it contains spaces).
  • Replace "app-id" with your Native Notify App ID.
  • Replace "app-token" with your Native Notify App Token.

Delete a Topic Group API

Use this API to delete a Topic Group. (Be careful! This cannot be undone!)

Run a DELETE request to this URL:

https://app.nativenotify.com/api/follow/master/${app-id}/${app-token}/${topic-group-name}

It answers 201 with Delete Follow Master successful! (also when no group had that name).

Notes:

  • Replace "topic-group-name" with the currently registered Topic Group name (URL-encoded).
  • Replace "app-id" with your Native Notify App ID.
  • Replace "app-token" with your Native Notify App Token.