Push Campaigns

Create, target, and send push campaigns — broadcast, segment-targeted, or scheduled.

A push campaign is a single row in push_campaigns with a title, body, optional data payload, optional segment target, and optional schedule. Creating one inserts the row; sending it hands delivery off to Amba, which fans out to APNs and FCM.

The three shapes

Shape	Configuration	Trigger
Broadcast	no `segment_id`	Sent to every registered token for the project
Targeted	`segment_id: "seg_xxx"`	Sent only to users in that segment
Scheduled	`scheduled_at: "2026-01-15T09:00:00Z"`	Held until the scheduled UTC time, then delivered

Create a campaign

POST /admin/push
 
{
  "name": "win-back-7d",
  "title": "Welcome back!",
  "body": "Your streak is waiting for you.",
  "data": { "screen": "home", "promo": "winback" },
  "segment_id": "seg_inactive_7d",
  "scheduled_at": "2026-04-20T09:00:00Z"
}

Response 201:

{
  "data": {
    "id": "<uuid>",
    "name": "win-back-7d",
    "title": "Welcome back!",
    "body": "Your streak is waiting for you.",
    "data": { "screen": "home", "promo": "winback" },
    "segment_id": "seg_inactive_7d",
    "status": "scheduled",
    "scheduled_at": "2026-04-20T09:00:00Z"
  }
}

Validation rules:

title + body required.
scheduled_at must parse as ISO-8601 and be in the future (INVALID_SCHEDULED_AT / SCHEDULED_AT_IN_PAST).
Without scheduled_at, the campaign starts as draft; send it explicitly via the /send endpoint.

Trigger immediate send

POST /admin/push/:campaignId/send

Status flips from draft to sending inside a conditional UPDATE (prevents double-send races). Delivery starts immediately and rows land in push_deliveries per token.

Conflict cases:

409 ALREADY_SENT — campaign is already sending or sent.
409 ALREADY_SCHEDULED — campaign is waiting on its scheduled_at. Let it fire, or contact support to cancel.

Send a test push

One-off send to your own device — useful for smoke-testing APNs / FCM credentials before a real campaign. See Setup for the full payload.

POST /admin/push/test
 
{
  "title": "Test push",
  "body": "If you see this, push works.",
  "app_user_id": "<uuid>"
}

Segment targeting

segment_id scopes delivery to users matching that segment's rules. See Segments for the 12 operators and rule grammar.

Agent: Push premium subscribers with new content.

1. amba_create_segment({
     project_id: "proj_xxx",
     name: "Premium Users",
     rules: {
       operator: "AND",
       conditions: [{ field: "entitlements.is_active", op: "eq", value: true }]
     }
   })
2. amba_create_push_campaign({
     project_id: "proj_xxx",
     title: "Exclusive drop",
     body: "A new premium lesson is live.",
     segment_id: "seg_xxx"
   })
3. amba_send_push_campaign({ project_id: "proj_xxx", campaign_id: "..." })

Segment membership is re-evaluated every 15 minutes. Campaigns resolve membership at send time, so a user who matched the rule 10 minutes ago but didn't match at send will not receive the push.

MCP tools

Tool	Description
`amba_create_push_campaign`	Create a campaign with optional segment + schedule
`amba_send_push_campaign`	Trigger delivery of a draft / scheduled campaign
`amba_send_test_push`	Send a test push to a device token

Routes reference

Method	Path	Description
`POST`	`/admin/push`	Create campaign
`GET`	`/admin/push`	List campaigns (desc by `created_at`)
`GET`	`/admin/push/:id`	Fetch campaign
`POST`	`/admin/push/:id/send`	Trigger immediate send
`POST`	`/admin/push/test`	Send a test push (app_user_id OR device_token)

Status values

Status	Meaning
`draft`	Created, not yet sent
`scheduled`	Waiting on `scheduled_at`
`sending`	Fan-out in progress
`sent`	Every batch attempted (per-token results live in `push_deliveries`)
`cancelled`	Operator-initiated cancel
`failed`	Delivery couldn't start or failed mid-flight — retry the `/send`

Database tables

Table	Purpose
`push_campaigns`	Campaign definitions with status + schedule + stats
`push_deliveries`	Per-token delivery log: status, error_message, provider_msg_id
`push_tokens`	Registered device tokens with `platform` + `provider`

Scheduling — schedules, delays, and delivery windows.
Setup — APNs / FCM credentials.