Skip to main content

SMS Notifications

Send SMS via Twilio, AWS SNS, or Azure Communication Services.

Step 1: Install the Package​

dotnet add package PrimusSaaS.Notifications --version 2.0.0

Step 2: Configure Program.cs​

Choose your SMS provider:

Option A: Twilio​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseTwilio(builder.Configuration.GetSection("Notifications:Twilio"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Option B: AWS SNS​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseAwsSns(builder.Configuration.GetSection("Notifications:Sns"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Option C: Azure Communication Services​

using PrimusSaaS.Notifications;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusNotifications(n => n
    .UseAzureCommunicationServices(builder.Configuration.GetSection("Notifications:Azure"))
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

var app = builder.Build();

Step 3: Configure appsettings.json​

Twilio Configuration​

{
  "Notifications": {
    "Twilio": {
      "AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "AuthToken": "your-auth-token",
      "FromNumber": "+15551234567"
    }
  }
}
How to get your Twilio credentials
  1. Go to Twilio Console
  2. Copy your Account SID and Auth Token from the dashboard
  3. Get a phone number from Phone Numbers Buy a Number
  4. Use the phone number as FromNumber (E.164 format: +15551234567)

AWS SNS Configuration​

{
  "Notifications": {
    "Sns": {
      "AccessKeyId": "AKIA...",
      "SecretAccessKey": "your-secret-key",
      "Region": "us-east-1"
    }
  }
}
How to get your AWS SNS credentials
  1. Go to AWS IAM Console
  2. Create a user with AmazonSNSFullAccess policy
  3. Generate access keys for programmatic access
  4. Note: SNS SMS has spending limits - request increase if needed

Azure Communication Services Configuration​

{
  "Notifications": {
    "Azure": {
      "ConnectionString": "endpoint=https://your-resource.communication.azure.com/;accesskey=...",
      "FromNumber": "+15551234567"
    }
  }
}
How to get your Azure credentials
  1. Go to Azure Portal
  2. Create a Communication Services resource
  3. Go to Keys and copy the Connection String
  4. Get a phone number from Phone numbers Get

Step 4: Create a Template​

NotificationTemplates/OrderConfirmation/SmsBody.liquid​

Hi {{ recipient.name }}! Your order #{{ data.orderId }} has been confirmed. Track at: {{ data.trackingUrl }}

Step 5: Send an SMS​

public class OrderService
{
    private readonly INotificationService _notifications;

    public OrderService(INotificationService notifications)
    {
        _notifications = notifications;
    }

    public async Task SendOrderConfirmation(string phone, string name, string orderId, string trackingUrl)
    {
        var result = await _notifications.SendAsync("OrderConfirmation", new
        {
            recipient = new { phone, name },
            data = new { orderId, trackingUrl }
        });

        if (!result.Success)
        {
            Console.WriteLine($"SMS failed: {result.FailureReason}");
        }
    }
}

Advanced: Direct SMS (No Template)​

Send SMS without templates:

app.MapPost("/send-sms", async (INotificationService notifications) =>
{
    var result = await notifications.SendSmsAsync(
        "+15559876543",
        "Your verification code is: 123456");
    
    return result.Success ? Results.Ok() : Results.Problem(result.FailureReason);
});

Advanced: Multiple Providers (Failover)​

Configure multiple SMS providers for failover:

builder.Services.AddPrimusNotifications(n => n
    .UseTwilio(builder.Configuration.GetSection("Notifications:Twilio"))
    .UseAwsSns(builder.Configuration.GetSection("Notifications:Sns")) // Fallback
    .UseFileTemplates("NotificationTemplates")
    .UseLogger());

If Twilio fails, AWS SNS will be used automatically.

Advanced: Combined Email + SMS​

Send both email and SMS in the same notification:

NotificationTemplates/PasswordReset/EmailSubject.liquid​

Reset your password

NotificationTemplates/PasswordReset/EmailBody.liquid​

<p>Click <a href="{{ data.resetLink }}">here</a> to reset your password.</p>

NotificationTemplates/PasswordReset/SmsBody.liquid​

Your password reset code is: {{ data.code }}
await _notifications.SendAsync("PasswordReset", new
{
    recipient = new { email = "user@example.com", phone = "+15559876543", name = "John" },
    data = new { resetLink = "https://...", code = "123456" }
});

Both channels will be attempted; results are reported per-channel.

Next Steps​

Want to...See Guide
Send emailsEmail Setup
Tenant-scoped notificationsMulti-Tenancy