Notifications API

BotServer provides RESTful endpoints for managing notifications across multiple channels including push notifications, in-app alerts, and message broadcasting.

Overview

The Notifications API enables:

• Push notifications to users
• Broadcast messages to groups
• Alert management
• Notification preferences
• Delivery tracking

Base URL

http://localhost:8080/api/v1/notifications

Authentication

All Notifications API requests require authentication:

Authorization: Bearer <token>

Endpoints

Send Notification

POST /send

Send a notification to one or more recipients.

Request Body:

{
  "recipients": ["user123", "user456"],
  "title": "System Update",
  "message": "Maintenance scheduled for tonight",
  "priority": "normal",
  "channels": ["web", "email"],
  "data": {
    "action": "view_details",
    "url": "/maintenance"
  }
}

Response:

{
  "notification_id": "ntf_abc123",
  "recipients_count": 2,
  "status": "queued",
  "delivery": {
    "web": "pending",
    "email": "pending"
  }
}

Broadcast Message

POST /broadcast

Send a message to all users or a specific group.

Request Body:

{
  "target": "all",
  "filters": {
    "channel": "web",
    "last_active": "7d"
  },
  "message": {
    "title": "New Feature Available",
    "body": "Check out our latest update!",
    "image_url": "https://example.com/feature.png"
  },
  "schedule": "2024-01-15T14:00:00Z"
}

Response:

{
  "broadcast_id": "brd_xyz789",
  "target_count": 1250,
  "scheduled_for": "2024-01-15T14:00:00Z",
  "status": "scheduled"
}

Get Notification Status

GET /notifications/{notification_id}

Get the status of a sent notification.

Response:

{
  "notification_id": "ntf_abc123",
  "created_at": "2024-01-15T10:00:00Z",
  "status": "delivered",
  "delivery_details": [
    {
      "recipient": "user123",
      "channel": "web",
      "status": "delivered",
      "delivered_at": "2024-01-15T10:00:05Z"
    },
    {
      "recipient": "user123",
      "channel": "email",
      "status": "delivered",
      "delivered_at": "2024-01-15T10:00:10Z"
    }
  ]
}

List Notifications

GET /notifications

List sent notifications with optional filters.

Query Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 20)
• status - Filter by status
• channel - Filter by channel
• start_date - Start date filter
• end_date - End date filter

Response:

{
  "notifications": [
    {
      "notification_id": "ntf_abc123",
      "title": "System Update",
      "status": "delivered",
      "created_at": "2024-01-15T10:00:00Z",
      "recipients_count": 2
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20
}

Mark as Read

PATCH /notifications/{notification_id}/read

Mark a notification as read by the current user.

Response:

{
  "notification_id": "ntf_abc123",
  "marked_as_read": true,
  "read_at": "2024-01-15T10:05:00Z"
}

Delete Notification

DELETE /notifications/{notification_id}

Delete a notification from the system.

Response:

{
  "deleted": true,
  "notification_id": "ntf_abc123"
}

User Preferences

Get Preferences

GET /users/{user_id}/preferences

Get notification preferences for a user.

Response:

{
  "user_id": "user123",
  "preferences": {
    "email": {
      "enabled": true,
      "frequency": "immediate"
    },
    "push": {
      "enabled": true,
      "quiet_hours": {
        "enabled": true,
        "start": "22:00",
        "end": "08:00"
      }
    },
    "sms": {
      "enabled": false
    },
    "categories": {
      "system": true,
      "marketing": false,
      "updates": true
    }
  }
}

Update Preferences

PATCH /users/{user_id}/preferences

Update notification preferences.

Request Body:

{
  "email": {
    "enabled": false
  },
  "push": {
    "quiet_hours": {
      "enabled": true,
      "start": "23:00",
      "end": "07:00"
    }
  }
}

Notification Templates

Create Template

POST /templates

Create a reusable notification template.

Request Body:

{
  "name": "welcome_message",
  "title": "Welcome to {{app_name}}",
  "body": "Hi {{user_name}}, welcome to our platform!",
  "channels": ["email", "push"],
  "variables": ["app_name", "user_name"]
}

Use Template

POST /send/template

Send notification using a template.

Request Body:

{
  "template": "welcome_message",
  "recipients": ["user789"],
  "variables": {
    "app_name": "BotServer",
    "user_name": "John"
  }
}

Notification Types

System Notifications

Critical system messages and alerts.

{
  "type": "system",
  "priority": "high",
  "persistent": true,
  "require_acknowledgment": true
}

User Notifications

Personal messages and updates.

{
  "type": "user",
  "priority": "normal",
  "expires_at": "2024-01-22T10:00:00Z"
}

Broadcast Notifications

Mass communications to multiple users.

{
  "type": "broadcast",
  "target": "segment",
  "segment_id": "active_users"
}

Delivery Channels

Web Push

Browser push notifications.

{
  "channel": "web",
  "options": {
    "icon": "https://example.com/icon.png",
    "badge": "https://example.com/badge.png",
    "vibrate": [200, 100, 200],
    "require_interaction": false
  }
}

Email

Email notifications with rich content.

{
  "channel": "email",
  "options": {
    "from": "noreply@example.com",
    "reply_to": "support@example.com",
    "attachments": [],
    "html": true
  }
}

SMS

Text message notifications.

{
  "channel": "sms",
  "options": {
    "sender_id": "BOTSERV",
    "unicode": true
  }
}

In-App

Notifications within the application.

{
  "channel": "in_app",
  "options": {
    "persist": true,
    "category": "updates"
  }
}

Webhook Events

Delivery Events

Configure webhooks to receive delivery updates.

{
  "event": "notification.delivered",
  "notification_id": "ntf_abc123",
  "recipient": "user123",
  "channel": "email",
  "delivered_at": "2024-01-15T10:00:10Z"
}

Interaction Events

Track user interactions with notifications.

{
  "event": "notification.clicked",
  "notification_id": "ntf_abc123",
  "user_id": "user123",
  "clicked_at": "2024-01-15T10:05:00Z",
  "action": "view_details"
}

Error Responses

400 Bad Request

{
  "error": "invalid_recipients",
  "message": "One or more recipients are invalid",
  "invalid_recipients": ["unknown_user"]
}

429 Rate Limit

{
  "error": "rate_limit_exceeded",
  "message": "Notification send limit exceeded",
  "limit": 100,
  "window": "1h",
  "retry_after": 3600
}

Usage Examples

Send Simple Notification

curl -X POST \
  -H "Authorization: Bearer token123" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["user123"],
    "title": "Hello",
    "message": "This is a test notification"
  }' \
  http://localhost:8080/api/v1/notifications/send

Schedule Broadcast

curl -X POST \
  -H "Authorization: Bearer token123" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "all",
    "message": {
      "title": "Scheduled Maintenance",
      "body": "System will be unavailable from 2 AM to 4 AM"
    },
    "schedule": "2024-01-20T02:00:00Z"
  }' \
  http://localhost:8080/api/v1/notifications/broadcast

Best Practices

1. Batch Notifications: Send to multiple recipients in one request
2. Use Templates: Maintain consistent messaging
3. Respect Preferences: Check user settings before sending
4. Handle Failures: Implement retry logic
5. Track Delivery: Monitor delivery rates
6. Avoid Spam: Rate limit and deduplicate messages

Rate Limits

Related APIs

• User API - User management
• WebSocket API - Real-time notifications
• Email API - Email notifications