Push Notifications

Amba runs the full push pipeline. Your app registers a device token through the SDK; you (or your AI agent) create campaigns scoped by segment or schedule; Amba delivers to iOS (via APNs) and Android (via FCM) with retries and per-delivery tracking.

How it works

After a user grants permission, the app calls client.push.registerToken(token, platform).
Admins (or MCP-driven agents) create push campaigns — title, body, data payload, optional segment_id, optional scheduled_at.
Sending (either immediately or at scheduled_at) hands the campaign off to Amba. The campaign's segment is resolved, registered tokens are loaded, users are batched, and the platform-specific delivery runs.
Per-token delivery status is captured so you can see who actually got the notification.

Four campaign 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"`	Delivered at the given UTC time (one global instant)
Local-time	`delivery_mode: "local_time"`, `local_date: "2026-01-15"`, `local_time: "09:00"`	Delivered at 09:00 in each recipient's local timezone (UTC if unset)

SDK usage

Method signatures:

Amba.push.register(token: string, platform: 'apns' | 'fcm', bundleId?: string): Promise<PushToken>
Amba.push.unregister(token: string): Promise<void>

Register a push token

// After getting permission + the native device token
await Amba.push.register(deviceToken, 'apns');
// or
await Amba.push.register(deviceToken, 'fcm');

Remove a push token

await Amba.push.unregister(deviceToken);

Expo setup

Amba.registerPushToken() is the canonical one-call path on Expo. It requests notification permission via expo-notifications, fetches the device's native APNs / FCM token, and forwards it to Amba.push.register — no manual permission dance required:

import { Amba, AmbaApiError } from '@layers/amba-expo';
 
async function askForPush() {
  try {
    const record = await Amba.registerPushToken();
    // record.token is the native APNs / FCM token, already persisted
    // server-side under your project.
    return record;
  } catch (err) {
    if (err instanceof AmbaApiError && err.code === 'PUSH_PERMISSION_DENIED') {
      // User rejected the OS prompt. Surface a "you can change this in
      // Settings" affordance.
    } else if (err instanceof AmbaApiError && err.code === 'PUSH_REGISTRATION_FAILED') {
      // Simulator, web preview, or `expo-notifications` / `expo-device`
      // not installed. Fall through to a soft-ask screen.
    }
    throw err;
  }
}

Peer-deps on expo-notifications + expo-device — both are already in the standard Expo template; install with npx expo install expo-notifications expo-device if you started from a stripped template.

Enable the Expo config plugin in app.json:

{
  "expo": {
    "plugins": [["@layers/amba-expo", { "ios": { "pushNotifications": true } }]]
  }
}

The plugin adds the iOS push entitlement, URL schemes, associated domains, and Android intent filters for notification interactions.

Provider setup

To actually deliver pushes, Amba needs your APNs key and / or FCM service-account credentials. These are encrypted at rest under your project's integration config.

iOS (APNs)

You need:

An APNs Auth Key (.p8 file) from Apple Developer → Keys.
The key's Key ID (10 characters, shown next to the key).
Your Team ID (10 characters, shown in the top right of Apple Developer).
Your app's bundle identifier (e.g. com.example.todoapp).

Configure via MCP:

amba_integrations_configure({
  project_id: "proj_xxx",
  provider: "apns",
  config: {
    key_id: "ABC123DEFG",
    team_id: "TEAM123456",
    bundle_id: "com.example.todoapp",
    apns_key_p8: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    environment: "sandbox" // or "production"
  }
})

Use sandbox for development (TestFlight / Xcode builds) and production for App Store releases.

Android (FCM)

You need:

A Firebase project linked to your app's package name.
A service account JSON with the Firebase Cloud Messaging API permission. Download from Firebase console → Project settings → Service accounts.

Configure via MCP:

amba_integrations_configure({
  project_id: "proj_xxx",
  provider: "fcm",
  config: {
    service_account_json: "{ ...the full JSON file... }"
  }
})

Creating campaigns

Via the Admin API

POST /admin/projects/:projectId/push/campaigns
Authorization: Bearer <developer token>
 
{
  "title": "Welcome back!",
  "body": "You haven't opened the app in a while. Come check out what's new.",
  "name": "win-back-7d",
  "segment_id": "seg_inactive_7d",
  "data": { "screen": "home", "promo": "welcome_back" },
  "scheduled_at": "2026-01-15T09:00:00Z"
}

Response:

{
  "data": {
    "id": "<uuid>",
    "title": "Welcome back!",
    "body": "You haven't opened the app in a while. Come check out what's new.",
    "status": "scheduled",
    "segment_id": "seg_inactive_7d",
    "scheduled_at": "2026-01-15T09:00:00Z"
  }
}

The API rejects scheduled_at values that are in the past or unparseable — it returns 400 SCHEDULED_AT_IN_PAST or 400 INVALID_SCHEDULED_AT.

Trigger immediate delivery

POST /admin/projects/:projectId/push/campaigns/:campaignId/send

Status flips to sending and Amba starts delivering in batches.

Send a test notification

POST /admin/projects/:projectId/push/test
 
{
  "title": "Test push",
  "body": "This is a test notification",
  "device_token": "abc123..."
}

Via MCP (agent-driven)

Agent: Create a push campaign targeting premium users and send it now.

1. amba_segments_create({
     project_id: "proj_xxx",
     name: "Premium Users",
     rules: { operator: "AND", conditions: [
       { field: "entitlements.is_active", op: "eq", value: true }
     ] }
   })
2. amba_push_campaigns_create({
     project_id: "proj_xxx",
     title: "Exclusive Content",
     body: "New premium content is available!",
     segment_id: "seg_xxx"
   })
3. amba_push_campaigns_send({ project_id: "proj_xxx", campaign_id: "..." })

Routes reference

Method	Path	Description
`POST`	`/client/push/tokens`	Register device token
`DELETE`	`/client/push/tokens/:token`	Remove device token
`POST`	`/admin/projects/:projectId/push/campaigns`	Create campaign
`GET`	`/admin/projects/:projectId/push/campaigns`	List campaigns
`GET`	`/admin/projects/:projectId/push/campaigns/:id`	Get campaign
`POST`	`/admin/projects/:projectId/push/campaigns/:id/send`	Trigger immediate send
`POST`	`/admin/projects/:projectId/push/test`	Send a test push to a device token

MCP tools

Tool	Description
`amba_push_campaigns_create`	Create a new campaign with optional segment targeting and scheduling
`amba_push_campaigns_send`	Trigger delivery of a draft / scheduled campaign
`amba_push_send_test`	Send a test push to a specific device token
`amba_integrations_configure`	Configure APNs or FCM credentials

Push Notifications

On this page