Send Notification

Send a push notification to your app's users.

Endpoint

POST /api/apps/{appId}/notifications/send

Authentication

Authenticated via the X-NativeSuite-Key header using your app's App Secret. You can find this in the dashboard under your app's Settings → Credentials.

X-NativeSuite-Key: {your-app-secret}

Finding your App Secret

Go to your app's Settings → Credentials in the dashboard. Your credential includes two values:

• Signing Secret — used for request signing (HMAC verification)
• App Secret — used here, to authenticate API calls from your backend to NativeSuite

Request Body

{
  "templateSlug": "string",
  "variables": { "key": "value" },
  "targetUsers": ["user-id-1", "user-id-2"],
  "testReleaseVersion": 1
}

Parameters

Field	Type	Required	Description
templateSlug	string	Yes	The slug of a notification template from the app's live release
variables	object	No	Key-value pairs to fill in placeholders in the template
targetUsers	string[]	No	End user IDs to target. If omitted, sends to all connected users
testReleaseVersion	integer	No	Target a specific test release version instead of the live release

Example

Template

Title: Payment received
Body: {{amount}} from {{customer_name}}

Request

curl -X POST https://api.staging.nativesuite.io/api/apps/{appId}/notifications/send \
  -H "X-NativeSuite-Key: your-app-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "payment-received",
    "variables": {
      "amount": "$1,240.00",
      "customer_name": "Acme Corp"
    },
    "targetUsers": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Response

Success (200):

{
  "messageCount": 1
}

messageCount is the number of notifications queued for delivery.

Error (401) — missing or invalid credential:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "X-NativeSuite-Key header is required"
}

Error (404) — template not found:

{
  "title": "Not Found",
  "status": 404,
  "detail": "notification template not found"
}

Error (422) — no live release:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "app has no live release"
}

Sending to Test Releases

During development, you can send notifications against a test release instead of the live one by passing testReleaseVersion:

{
  "templateSlug": "payment-received",
  "variables": { "amount": "$500" },
  "testReleaseVersion": 2
}

This targets the template from release version 2 (which must be in Testing status) and delivers to testers.

Notes

• Templates are matched by slug, not by ID
• If targetUsers is omitted, the notification is sent to all users connected to the app
• Variables that don't match any in the template are silently ignored
• Missing variables are rendered as empty strings
• Notifications are delivered asynchronously — the response confirms the messages were queued, not delivered