Documentation Home KeepSafe Messenger Home

Push Notifications 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 Device

POST /api/devices/register

curl -X POST https://messenger.keepsafe.ai/api/devices/register \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","platform":"ios","environment":"production","token":"APNS_DEVICE_TOKEN","deviceId":"INSTALL_ID"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Use the app ID from admin or the bundle/package ID.
`platform`	Yes	`ios` or `android`.
`environment`	No	Defaults to `production`; use `sandbox` for development APNs tokens.
`token`	Yes	The APNs device token or future FCM token.
`deviceId`	No	Stable install/device identifier if the app has one.

Send Push

POST /api/push/send

Broadcast

curl -X POST https://messenger.keepsafe.ai/api/push/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","platform":"ios","environment":"production","title":"Hello","body":"Broadcast message"}'

Specific Push Token

curl -X POST https://messenger.keepsafe.ai/api/push/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","platform":"ios","environment":"production","target":{"type":"tokens","tokens":["APNS_DEVICE_TOKEN"]},"title":"Hello","body":"One device"}'

Topic

curl -X POST https://messenger.keepsafe.ai/api/push/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","platform":"ios","environment":"production","target":{"type":"topic","topic":"news.breaking"},"title":"Hello","body":"Topic message"}'

Dry Run

curl -X POST https://messenger.keepsafe.ai/api/push/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","platform":"ios","environment":"production","title":"Dry run","body":"No push will be sent","dryRun":true}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Identifies the app to send for.
`platform`	No	`ios` or `android`. Blank includes matching devices across platforms where supported.
`environment`	No	Defaults to `production`.
`title`	Yes	Notification title.
`body`	Yes	Notification body.
`target`	No	Defaults to broadcast. Use `{"type":"tokens","tokens":["..."]}` or `{"type":"topic","topic":"..."}`.
`dryRun`	No	Set `true` to record recipients and deliveries without sending.
`data`	No	Custom data fields merged into the payload.