Documentation Home KeepSafe Messenger Home

SMS Messages 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 SMS Recipient

POST /api/sms/register

curl -X POST https://messenger.keepsafe.ai/api/sms/register \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","recipientId":"user-123","phoneNumber":"512-555-1234","label":"Jon"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Use the app ID from admin or the bundle/package ID.
`recipientId`	Yes	Unique ID for this SMS recipient within the app. Specific SMS sends use this value, not the phone number. Aliases: `recipientKey` or `externalId`.
`phoneNumber`	Yes	Phone number to register for this app. North American numbers may be sent with punctuation or without `+1`; stored event history exposes previews only.
`label`	No	Optional name or device label for the admin recipient table.

Send SMS

POST /api/sms/send

Specific Recipient IDs

curl -X POST https://messenger.keepsafe.ai/api/sms/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","recipientIds":["user-123"],"message":"Hello from KeepSafe Messenger","dryRun":true}'

Broadcast

curl -X POST https://messenger.keepsafe.ai/api/sms/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","target":{"type":"broadcast"},"message":"Hello registered recipients"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Identifies the app that owns the send event.
`recipientId`, `recipientIds`, or `target.recipientIds`	No	Specific send target. Every ID must already be registered for this app.
`target.type`	No	Use `broadcast` to send to all registered SMS recipients for the app. Specific sends use recipient IDs, not phone numbers.
`message` or `body`	Yes	SMS body.
`messageType`	No	`TRANSACTIONAL` or `PROMOTIONAL`. Defaults to `TRANSACTIONAL`.
`dryRun`	No	Set `true` to record the SMS event without calling AWS.