Push Notifications

Amba ships a full push pipeline: the client SDK registers device tokens, you (or your AI agent) create campaigns scoped by segment or schedule, and Amba fans out to APNs (iOS) and FCM (Android) with retries and 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, tokens are fetched from push_tokens, users are batched, and the platform-specific delivery runs.
Delivery status lands in push_deliveries per token so you can see who actually got the notification.

Three 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

SDK usage

Method signatures:

client.push.registerToken(token: string, platform: 'ios' | 'android'): Promise<void>
client.push.unregisterToken(token: string): Promise<void>

Register a push token

// After getting permission + the native device token
await client.push.registerToken(deviceToken, 'ios');
// or
await client.push.registerToken(deviceToken, 'android');

Remove a push token

await client.push.unregisterToken(deviceToken);

Expo setup

Amba.init() automatically calls registerForPushNotificationsAsync() and, if the user grants permission, forwards the token to the Amba server. To defer this (e.g. ask for permission later after onboarding):

import { Amba } from '@amba/expo';
 
Amba.init({
  projectId: process.env.EXPO_PUBLIC_AMBA_PROJECT_ID!,
  apiKey: process.env.EXPO_PUBLIC_AMBA_API_KEY!,
  autoRegisterPushToken: false, // register manually later
});
 
async function askForPush() {
  const result = await Amba.registerPushToken();
  if (!result) {
    // Permission denied, simulator, or unsupported platform
    return;
  }
  // result.token is already registered with the server
}

Enable the Expo config plugin in app.json:

{
  "expo": {
    "plugins": [["@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 stored encrypted in project_integrations.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_configure_integration({
  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_configure_integration({
  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_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 Content",
     body: "New premium content is available!",
     segment_id: "seg_xxx"
   })
3. amba_send_push_campaign({ 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_create_push_campaign`	Create a new campaign with optional segment targeting and scheduling
`amba_send_push_campaign`	Trigger delivery of a draft / scheduled campaign
`amba_send_test_push`	Send a test push to a specific device token
`amba_configure_integration`	Configure APNs or FCM credentials

Database tables

Table	Purpose
`push_tokens`	Device tokens with `platform` (`ios` / `android`) + the owning `app_user_id`
`push_campaigns`	Campaign definitions: title, body, data, segment, scheduled_at, status
`push_deliveries`	Per-token delivery log with status + timestamps

Push Notifications

On this page