All bts-soft packages
npm install @bts-soft/notifications@bts-soft/notifications package provides a flexible and extensible notification system that allows sending messages through various channels including Email, SMS, WhatsApp, Telegram, Discord, Microsoft Teams, Facebook Messenger, and Firebase Cloud Messaging (FCM). The system uses a queue-based architecture with BullMQ for reliable message delivery.
bash
npm install @bts-soft/notifications
`
---
Dependencies
The package requires the following peer dependencies:
`bash
npm install bullmq @nestjs/bullmq nodemailer twilio firebase-admin axios node-telegram-bot-api
`
---
Quick Start
$3
`typescript
import { Module } from '@nestjs/common';
import { NotificationModule } from '@bts-soft/notifications';
@Module({
imports: [NotificationModule],
})
export class AppModule {}
`
---
$3
`env
Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
Email Configuration (Nodemailer)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_SENDER=no-reply@yourdomain.com
SMS/WhatsApp Configuration (Twilio)
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_SMS_NUMBER=+1234567890
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886
Telegram Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
ENABLE_TELEGRAM_BOT=true
Discord Configuration
DISCORD_WEBHOOK_URL=your_discord_webhook_url
Microsoft Teams Configuration
TEAMS_WEBHOOK_URL=your_teams_webhook_url
Facebook Messenger Configuration
FB_PAGE_ACCESS_TOKEN=your_page_access_token
Firebase Configuration
FIREBASE_SERVICE_ACCOUNT_PATH=./path/to/serviceAccountKey.json
`
---
$3
`typescript
import { Injectable } from '@nestjs/common';
import { NotificationService, ChannelType } from '@bts-soft/notifications';
@Injectable()
export class UserService {
constructor(private notificationService: NotificationService) {}
async sendWelcomeNotification(userEmail: string, userName: string) {
// Send email
await this.notificationService.send(ChannelType.EMAIL, {
recipientId: userEmail,
subject: 'Welcome to Our Platform',
body: Hello ${userName}, welcome to our platform!,
});
// Send SMS
await this.notificationService.send(ChannelType.SMS, {
recipientId: '+1234567890',
body: Welcome ${userName}! Your account has been created.,
});
}
}
`
---
Core Components
$3
The main service for queuing notification jobs:
`typescript
export class NotificationService {
async send(channel: ChannelType, message: NotificationMessage): Promise
}
`
$3
BullMQ worker that processes queued notifications and routes them to the appropriate channels.
$3
Factory class that creates channel instances based on configuration.
Channel-Specific Usage
$3
`typescript
await notificationService.send(ChannelType.EMAIL, {
recipientId: 'user@example.com',
subject: 'Test Email',
body: 'This is a test email message.',
channelOptions: {
html: 'Test Email
This is a test email message.
'
}
});
`
$3
`typescript
await notificationService.send(ChannelType.SMS, {
recipientId: '+201234567890',
body: 'Your verification code is 123456',
});
`
$3
`typescript
await notificationService.send(ChannelType.WHATSAPP, {
recipientId: '+201234567890',
body: 'Hello! This is a WhatsApp test message.',
});
`
$3
`typescript
await notificationService.send(ChannelType.TELEGRAM, {
recipientId: 'TELEGRAM_CHAT_ID',
body: 'Hello from Telegram bot!',
});
`
$3
`typescript
await notificationService.send(ChannelType.DISCORD, {
body: 'System Alert: Deployment completed successfully!',
channelOptions: {
username: 'Notification Bot',
avatar_url: 'https://example.com/avatar.png',
},
});
`
$3
`typescript
await notificationService.send(ChannelType.TEAMS, {
body: 'System Alert: Server CPU usage exceeded 90%',
});
`
$3
`typescript
await notificationService.send(ChannelType.FIREBASE_FCM, {
recipientId: 'DEVICE_FCM_TOKEN',
title: 'Welcome',
body: 'Thank you for joining our app!',
channelOptions: {
data: { userId: '12345' },
},
});
`
Message Structure
All channels use the unified NotificationMessage interface:
`typescript
interface NotificationMessage {
recipientId: string; // Channel-specific recipient identifier
body: string; // Main message content
title?: string; // Optional title (FCM, etc.)
subject?: string; // Email subject
channelOptions?: any; // Channel-specific options
}
`
---
Error Handling
The system includes comprehensive error handling:
- Failed jobs are automatically retried with exponential backoff
- Detailed logging for debugging and monitoring
- Configuration validation at startup
- Graceful error propagation
---
Queue Configuration
Notifications are processed through a BullMQ queue with the following settings:
- Queue Name: send-notification
- Retry Attempts: 3
- Backoff Strategy: Exponential with 5-second delay
- Redis: Required for queue persistence
---
Advanced Configuration
$3
You can provide custom configuration for each channel through the factory:
`typescript
const customApiKeys = {
email: {
service: 'gmail',
user: 'custom@gmail.com',
pass: 'custom-password',
sender: 'no-reply@custom.com'
},
// ... other channel configurations
};
`
$3
For Telegram integration, set up the webhook:
`bash
curl "https://api.telegram.org/bot/setWebhook?url=/telegram/webhook"
`
---
License
This package is part of the @bts-soft` ecosystem. All rights reserved © BTS Soft.