👁 Image
Acontplus.Notifications 1.6.5

Acontplus.Notifications

👁 NuGet
👁 .NET
👁 License: MIT

Production-ready multi-channel notification library for .NET 10. Covers email (MailKit SMTP + Amazon SES) and WhatsApp Cloud API (Meta Graph API v23.0) in a single package — templating, media, interactive messages, multi-tenant credentials, resilience, and webhook validation included.

🚀 Features

WhatsApp Cloud API (Meta Graph API v23.0)

• 💬 Text messages — plain text with URL preview, in-thread replies
• 📋 Templates — body/header params, image/video/document headers, quick-reply & URL buttons
• 🖼️ Media — image, document, audio, video, sticker (URL or pre-uploaded ID)
• 📍 Location — map pin with name and address
• 🔘 Interactive — quick-reply buttons, scrollable list menu, CTA URL button
• 👍 Reactions — send/remove emoji reactions on received messages
• ✅ Read receipts — mark messages as read (double blue ticks)
• 📤 Media upload — upload files once, reuse the ID in multiple messages
• 🔐 Webhook validation — HMAC-SHA256 signature verification (X-Hub-Signature-256)
• 🏢 Multi-tenant — default account + named accounts per company + per-request inline override
• 🔄 Built-in resilience — 3 retries, exponential back-off, circuit breaker, per-attempt timeout

Core Email Capabilities

• 📧 Email via MailKit (SMTP) and Amazon SES (HTTP v2)
• 🎨 Scriban templating with logo embedding and variable interpolation
• 🔄 Retry logic with Polly (exponential back-off, jitter)
• 🚦 Rate limiting (SES: 14 emails/sec default; SMTP: auth throttling)
• 🏊 SMTP connection pooling (configurable pool size)
• 📦 Bulk sending with batching (SES: 50 recipients/batch)
• 🧵 Thread-safe concurrent operations
• 📨 Attachments (PDF, images, documents)

📦 Installation

dotnet add package Acontplus.Notifications

<PackageReference Include="Acontplus.Notifications" Version="1.6.2" />

⚡ WhatsApp Cloud API (v1.6.0)

1. Register the service

// Program.cs
builder.Services.AddWhatsAppService(builder.Configuration);
// or inline:
builder.Services.AddWhatsAppService(opts =>
{
 opts.PhoneNumberId = "1234567890";
 opts.AccessToken = "EAAxxxx...";
 opts.ApiVersion = "v23.0";
 opts.DefaultCountryCode = "593"; // 09xxxxxxxx → 593 9xxxxxxxx
});

2. appsettings.json

{
 "WhatsApp": {
 // REQUIRED (when using server-stored credentials)
 "PhoneNumberId": "YOUR_PHONE_NUMBER_ID",
 "AccessToken": "YOUR_PERMANENT_SYSTEM_USER_TOKEN",

 // OPTIONAL — defaults shown
 "ApiVersion": "v23.0",
 "TimeoutSeconds": 30,

 // OPTIONAL — auto-prefix numbers starting with "0" (e.g. 09xxxxxxxx → 5939xxxxxxxx)
 "DefaultCountryCode": "593",

 // OPTIONAL — only needed if you call ValidateWebhookSignature()
 "AppSecret": "YOUR_APP_SECRET_FOR_WEBHOOK_VALIDATION",

 // OPTIONAL — only needed if you handle Meta's GET webhook verify handshake
 "WebhookVerifyToken": "YOUR_WEBHOOK_VERIFY_TOKEN",

 // OPTIONAL — multi-tenant: named accounts override the default credentials above
 "Accounts": {
 "company-a": {
 "PhoneNumberId": "COMPANY_A_PHONE_ID",
 "AccessToken": "COMPANY_A_TOKEN"
 }
 }
 }
}

Per-request credentials: If your callers supply AccessToken / PhoneNumberId on every request (e.g. credentials come from the frontend), you can omit PhoneNumberId and AccessToken entirely from appsettings and only keep TimeoutSeconds.

Obtain credentials: Meta Business Manager → WhatsApp → API Setup. Use a permanent system-user token (never expires) instead of a temporary one.

3. Inject and send

public class NotificationService(IWhatsAppService whatsApp)
{
 // Text message (requires 24-hour conversation window)
 public Task<WhatsAppResult> SendTextAsync(string to, string body) =>
 whatsApp.SendTextAsync(new() { To = to, Body = body });

 // Template (works any time — no 24-hour window needed)
 public Task<WhatsAppResult> SendInvoiceAsync(string to, string mediaId, string customerName, string invoiceNumber) =>
 whatsApp.SendTemplateAsync(new()
 {
 To = to,
 TemplateName = "notificacion_documento",
 LanguageCode = "es_EC",
 Components =
 [
 WhatsAppTemplateComponent.HeaderDocument(mediaId, "factura.pdf", isId: true),
 WhatsAppTemplateComponent.Body(customerName, invoiceNumber)
 ]
 });

 // Upload a file once → reuse the ID
 public async Task<string?> UploadInvoiceAsync(Stream pdfStream) =>
 await whatsApp.UploadMediaAsync(new()
 {
 FileStream = pdfStream,
 FileName = "invoice.pdf",
 ContentType = "application/pdf"
 });

 // Interactive quick-reply buttons
 public Task<WhatsAppResult> SendConfirmationAsync(string to) =>
 whatsApp.SendInteractiveAsync(new()
 {
 To = to,
 InteractiveType = WhatsAppInteractiveType.Button,
 BodyText = "Do you confirm your appointment?",
 ReplyButtons =
 [
 new WhatsAppReplyButton { Id = "yes", Title = "Yes, confirm" },
 new WhatsAppReplyButton { Id = "no", Title = "No, cancel" }
 ]
 });

 // Multi-tenant: named account
 public Task<WhatsAppResult> SendForCompanyAsync(string to, string message) =>
 whatsApp.SendTextAsync(new()
 {
 To = to,
 Body = message,
 Credentials = WhatsAppCredentials.FromAccount("company-a")
 });
}

4. Webhook validation

app.MapPost("/webhook/whatsapp", async (
 HttpRequest req,
 IWhatsAppService whatsApp) =>
{
 var signature = req.Headers["X-Hub-Signature-256"].ToString();
 var body = await new StreamReader(req.Body).ReadToEndAsync();

 if (!whatsApp.ValidateWebhookSignature(signature, body))
 return Results.Unauthorized();

 // process payload ...
 return Results.Ok();
});

// Webhook verification handshake (GET)
app.MapGet("/webhook/whatsapp", (
 [FromQuery(Name = "hub.mode")] string mode,
 [FromQuery(Name = "hub.verify_token")] string token,
 [FromQuery(Name = "hub.challenge")] string challenge,
 IConfiguration config) =>
{
 var expected = config["WhatsApp:WebhookVerifyToken"];
 return mode == "subscribe" && token == expected
 ? Results.Ok(int.Parse(challenge))
 : Results.Unauthorized();
});

Supported message types

Multi-tenant credential resolution order

1. Named account — WhatsAppCredentials.FromAccount("name") → looks up WhatsApp:Accounts:name
2. Inline override — WhatsAppCredentials.Inline(phoneId, token)
3. Default — top-level WhatsApp:PhoneNumberId + WhatsApp:AccessToken

📧 Email (MailKit / Amazon SES)

Quick Start

// Program.cs
builder.Services.AddMemoryCache(); // enables template caching
builder.Services.AddSingleton<IMailKitService, AmazonSesService>(); // or MailKitService

appsettings.json

{
 "AWS": {
 "SES": {
 "Region": "us-east-1",
 "DefaultFromEmail": "noreply@example.com",
 "MaxSendRate": 14,
 "BatchSize": 50,
 "BatchDelayMs": 100,
 "AccessKey": "AKIA...",
 "SecretKey": "your-secret-key"
 }
 },
 "Templates": { "Path": "Templates" },
 "Media": { "ImagesPath": "wwwroot/images" }
}

Send an email

var success = await emailService.SendAsync(new EmailModel
{
 SenderEmail = "noreply@example.com",
 RecipientEmail = "user@example.com",
 Subject = "Welcome!",
 Template = "welcome.html", // cached 30 min
 Body = JsonSerializer.Serialize(new { UserName = "John" }),
 IsHtml = false
});

Bulk sending

var emails = recipients.Select(r => new EmailModel { ... }).ToList();
await emailService.SendBulkAsync(emails, ct); // auto-batched, rate-limited

⚙️ Configuration Reference

WhatsApp settings

¹ Conditional — required when using server-stored default credentials. Omit when all callers supply credentials per-request via WhatsAppCredentials (e.g. credentials come from the frontend). In that case only TimeoutSeconds is meaningful.

² Only needed if you call ValidateWebhookSignature().

³ Only needed if you handle Meta's GET webhook verify handshake endpoint.

Amazon SES settings

MailKit SMTP settings

🚀 Performance

WhatsApp resilience (v1.6.0)

Email template caching (v1.5.0+)

📚 API Reference

IWhatsAppService

Task<WhatsAppResult> SendTextAsync(SendWhatsAppTextRequest, CancellationToken);
Task<WhatsAppResult> SendTemplateAsync(SendWhatsAppTemplateRequest, CancellationToken);
Task<WhatsAppResult> SendMediaAsync(SendWhatsAppMediaRequest, CancellationToken);
Task<WhatsAppResult> SendLocationAsync(SendWhatsAppLocationRequest, CancellationToken);
Task<WhatsAppResult> SendInteractiveAsync(SendWhatsAppInteractiveRequest, CancellationToken);
Task<WhatsAppResult> SendReactionAsync(SendWhatsAppReactionRequest, CancellationToken);
Task<bool> MarkAsReadAsync(string messageId, WhatsAppCredentials?, CancellationToken);
Task<string?> UploadMediaAsync(WhatsAppMediaUpload, WhatsAppCredentials?, CancellationToken);
bool ValidateWebhookSignature(string xHubSignature256, string rawBody, string? appSecret);

IMailKitService

Task<bool> SendAsync(EmailModel email, CancellationToken ct);
Task<bool> SendBulkAsync(IEnumerable<EmailModel> emails, CancellationToken ct);