Documentation Home KeepSafe Messenger Home

Live Activities API

Base URL: https://messenger.keepsafe.ai

Authentication

App API calls use an app API token generated from the admin setup flow. Send it as a bearer token.

Authorization: Bearer <API_TOKEN>

Scope	Purpose
`device:write`	Register or update device push tokens, ActivityKit Live Activity push tokens, SMS recipients, and email recipients.
`slack:write`	Register or update Slack incoming webhook recipients.
`push:send`	Initiate push notifications and Live Activity updates.
`sms:send`	Initiate SMS messages through AWS End User Messaging.
`email:send`	Initiate email messages through SendGrid.
`slack:send`	Initiate Slack messages through registered incoming webhooks.
`admin`	Admin-level API access.

Register Live Activity

POST /api/live-activities/register

curl -X POST https://messenger.keepsafe.ai/api/live-activities/register \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","environment":"production","token":"ACTIVITYKIT_PUSH_TOKEN","activityId":"GAME_ID","attributesType":"GameAttributes"}'

curl -X POST https://messenger.keepsafe.ai/api/live-activities/register \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","environment":"production","activityKitPushToStartToken":"PUSH_TO_START_TOKEN","attributesType":"FireGameActivityAttributes","deviceId":"INSTALL_ID"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Use the app ID from admin or the bundle/package ID.
`environment`	No	Defaults to `production`. Accepted values: `production`, `sandbox`, or `development`. Development Live Activity sends use APNs sandbox delivery.
`token`	One token required	Legacy per-activity update token. Aliases: `pushToken`, `liveActivityPushToken`, or `activityKitPushToken`. Missing `tokenType` is treated as `activityUpdate`.
`activityKitPushToStartToken`	One token required	ActivityKit push-to-start token from `Activity<Attributes>.pushToStartTokenUpdates`. Stored as `tokenType=pushToStart` and not tied to an activity ID.
`tokenType`	No	`activityUpdate` or `pushToStart`. Push-to-start tokens should use `activityKitPushToStartToken`; existing clients can omit this field.
`activityId`	No	Your app's stable identifier for an existing live activity, such as a game or order ID. Push-to-start registrations store this as empty.
`attributesType`	No	The ActivityKit attributes type name if useful for routing later.
`deviceId`	No	Stable install/device identifier if the app has one.

Send Live Activity Start/Update

POST /api/live-activities/send

curl -X POST https://messenger.keepsafe.ai/api/live-activities/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","environment":"production","event":"start","eventId":"GAME_ID","attributesType":"FireGameActivityAttributes","attributes":{"matchup":"SEA @ POR"},"contentState":{"status":"Starts in 30 min","awayName":"SEA","awayScore":"-","homeName":"POR","homeScore":"-","detail":"Pregame"},"title":"SEA @ POR","body":"Starts in 30 minutes"}'

curl -X POST https://messenger.keepsafe.ai/api/live-activities/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","environment":"production","activityId":"GAME_ID","event":"update","timestamp":1781571000,"staleDate":1781571090,"contentState":{"status":"Q3 04:12","awayName":"SEA","awayScore":"72","homeName":"POR","homeScore":"69","detail":"Live score"},"dryRun":true}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Identifies the app that owns the Live Activity.
`environment`	No	Defaults to `production`. Accepted values: `production`, `sandbox`, or `development`. Development Live Activity sends use APNs sandbox delivery.
`activityId`, `target.activityIds`, token target, or `deviceId`	No	Updates/end events target stored `activityUpdate` tokens. Start events target stored `pushToStart` tokens. Token target accepts `token`, `pushToken`, `liveActivityPushToken`, `activityKitPushToken`, `tokens`, or `target.tokens`. Device targeting accepts `deviceId`, `deviceIds`, or `target.deviceIds`.
`event`	No	`start`, `update`, or `end`. Defaults to `update`.
`eventId`	Start only	Required for `event=start`. Used for ActivityKit `attributes.eventId` and idempotency per device/game.
`attributesType`	Start only	Required for `event=start`. Must match the iOS ActivityKit attributes type, such as `FireGameActivityAttributes`.
`attributes`	Start only	Optional JSON object for start attributes. `eventId` is inserted automatically from the top-level `eventId`.
`contentState`	Yes	JSON object sent as APNs `aps.content-state`.
`input-push-token`	Automatic for start	For `event=start`, the payload includes `aps.input-push-token = 1` so the app can upload the per-activity update token after the Live Activity starts.
`alert`	No	Optional APNs alert object. If omitted, `title`/`body` are used when present.
`timestamp` / `staleDate` / `dismissalDate`	No	Unix timestamps mapped to APNs `timestamp`, `stale-date`, and `dismissal-date`. If omitted, `timestamp` defaults to current Unix seconds.
`dryRun`	No	Set `true` to record matched Live Activity tokens without sending to APNs.