Channel Documentation

Detailed documentation for each notification channel.

ZNS (Zalo Notification Service)

ZNS is NotiBoost's primary notification channel, optimized for the Vietnamese market.

Setup ZNS

Follow these steps to set up ZNS channel:

1. Register ZNS account with Zalo
2. Get ZNS API credentials
3. Configure ZNS in NotiBoost dashboard
4. Test with approved template

API Configuration

Configure ZNS channel via API:

PUT /api/v1/channels/zns
{
  "api_key": "your_zns_api_key",
  "oa_id": "your_oa_id",
  "secret_key": "your_secret_key"
}

Template Management

Create ZNS templates with approved content:

POST /api/v1/templates
{
  "name": "order_confirmation",
  "channel": "zns",
  "content": {
    "header": "Xác nhận đơn hàng",
    "body": "Đơn hàng {{order_id}} đã được xác nhận.\nTổng tiền: {{amount}} VNĐ",
    "footer": "Cảm ơn bạn đã mua sắm",
    "buttons": [
      {
        "type": "ZALO_OPEN",
        "text": "Xem chi tiết",
        "url": "https://your-app.com/orders/{{order_id}}"
      }
    ]
  },
  "variables": ["order_id", "amount"]
}

Note: Templates must be approved by Zalo before use. Approval typically takes 1-3 business days.

ZNS Constraints

• Templates must be approved by Zalo first
• Quota limited by package
• Message format must comply with ZNS spec
• User must be subscribed to your Zalo OA
• Rate limits apply based on package tier

Quota Management

NotiBoost automatically manages ZNS quota and alerts when running low.

• Quota is tracked per day/month based on your ZNS package
• Automatic alerts when quota reaches 80%
• Fallback to Email/SMS when quota exhausted

Error Handling

Common ZNS errors and how to handle them:

Email

Email messaging for customer support and notifications.

Setup Email

Configure email provider and messaging permissions.

SMTP Configuration

Configure email using SMTP:

PUT /api/v1/channels/email
{
  "provider": "smtp",
  "host": "smtp.gmail.com",
  "port": 587,
  "username": "your_email@gmail.com",
  "password": "your_app_password",
  "encryption": "tls",
  "from_name": "Your Company",
  "from_email": "noreply@yourcompany.com"
}

API Provider Configuration

Configure email using API providers (SendGrid, Mailgun, etc.):

PUT /api/v1/channels/email
{
  "provider": "sendgrid",
  "api_key": "your_sendgrid_api_key",
  "from_name": "Your Company",
  "from_email": "noreply@yourcompany.com"
}

Email Templates

Create HTML and text email templates:

POST /api/v1/templates
{
  "name": "order_confirmation_email",
  "channel": "email",
  "subject": "Xác nhận đơn hàng #{{order_id}}",
  "content": {
    "html": "
Đơn hàng #{{order_id}}
Tổng tiền: {{amount}} VNĐ
",
    "text": "Đơn hàng #{{order_id}}\nTổng tiền: {{amount}} VNĐ"
  },
  "variables": ["order_id", "amount"]
}

Email Limits

• Max 10MB per email (including attachments)
• Rate limits vary by provider
• Bounce rate monitoring and blacklist prevention

App Push Notifications

Mobile push notifications for iOS and Android apps.

Setup App Push

Configure FCM (Firebase Cloud Messaging) or APNS (Apple Push Notification Service).

Firebase Cloud Messaging (FCM)

Configure FCM for Android and iOS:

PUT /api/v1/channels/push
{
  "provider": "fcm",
  "server_key": "your_fcm_server_key",
  "project_id": "your_firebase_project_id"
}

Apple Push Notification Service (APNS)

Configure APNS for iOS apps:

PUT /api/v1/channels/push
{
  "provider": "apns",
  "bundle_id": "com.yourapp.bundle",
  "key_id": "your_apns_key_id",
  "team_id": "your_apple_team_id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "environment": "production"
}

Token Management

Register push tokens for users:

PUT /api/v1/users/{user_id}/channel_data
{
  "push_token": "fcm_token_abc123",
  "push_platform": "android"
}

Push Payload Structure

Create push notification templates:

POST /api/v1/templates
{
  "name": "order_push",
  "channel": "push",
  "content": {
    "title": "Đơn hàng mới",
    "body": "Đơn hàng #{{order_id}} đã được xác nhận",
    "data": {
      "order_id": "{{order_id}}",
      "type": "order_confirmation"
    }
  },
  "variables": ["order_id"]
}

SMS

SMS channel primarily used as fallback when ZNS or Email fails.

Setup SMS

Configure SMS provider (Twilio, Nexmo, etc.):

PUT /api/v1/channels/sms
{
  "provider": "twilio",
  "account_sid": "your_account_sid",
  "auth_token": "your_auth_token",
  "from_number": "+84901234567"
}

SMS Fallback

SMS is automatically used when primary channels fail.

POST /api/v1/flows
{
  "name": "critical_notification",
  "channels": ["zns", "email"],
  "fallback": "sms",
  "fallback_conditions": {
    "zns_failed": true,
    "email_failed": true
  }
}

SMS Limits

• 160 characters per SMS (GSM-7 encoding)
• 70 characters per SMS (Unicode)
• Long messages automatically split into multiple SMS

SMS Cost

SMS is typically the most expensive channel. Use as fallback only for critical notifications.

Quota Management

NotiBoost manages quota for all channels:

• Real-time quota tracking
• Automatic fallback when quota exhausted
• Alerts when quota running low

Quota API

Check quota status via API:

GET /api/v1/channels/{channel}/quota

Response:
{
  "channel": "zns",
  "total": 10000,
  "used": 7500,
  "remaining": 2500,
  "percentage_used": 75,
  "alert_threshold": 80
}

Best Practices

• Prioritize ZNS for transactional notifications
• Use SMS only when necessary (higher cost)
• Monitor quota usage regularly
• Set up fallback chains for critical notifications
• Test all channels before production use

Troubleshooting

Common issues and solutions:

Messages not being delivered

Check channel configuration, user channel data, and quota status. Review delivery logs in Observability dashboard.

High bounce/failure rates

Verify user contact information is correct and up-to-date. Check channel provider status and rate limits.

Quota exhausted unexpectedly

Review flow configurations to ensure fallback chains are working. Check for duplicate sends or retry loops.