API Documentation

Complete API reference for NotiBoost. Includes authentication, event ingestion, flow management, and webhooks.

Authentication

All API requests require authentication via API key.

API Key

Use Bearer token in Authorization header:

Authorization: Bearer YOUR_API_KEY

Event Ingestion

Send events from your product system to NotiBoost.

Endpoint

POST /api/v1/events

Request Body

{
  "event_name": "order_created",
  "event_id": "evt_001",
  "occurred_at": "2025-12-01T10:00:00Z",
  "user_id": "u_123",
  "properties": {
    "order_id": "A001",
    "amount": 350000,
    "currency": "VND"
  }
}

Response

{
  "success": true,
  "trace_id": "trc_abc123",
  "event_id": "evt_001",
  "message": "Event ingested successfully"
}

Event Fields

Users API

Manage users in NotiBoost. Users are recipients of notifications.

Create User

POST /api/v1/users

{
  "user_id": "u_123",
  "name": "Nguyễn Văn A",
  "email": "user@example.com",
  "phone": "+84901234567",
  "properties": {
    "segment": "vip",
    "preferred_channel": "zns"
  }
}

Get User

GET /api/v1/users/{user_id}

{
  "user_id": "u_123",
  "name": "Nguyễn Văn A",
  "email": "user@example.com",
  "phone": "+84901234567",
  "channel_data": {
    "email": "user@example.com",
    "phone": "+84901234567",
    "push_token": "fcm_token_abc123",
    "push_platform": "android",
    "zns_oa_id": "123456789"
  },
  "properties": {
    "segment": "vip",
    "preferred_channel": "zns"
  },
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:00:00Z"
}

Update User

PUT /api/v1/users/{user_id}

Delete User

DELETE /api/v1/users/{user_id}

Channel Data Management

Update channel data for user. Supports all channels: ZNS, Email, SMS, and Push.

PUT /api/v1/users/{user_id}/channel_data

{
  "email": "user@example.com",
  "phone": "+84901234567",
  "push_token": "fcm_token_abc123",
  "push_platform": "android",
  "zns_oa_id": "123456789"
}

Available fields:

• email - Email address for Email channel
• phone - Phone number for SMS and ZNS channels (format: +84901234567)
• push_token - Push notification token (FCM or APNS token)
• push_platform - Push platform: "android" or "ios"
• zns_oa_id - Zalo OA ID for ZNS channel (optional, used for user identification)

User Preferences

Manage user notification preferences (channels and categories).

PUT /api/v1/users/{user_id}/preferences

{
  "channels": {
    "zns": { "enabled": true },
    "email": { "enabled": true },
    "sms": { "enabled": true },
    "push": { "enabled": true }
  },
  "categories": {
    "order": { "enabled": true },
    "marketing": { "enabled": false }
  }
}

Audiences API

Manage audiences (user groups) based on filters. Audiences are used to target notifications.

Create Audience

POST /api/v1/audiences

{
  "name": "VIP Customers",
  "description": "Customers with high order value",
  "filter": {
    "properties.order_count": { "gte": 10 },
    "properties.total_spent": { "gte": 1000000 }
  }
}

List Audiences

GET /api/v1/audiences

Get Audience

GET /api/v1/audiences/{audience_id}

Update Audience

PUT /api/v1/audiences/{audience_id}

Delete Audience

DELETE /api/v1/audiences/{audience_id}

Get Audience Users

GET /api/v1/audiences/{audience_id}/users

Get list of users in this audience.

Flow Management

Create and manage notification flows.

Create Flow

POST /api/v1/flows

Example

{
  "name": "order_confirmation",
  "description": "Send order confirmation via ZNS",
  "rules": [
    {
      "condition": "event_name == 'order_created'",
      "action": "send_zns"
    }
  ],
  "channels": ["zns"],
  "template_id": "tpl_order_confirm"
}

Templates API

Manage message templates for channels.

Create Template

POST /api/v1/templates

{
  "name": "order_confirmation_zns",
  "channel": "zns",
  "content": {
    "header": "Xác nhận đơn hàng",
    "body": "Đơn hàng {{order_id}} đã được xác nhận. Tổng tiền: {{amount}} VNĐ",
    "footer": "Cảm ơn bạn đã mua sắm"
  },
  "variables": ["order_id", "amount"]
}

List Templates

GET /api/v1/templates?channel=zns

Get Template

GET /api/v1/templates/{template_id}

Update Template

PUT /api/v1/templates/{template_id}

Batch Operations

Send multiple events or create multiple users at once for better performance.

Batch Events

POST /api/v1/events/batch

{
  "events": [
    {
      "event_name": "order_created",
      "event_id": "evt_001",
      "user_id": "u_123",
      "properties": { "order_id": "A001" }
    },
    {
      "event_name": "payment_success",
      "event_id": "evt_002",
      "user_id": "u_123",
      "properties": { "order_id": "A001" }
    }
  ]
}

Batch Users

POST /api/v1/users/batch

{
  "users": [
    {
      "user_id": "u_123",
      "name": "Nguyễn Văn A",
      "email": "user1@example.com",
      "phone": "+84901234567"
    },
    {
      "user_id": "u_124",
      "name": "Trần Thị B",
      "email": "user2@example.com",
      "phone": "+84901234568",
      "push_token": "fcm_token_xyz789",
      "push_platform": "ios"
    }
  ]
}

Note: You can include channel data (email, phone, push_token, etc.) in batch requests. Channel data can also be set separately using the channel_data endpoint.

Webhooks

Receive notifications about delivery status via webhooks.

Setup Webhook

Configure webhook endpoint to receive notifications.

POST /api/v1/webhooks

{
  "url": "https://your-app.com/webhooks/notiboost",
  "events": ["message.sent", "message.delivered", "message.failed"],
  "secret": "your_webhook_secret"
}

Webhook Security

Verify webhook signatures to ensure requests come from NotiBoost.

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Webhook Events

• message.sent - Message has been sent
• message.delivered - Message has been delivered successfully
• message.failed - Message delivery failed
• message.retried - Message is being retried

Webhook Payload

{
  "event": "message.delivered",
  "trace_id": "trc_abc123",
  "message_id": "msg_xyz789",
  "channel": "zns",
  "delivered_at": "2025-12-01T10:00:05Z",
  "status": "success"
}

Error Handling

NotiBoost API returns standard HTTP status codes.

Error Codes

Rate Limits

API has rate limits to ensure stability:

• 1000 requests per minute per API key
• Burst limit: 100 requests per second
• Exceeding rate limit returns 429 status code

Rate Limit Headers

Response headers contain rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List API endpoints support pagination.

Query Parameters

GET /api/v1/users?page=1&per_page=50

Response Format

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Idempotency

Use Idempotency-Key header to ensure requests are not duplicated.

POST /api/v1/events
Idempotency-Key: unique-key-12345

NotiBoost will return the same result if the same idempotency key is used within 24 hours.

Examples

Code examples for integrating NotiBoost.

cURL Example

curl -X POST https://api.notiboost.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "order_created",
    "event_id": "evt_001",
    "occurred_at": "2025-12-01T10:00:00Z",
    "user_id": "u_123",
    "properties": {
      "order_id": "A001",
      "amount": 350000
      }
  }'