Transactional Push

Send transactional push notifications to your users

Overview

Flameup's transactional push API sends notifications directly to a user's registered devices. Use it for notifications triggered by user actions like order confirmations, password resets, and account alerts.

Transactional email is not sent through the public API key — send it via campaigns or the Flameup dashboard. See Campaigns.

Push Notifications

Send push notifications to a user's registered devices.

Required: User must have a registered device token. See Devices API for registration. Your API key must have access to the target workspace.

Send Push Notification

Endpoint: POST /api/v1/workspaces/{workspace_id}/push/send

async function sendPush(personId, title, body, options = {}) {
  const response = await fetch(
    `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/push/send`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        person_id: personId,
        title: title,
        body: body,
        ...options
      })
    }
  );

  return response.json();
}

// Example: Order confirmation
await sendPush('550e8400-e29b-41d4-a716-446655440000',
  'Order Confirmed!',
  'Your order #ORD-12345 has been confirmed. Total: $99.99',
  {
    action_url: 'myapp://orders/ORD-12345',
    ios_badge: 1
  }
);

import requests

def send_push(person_id, title, body, **options):
    response = requests.post(
        f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/push/send',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {API_KEY}'
        },
        json={
            'person_id': person_id,
            'title': title,
            'body': body,
            **options
        }
    )
    return response.json()

# Example: Order confirmation
send_push(
    '550e8400-e29b-41d4-a716-446655440000',
    'Order Confirmed!',
    'Your order #ORD-12345 has been confirmed. Total: $99.99',
    action_url='myapp://orders/ORD-12345',
    ios_badge=1
)

curl -X POST "https://api.flameup.ai/api/v1/workspaces/your_workspace_id/push/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Order Confirmed!",
    "body": "Your order #ORD-12345 has been confirmed. Total: $99.99",
    "action_url": "myapp://orders/ORD-12345",
    "ios_badge": 1
  }'

Request Body

Field	Type	Required	Description
`person_id`	string	Yes	Flameup person UUID
`title`	string	Yes	Notification title
`body`	string	Yes	Notification body text
`platform`	string	No	Target platform: `ios`, `android`, or `all` (default). Web coming soon.
`image_url`	string	No	URL for rich notification image
`action_url`	string	No	Deep link URL when notification is tapped
`priority`	string	No	Delivery priority: `low`, `normal`, `high`
`ttl`	integer	No	Time to live in seconds
`custom_data`	object	No	Custom key-value payload for your app

iOS Options

Field	Type	Description
`ios_badge`	integer	App badge count
`ios_sound`	string	Notification sound (e.g., `default`)
`ios_category`	string	Action category for interactive notifications

Android Options

Field	Type	Description
`android_channel_id`	string	Notification channel ID
`android_icon`	string	Notification icon resource name
`android_color`	string	Icon color (e.g., `#FF0000`)
`android_sound`	string	Notification sound

Response

{
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "sent_at": "2024-01-15T10:30:00Z",
  "provider": "fcm",
  "provider_id": "projects/myapp/messages/abc123"
}

Field	Description
`message_id`	Flameup message ID
`status`	`pending`, `sent`, `delivered`, or `failed`
`sent_at`	Timestamp when sent
`provider`	Push provider used (`fcm`)
`provider_id`	External message ID from provider
`error`	Error message (only if failed)

Push Notification Examples

// Order confirmation
await sendPush(personId, 'Order Confirmed!',
  'Your order #ORD-12345 is confirmed. Total: $99.99', {
    action_url: 'myapp://orders/ORD-12345',
    ios_badge: 1
});

// Shipping notification
await sendPush(personId, 'Your order has shipped!',
  'Track your package: 1Z999AA10123456784', {
    action_url: 'myapp://tracking/1Z999AA10123456784'
});

// Delivered notification
await sendPush(personId, 'Package delivered!',
  'Your order #ORD-12345 has been delivered.', {
    action_url: 'myapp://orders/ORD-12345/review'
});

// New login alert
await sendPush(personId, 'New Login Detected',
  'New sign-in from Chrome on Windows in New York, US', {
    action_url: 'myapp://security',
    priority: 'high'
});

// Password changed
await sendPush(personId, 'Password Changed',
  'Your password was changed. If this wasn\'t you, contact support.', {
    priority: 'high'
});

// Payment successful
await sendPush(personId, 'Payment Received',
  'We received your payment of $49.99. Thank you!', {
    action_url: 'myapp://receipts/pay_abc123'
});

// Payment failed
await sendPush(personId, 'Payment Failed',
  'Your payment of $49.99 was declined. Please update your card.', {
    action_url: 'myapp://billing',
    priority: 'high'
});

// New follower
await sendPush(personId, 'John Doe is now following you',
  'Tap to view their profile', {
    action_url: 'myapp://profile/user_456',
    image_url: 'https://example.com/avatars/user_456.jpg'
});

// New message
await sendPush(personId, 'New message from Jane',
  'Hey, are you free for lunch?', {
    action_url: 'myapp://chat/chat_789',
    ios_badge: 5
});

Error Handling

Handle these common error cases in your integration.

Push Errors

{
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "No valid device tokens found for user"
}

Common push errors:

No device tokens registered for user
Invalid or expired device token
FCM configuration missing for workspace

Handling in Code

async function sendNotification(personId, title, body, options) {
  try {
    const result = await sendPush(personId, title, body, options);

    if (result.status === 'failed') {
      console.error('Push failed:', result.error);
      // Fallback to email or in-app notification
      return null;
    }

    return result;
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
}

Best Practices

The Push API requires the Flameup person_id (UUID), not your external user ID. Look up the person first or store the person_id when you create users:

// When creating a user, store the person_id
const person = await createPerson({ userId: 'user_123', ... });
// Save person.id for later push notifications

Was this page helpful?