Acontplus.Notifications 1.6.0

Acontplus.Notifications

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

v1.6.0 — 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

v1.5.0 — Email Performance & Caching

• ⚡ Template Caching — 50× faster template loading (30-min memory cache, sliding expiration)
• 📊 99% less I/O — cached templates eliminate repeated disk reads
• 🔄 Backward compatible — optional IMemoryCache injection

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.0" />

⚡ 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);