Tài liệu Channel

Tài liệu chi tiết cho từng notification channel.

ZNS (Zalo Notification Service)

ZNS là kênh notification chính của NotiBoost, được tối ưu cho thị trường Việt Nam.

Setup ZNS

Thực hiện các bước sau để setup ZNS channel:

  1. Đăng ký ZNS account với Zalo
  2. Lấy ZNS API credentials
  3. Cấu hình ZNS trong NotiBoost dashboard
  4. Test với template đã được approve

Cấu hình API

Cấu hình ZNS channel qua API:

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

Quản lý Template

Tạo ZNS templates với nội dung đã được phê duyệt:

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"]
}

Lưu ý: Templates phải được Zalo phê duyệt trước khi sử dụng. Thời gian phê duyệt thường là 1-3 ngày làm việc.

ZNS Constraints

  • Template phải được Zalo approve trước
  • Quota giới hạn theo package
  • Message format phải tuân thủ ZNS spec
  • User phải subscribe Zalo OA của bạn
  • Rate limits áp dụng theo package tier

Quota Management

NotiBoost tự động quản lý ZNS quota và cảnh báo khi gần hết.

  • Quota được track theo ngày/tháng dựa trên ZNS package
  • Tự động cảnh báo khi quota đạt 80%
  • Fallback sang Email/SMS khi quota hết

Xử lý Lỗi

Các lỗi ZNS phổ biến và cách xử lý:

Mã Lỗi Ý nghĩa Hành động
QUOTA_EXCEEDED ZNS quota vượt quá Nâng cấp package hoặc dùng fallback channel
TEMPLATE_NOT_APPROVED Template chưa được Zalo phê duyệt Chờ phê duyệt hoặc dùng template đã được phê duyệt
USER_NOT_SUBSCRIBED User chưa subscribe Zalo OA User phải subscribe trước hoặc dùng kênh thay thế

Email

Email messaging cho customer support và notifications.

Setup Email

Cấu hình email provider và messaging permissions.

Cấu hình SMTP

Cấu hình email sử dụng 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"
}

Cấu hình API Provider

Cấu hình email sử dụng 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

Tạo HTML và 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"]
}

Giới hạn Email

  • Tối đa 10MB mỗi email (bao gồm attachments)
  • Rate limits khác nhau theo provider
  • Theo dõi bounce rate và ngăn chặn blacklist

App Push Notifications

Mobile push notifications cho iOS và Android apps.

Setup App Push

Cấu hình FCM (Firebase Cloud Messaging) hoặc APNS (Apple Push Notification Service).

Firebase Cloud Messaging (FCM)

Cấu hình FCM cho Android và 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)

Cấu hình APNS cho 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"
}

Quản lý Token

Đăng ký push tokens cho users:

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

Cấu trúc Push Payload

Tạo 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 chủ yếu dùng làm fallback khi ZNS hoặc Email fail.

Setup SMS

Cấu hình 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 tự động được sử dụng khi primary channels fail.

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

Giới hạn SMS

  • 160 ký tự mỗi SMS (GSM-7 encoding)
  • 70 ký tự mỗi SMS (Unicode)
  • Tin nhắn dài tự động chia thành nhiều SMS

Chi phí SMS

SMS thường là kênh đắt nhất. Chỉ dùng làm fallback cho notifications quan trọng.

Quota Management

NotiBoost quản lý quota cho tất cả channels:

  • Real-time quota tracking
  • Automatic fallback khi quota hết
  • Alerts khi gần hết quota

Quota API

Kiểm tra quota status qua API:

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

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

Best Practices

  • Ưu tiên ZNS cho transactional notifications
  • Sử dụng SMS chỉ khi cần thiết (chi phí cao hơn)
  • Monitor quota usage thường xuyên
  • Thiết lập fallback chains cho notifications quan trọng
  • Test tất cả channels trước khi dùng production

Troubleshooting

Các vấn đề phổ biến và giải pháp:

Messages không được gửi

Kiểm tra channel configuration, user channel data, và quota status. Xem delivery logs trong Observability dashboard.

Tỷ lệ bounce/failure cao

Xác minh thông tin liên hệ của user là chính xác và cập nhật. Kiểm tra channel provider status và rate limits.

Quota hết bất ngờ

Rà soát flow configurations để đảm bảo fallback chains hoạt động. Kiểm tra duplicate sends hoặc retry loops.