---
title: Topics & Preferences · BuzzKit
description: Named notification categories with per-topic, per-channel choices for every subscriber.
canonical: https://buzzkit.dev/features/topics
last-updated: 2026-09-02
---

# A settings screen with no backend code. Per topic, per channel, resolved for you.

Topics are the named categories your notifications belong to: workout reminders, progress updates, tips and offers. Each subscriber chooses per topic and per channel, and every send to a topic filters to the people who said yes.

## Defaults with overrides

A topic carries a baseline choice, optional per-channel defaults and a category heading. Resolution is explicit choice first, then the channel default, then the topic default.

```
POST /v1/topics
{
  "slug": "running-reminders",
  "name": "Running reminders",
  "category": "Training",
  "channels": ["push", "email"],
  "defaultOptedIn": true,
  "channelDefaults": { "email": false },
  "dailyCap": 3
}
```

## The settings screen is two requests

A GET on the client preferences endpoint returns the topic catalog with the resolved state per channel and its category, and a PATCH saves a choice. The iOS SDK wraps both.

```
PATCH /v1/client/preferences
BuzzKit-Subscriber: user_42
{
  "preferences": {
    "marketing": false,
    "running-reminders": { "email": false }
  }
}
```

## Every send respects the choice

Sending targets a topic and a channel, and BuzzKit filters to subscribers whose preference for that pair is opted in. A muted device, a topic turned off or a channel switched off all stop a delivery before it is queued.

```
POST /v1/messages
{
  "topic": "running-reminders",
  "channel": "push",
  "title": "Tempo run tonight",
  "body": "Track is booked from 19:00."
}

// Only subscribers opted into running-reminders
// on push are reachable
{ "id": "msg_4k1d", "counts": { "total": 812 } }
```

## Capabilities

- **Deviations only.** Only changes are stored, so defaults keep applying to everyone else.
- **Categories.** Group topics under headings for the settings screen.
- **Server or client.** Read and write preferences from your backend or from the app.
- **Identity verification.** A hash from your backend proves which user a request speaks for.
- **Kept through changes.** Narrowing a topic’s channels keeps the stored choices.
- **On the timeline.** Every change writes a preferences event to the subscriber’s stream.

## Questions

### How do I let users choose which notifications they get?

Create a topic per category, then render the client preferences endpoint as a list of switches. The iOS SDK does this out of the box.

### What happens when I change a topic’s default?

Subscribers who never chose follow the new default immediately. Subscribers who chose keep their choice.

### Can a subscriber opt out of push but keep email for the same topic?

Yes. Preferences are per topic and per channel, so a subscriber can keep the email and turn off the push, or the other way around.

## Related

- [Sending](https://buzzkit.dev/features/sending.md): One POST sends to a subscriber, a topic or a segment and lands on every device.
- [Segments](https://buzzkit.dev/features/segments.md): Saved expressions over attributes and events, evaluated fresh at send time.
- [iOS SDK](https://buzzkit.dev/features/ios-sdk.md): Registration, identity, events, action buttons and a notification settings screen in one Swift package.

## Start

- [Start sending](https://buzzkit.dev/dashboard)
- [API Reference](https://docs.buzzkit.dev)
- [BuzzKit on GitHub](https://github.com/buzzkit-dev/buzzkit)