# 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](/docs/indie-push-notifications/registration) instructions before using
> the APIs listed on this page. Topic Push APIs will not work without first
> following the [Indie Registration
> Guide](/docs/indie-push-notifications/registration)

## Prerequisites

1. **Create a free Native Notify account**

   Create a free [NativeNotify.com](https://dashboard.nativenotify.com/sign-up-one)
   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:

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

Use this POST body:

```bash
{
  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:

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

Use this POST body:

```bash
{
  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:

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

Use this POST body:

```bash
{
  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](/docs/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:

```bash
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:

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

Use this PUT body:

```bash
{
  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:

```bash
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:

```bash
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.