Manage Push Topics
Subscribe and unsubscribe users from push notification topics
Manage Push Notification Topics
Topics let you segment your push notifications so users only receive what they are interested in. For example, you might create topics like "News", "Offers", and "Order updates" — and let users choose which ones they want to subscribe to.
Topics are created in the starti.app Manager or automatically when you subscribe to a topic that doesn't exist yet. Once users are subscribed, you can send notifications to a specific topic either from the Manager or programmatically through the Admin API.
For the full picture on how push notifications work — including alternative approaches that don't require topics — see Push Notifications.
Request push notification access
Before subscribing to topics, request permission:
const granted = await startiapp.PushNotification.requestAccess();
if (!granted) {
console.log("User denied push notification permissions");
}Get available topics
Fetch the list of topics configured for your app:
const topics = await startiapp.PushNotification.getTopics();
topics.forEach((topic) => {
console.log(topic.name, topic.subscribed);
});Subscribe to topics
const subscribed = await startiapp.PushNotification.subscribeToTopics([
"news",
"promotions",
]);
console.log("Subscribed to:", subscribed);
// [{ topic: "news", name: "News" }, { topic: "promotions", name: "Promotions" }]Unsubscribe from topics
await startiapp.PushNotification.unsubscribeFromTopics(["promotions"]);Build a topic preferences UI
await startiapp.initialize();
const topics = await startiapp.PushNotification.getTopics();
topics.forEach((topic) => {
const toggle = document.createElement("input");
toggle.type = "checkbox";
toggle.checked = topic.subscribed;
toggle.addEventListener("change", async () => {
if (toggle.checked) {
await startiapp.PushNotification.subscribeToTopics([topic.topic]);
} else {
await startiapp.PushNotification.unsubscribeFromTopics([topic.topic]);
}
});
const label = document.createElement("label");
label.textContent = topic.name;
label.prepend(toggle);
document.body.appendChild(label);
});Send a notification to a topic
Once users have subscribed, you can send notifications to a topic from the Manager — or from your own backend using the Admin API. Here is an example using curl:
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '[
{
"topics": ["news"],
"title": "Weekly update",
"body": "Check out what happened this week"
}
]' \
https://api.starti.app/v1/push-notifications/sendThe notification is delivered to all devices subscribed to the news topic. See the Admin API reference for the full list of options, including openToUrl and badgeCount.