Segments

A segment is a named group of subscribers (indie sub ids) that you can target in a send or a schedule rule. Two kinds:

Manual segments — join by key

Each manual segment has a key you choose at creation: 1–64 characters, lowercase letters, digits, dashes or underscores (start with a letter or digit). It is the contract your app code subscribes with, so it is immutable after creation — to change it, delete the segment and recreate it.

From your app (any framework)

List what a client can subscribe to:

GET https://app.nativenotify.com/api/segments/list/:appId/:appToken

{
  "ok": true,
  "segments": [
    { "id": 41, "name": "Beta testers", "key": "beta-testers", "kind": "manual", "rule": null, "count": 128, "subscribable": true }
  ]
}

Join and leave (both idempotent — calling subscribe twice is fine):

POST https://app.nativenotify.com/api/segments/subscribe
POST https://app.nativenotify.com/api/segments/unsubscribe

{ "appId": 123, "appToken": "yourAppToken", "segmentKey": "beta-testers", "subscriberId": "user_8241" }

Subscribe answers 201 with { ok, joined, alreadyMember, subscriberId, count, segment }; unsubscribe answers 200 with { ok, removed, wasMember, count, segment }. count is the segment's live size after the change.

Errors use the standard envelope: missing_field (segmentKey/subscriberId), app_not_found, 404 segment_not_found (unknown key), 400 auto_segment (clients cannot join an auto segment by key).

From the dashboard or the agent

The dashboard's Segments tab (Agent Notify) and the agent in chat manage the same objects: create a manual segment (name + optional key + description), rename, delete, add/remove individual subscribers, and see growth/opt-out counts from the recorded join/leave events. Agents have get_audiences, create_segment, update_segment, delete_segment, add_segment_members and remove_segment_members tools.

Deleting a segment that a schedule rule depends on answers 409 — never a silent cascade.

Auto segments

Auto segments update themselves from the app-open data Native Notify already records (SDK registration/app opens, or indie registrations). Three rules ship today:

One segment per rule per app. Auto segments reject manual member edits (and cannot be joined by key) — they are always exactly what the rule says.

Sending to a segment

• Recurring rules: audienceKind: "segment" + segmentId — see Scheduling.
• Sends: the agent and dashboard can send to a segment by resolving it to its subscriber ids through the indie group path; the public group push API takes subIDs directly if you prefer to resolve audience yourself.

What a subscriber is

A subscriber is an indie identity: subscriberId on a universal registration or your sub id on the SDK path (POST /api/indie/id). One subscriber can be many devices — that is the supported pattern (a whole small group can share one sub id).