Expo Push (Classic)

Segments

Named groups of subscribers, joined by key or computed from app activity, that sends and schedules can target.

A segment is a named group of subscribers (indie sub ids). There are two kinds:

Kind	Membership	Example
Manual	Subscribers join and leave by a stable key from your app, in any framework.	"Beta testers", "Sunday volunteers"
Auto	Computed live from app-open activity.	"Lapsed (30 days)", "Active (7 days)", "New (7 days)"

Manual segments

A manual segment has a key you choose at creation: 1–64 characters, lowercase letters, digits, dashes or underscores, starting with a letter or digit. Your app subscribes with it, so it can't change. Delete and recreate the segment to change it.

Join from your app

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 are idempotent, so 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" }

Call	Status	Response
`subscribe`	`201`	`{ ok, joined, alreadyMember, subscriberId, count, segment }`
`unsubscribe`	`200`	`{ ok, removed, wasMember, subscriberId, count, segment }`

count is the segment's live size after the change. Errors use { "error": { "code", "message", "field"? } }:

Status	Code	Meaning
`400`	`missing_field`	`segmentKey` or `subscriberId` is missing.
`400`	`invalid_subscriber_id`	`subscriberId` is over 256 characters.
`400`	`app_not_found`	The app id is unknown.
`400`	`auto_segment`	Clients can't join an auto segment by key.
`404`	`segment_not_found`	No segment has that key.
`502`	`subscribe_failed`, `unsubscribe_failed`	The change wasn't saved. Retry.
`401`	—	A wrong `appId` and `appToken` pair, with a plain-text message.

Manage from the agent or the API

On a classic app, the agent in chat manages segments with get_audiences, create_segment, update_segment, delete_segment, add_segment_members and remove_segment_members. The composer and Scheduling tab in Native Notify can target an existing segment. Over MCP an agent can only read segments, with list_segments (the ids a schedule rule targets).

The account routes need a Native Notify dashboard session or an MCP access token, and an app token gets 403:

GET    /api/apps/:appId/segments
POST   /api/apps/:appId/segments
GET    /api/apps/:appId/segments/:segmentId
PATCH  /api/apps/:appId/segments/:segmentId
DELETE /api/apps/:appId/segments/:segmentId
POST   /api/apps/:appId/segments/:segmentId/members
POST   /api/apps/:appId/segments/:segmentId/members/remove

Deleting a segment that a schedule rule depends on answers 409.

Auto segments

Auto segments update themselves from the app opens Native Notify already records for subscribers. Each indie registration (registerIndieID() or POST /api/indie/id) counts as an app open for that sub id.

Rule	Membership
`lapsed_30d`	Subscribers who haven't opened the app in the last 30 days.
`active_7d`	Subscribers who opened the app in the last 7 days.
`new_7d`	Subscribers whose first recorded app open was in the last 7 days.

There's one segment per rule per app. Auto segments reject manual member edits and can't be joined by key.

Send to a segment

Schedule rules: audienceKind: "segment" with segmentId. See Scheduling.
Sends: Native Notify and the agent resolve a segment to its subscriber ids and send through the indie group path. The public group push API takes subIDs directly.

5,000-member cap

A segment of more than 5,000 members is refused (a 400 in the composer, a blocked run in a schedule) instead of sent in part, so split it or send to all devices.

What a subscriber is

A subscriber is the sub id you register with registerIndieID() or POST /api/indie/id. One sub id can cover many devices, and a whole small group can share one.

Apps on the push API use groups instead of segments.

PreviousScheduling Next Tokens & receipts