📚 Developer Documentation

Learn how to integrate our notification system into your application

Notification SDK

🚀 Quick Start

Step 1: Register Your Application

Fill out the registration form with your application details. Our team will review and approve your request.

Step 2: Get Your API Credentials

Once approved, you'll receive your API key and App ID. These are required for all API requests.

Your credentials will look like:

App ID: my-awesome-app

API Key: spark_abc123_def456

Step 3: Send Your First Notification

Use your API credentials to send notifications through our system.

Example API request:

curl -X POST https://your-domain.com/api/notifications/app/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "user123",
    "title": "Welcome!",
    "message": "Your account has been created successfully.",
    "type": "SUCCESS"
  }'

🔌 API Reference

Authentication

All API requests require authentication using your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Send Notification

Endpoint:

POST /api/notifications/app/send

Request Body:

{
  "recipientId": "string",     // Required: Unique user identifier
  "title": "string",           // Required: Notification title
  "message": "string",         // Required: Notification message
  "type": "string",            // Optional: INFO, SUCCESS, WARNING, ERROR
  "priority": "string",        // Optional: LOW, NORMAL, HIGH, URGENT
  "scheduledFor": "string",    // Optional: ISO 8601 timestamp
  "metadata": {}               // Optional: Additional data
}

Prefer recipientId for repeat sends. Send a full recipient object only when you need the API to create the user on first contact or update stored contact details such as email, phone, or Slack preferences.

When sending a full recipient object, email is currently required even for Slack deliveries. If you only know the Slack identity, first create or resolve the recipient and then use recipientId for later sends.

This direct send API is different from the in-app SDK login flow. SDK login is typically email-backed and used to establish a user notification identity, while direct send requests are for server-side delivery work such as email, in-app, or Slack-targeted notifications.

Example Response:

{
  "success": true,
  "data": {
    "id": "notif_123",
    "status": "PENDING",
    "message": "Notification queued successfully"
  }
}

Get Application Configuration

Endpoint:

GET /api/applications?apiKey=YOUR_API_KEY&appId=YOUR_APP_ID

Example Response:

{
  "success": true,
  "data": {
    "appId": "my-awesome-app",
    "name": "My Awesome App",
    "defaultProvider": "novu",
    "fallbackStrategy": "failover",
    "maxRetries": 3,
    "isActive": true
  }
}

💻 Integration Examples

JavaScript/Node.js

const sendNotification = async (recipientId, title, message) => {
  try {
    const response = await fetch('https://your-domain.com/api/notifications/app/send', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        recipientId,
        title,
        message,
        type: 'INFO'
      })
    });
    
    const result = await response.json();
    if (result.success) {
      console.log('Notification sent:', result.data);
    }
  } catch (error) {
    console.error('Failed to send notification:', error);
  }
};

// Usage
sendNotification('user123', 'Welcome!', 'Your account is ready.');

Python

import requests
import json

def send_notification(recipient_id, title, message):
    url = 'https://your-domain.com/api/notifications/app/send'
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
    data = {
        'recipientId': recipient_id,
        'title': title,
        'message': message,
        'type': 'INFO'
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        result = response.json()
        if result['success']:
            print('Notification sent:', result['data'])
    except Exception as e:
        print('Failed to send notification:', e)

# Usage
send_notification('user123', 'Welcome!', 'Your account is ready.')

cURL

# Send a simple notification
curl -X POST https://your-domain.com/api/notifications/app/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "user123",
    "title": "Welcome!",
    "message": "Your account has been created successfully.",
    "type": "SUCCESS"
  }'

# Send a scheduled notification
curl -X POST https://your-domain.com/api/notifications/app/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "user123",
    "title": "Reminder",
    "message": "Don't forget your meeting at 2 PM",
    "scheduledFor": "2024-01-15T14:00:00Z"
  }'

🎯 Best Practices

✅ Do's

• Use meaningful recipient IDs
• Provide clear, actionable titles
• Handle API errors gracefully
• Store API key securely
• Use appropriate notification types

❌ Don'ts

• Don't expose API key in client code
• Don't send too many notifications
• Don't ignore rate limits
• Don't use generic recipient IDs
• Don't forget error handling

🆘 Need Help?

If you need assistance with integration or have questions about the API, we're here to help!

📧 Email Support

support@sparkstrand.com

📚 Documentation

Check our comprehensive API documentation for detailed examples and reference.