Tham chiếu API — Notification Manager

Gửi thông báo

messages:send

Gửi thông báo qua kênh đã cấu hình.

POST /api/messages:send

Body:

Trường	Kiểu	Bắt buộc	Mô tả
channelName	string	Có	Tên kênh thông báo (đã cấu hình trong Settings)
to	string[]	Có	Danh sách người nhận (email hoặc userId tuỳ kênh)
subject	string	Không	Tiêu đề (dùng cho email)
content	string / object	Có	Nội dung thông báo

Ví dụ gửi email

await api.resource('messages').send({
  values: {
    channelName: 'default-email',
    to: ['user@example.com', 'admin@example.com'],
    subject: 'Thông báo quan trọng',
    content: '<h1>Xin chào</h1><p>Nội dung thông báo HTML...</p>',
  },
});

Ví dụ gửi in-app

await api.resource('messages').send({
  values: {
    channelName: 'in-app-message',
    to: ['userId-123', 'userId-456'],
    title: 'Đơn hàng mới',
    content: {
      text: 'Bạn có đơn hàng mới #1234',
      link: '/orders/1234',
    },
  },
});

Gửi từ server-side code

const notificationManager = this.app.pm.get(
  PluginNotificationManagerServer
) as PluginNotificationManagerServer;

await notificationManager.send({
  channelName: 'default-email',
  to: ['user@example.com'],
  subject: 'Thông báo từ server',
  content: 'Nội dung...',
});

Gửi cho nhiều user (sendToUsers)

await notificationManager.sendToUsers({
  channelName: 'in-app-message',
  userIds: [1, 2, 3],
  title: 'Thông báo chung',
  content: 'Nội dung...',
});

Quản lý kênh thông báo

Lấy danh sách kênh

const channels = await api.resource('notificationChannels').list();

Response:

{
  "data": [
    {
      "id": 1,
      "name": "default-email",
      "channelType": "email",
      "options": { "host": "smtp.gmail.com", "port": 587 },
      "enabled": true
    }
  ]
}

Tạo kênh mới

await api.resource('notificationChannels').create({
  values: {
    name: 'support-email',
    channelType: 'email',
    options: {
      host: 'smtp.gmail.com',
      port: 587,
      secure: false,
      account: 'support@company.com',
      password: 'app-password',
      from: 'Support <support@company.com>',
    },
    enabled: true,
  },
});

Cập nhật kênh

await api.resource('notificationChannels').update({
  filterByTk: channelId,
  values: {
    enabled: false,
  },
});

Xoá kênh

await api.resource('notificationChannels').destroy({
  filterByTk: channelId,
});

Xem lịch sử gửi (Send Logs)

Lấy danh sách log

const logs = await api.resource('notificationSendLogs').list({
  filter: {
    status: 'failed',
  },
  sort: ['-createdAt'],
  pageSize: 50,
});

Cấu trúc Send Log

Trường	Kiểu	Mô tả
id	bigint	ID log
channelId	bigint	ID kênh đã gửi
receiver	string	Người nhận
status	string	Trạng thái: success, failed, pending
content	json	Nội dung đã gửi
errorMessage	text	Chi tiết lỗi (nếu thất bại)
createdAt	datetime	Thời gian gửi

Đăng ký Channel Type (dành cho Plugin Developer)

Interface Channel

Một channel type cần implement interface sau:

interface NotificationChannel {
  send(options: SendOptions): Promise<void>;
}

Đăng ký vào Manager

class MyPlugin extends Plugin {
  async load() {
    const nm = this.pm.get(
      PluginNotificationManagerServer
    ) as PluginNotificationManagerServer;

    nm.registerChannelType({
      type: 'sms',
      Channel: MySMSChannel,
    });
  }
}

Mã lỗi (Error Codes)

Mã	Mô tả
CHANNEL_NOT_FOUND	Kênh với tên channelName không tồn tại
CHANNEL_DISABLED	Kênh đã bị tắt (enabled: false)
SEND_FAILED	Gửi thất bại — xem errorMessage để biết chi tiết
INVALID_RECEIVER	Người nhận không hợp lệ (email sai format, userId không tồn tại)