Text Message

Description

Message providers in FlexBase expose a unified interface (IFlexTextMessageProvider) for sending SMS and notifications across providers like Twilio, Firebase, and AWS SNS.

Your application code should depend on IFlexTextMessageProvider.

Important concepts

• IFlexTextMessageProvider is the contract: send via SendSmsAsync(...), SendPushAsync(...), or SendAsync(...).

• Provider bridge: generated infrastructure commonly registers IFlexTextMessageProviderBridge (which also implements IFlexTextMessageProvider) so behavior can be overridden safely.

• Channel support is provider-specific: use SupportedChannels / SupportsChannel(...) to validate capability.

Configuration in DI

Only register the provider—Flex auto-wires generated PostBus handlers/plugins that consume the interface.

public static class OtherApplicationServicesConfig
{
	public static IServiceCollection AddOtherApplicationServices(
		this IServiceCollection services,
		IConfiguration configuration)
	{
		// Pick ONE (or register multiple with different compositions).
		services.AddFlexConsoleMessageProvider(configuration);
		// services.AddFlexTwilioMessageProvider(configuration);
		// services.AddFlexFirebaseMessageProvider(configuration);
		// services.AddFlexAwsSnsMessageProvider(configuration);
		return services;
	}
}

appsettings.json

Message provider configuration is read from FlexBase:Providers:Message:<Provider>.

{
    "FlexBase": {
	"Providers": {
	  "Message": {
		"Console": {
		  "DefaultChannel": "Sms",
		  "DefaultSenderId": "MYAPP",
		  "SimulateDelay": true,
		  "SimulatedDelay": "00:00:00.500"
		},
		"Twilio": {
		  "AccountSid": "<store-in-secrets>",
		  "AuthToken": "<store-in-secrets>",
		  "DefaultFromNumber": "[phone]",
		  "MessagingServiceSid": null,
		  "MaxRetries": 3,
		  "Timeout": "00:00:30"
		},
		"Firebase": {
		  "ProjectId": "<your-project-id>",
		  "CredentialsJsonPath": null,
		  "CredentialsJson": null,
		  "DefaultTopic": null,
		  "MaxRetries": 3,
		  "Timeout": "00:00:30"
		},
		"AwsSns": {
		  "AccessKeyId": "<store-in-secrets>",
		  "SecretAccessKey": "<store-in-secrets>",
		  "Region": "us-east-1",
		  "DefaultSenderId": "MYAPP",
		  "DefaultTopicArn": null,
		  "SmsType": "Transactional",
		  "MaxRetries": 3,
		  "Timeout": "00:00:30"
		}
	  }
	}
    }
}

Examples (template-based)

This mirrors the generated PostBus handler template shape. You do not register the handler manually.

using Microsoft.Extensions.Logging;
using Sumeru.Flex;
using System.Threading.Tasks;

namespace {YourApplication}.PostBusHandlers.Message;

public partial class SendSmsHandler : ISendSmsHandler
{
	protected string EventCondition = string.Empty;

	protected readonly ILogger<SendSmsHandler> _logger;
	protected readonly IFlexHost _flexHost;
	protected readonly IFlexTextMessageProvider _messageProvider;

	protected FlexAppContextBridge? _flexAppContext;

	public SendSmsHandler(
		ILogger<SendSmsHandler> logger,
		IFlexHost flexHost,
		IFlexTextMessageProvider messageProvider)
	{
		_logger = logger;
		_flexHost = flexHost;
		_messageProvider = messageProvider;
	}

	public virtual async Task Execute(SendSmsCommand cmd, IFlexServiceBusContext serviceBusContext)
	{
		_flexAppContext = cmd.Dto.GetAppContext();  //do not remove this line

		var result = await _messageProvider.SendSmsAsync(
			phoneNumber: cmd.Dto.PhoneNumber,
			content: cmd.Dto.Content,
			senderId: cmd.Dto.SenderId);

		cmd.Dto.MessageId = result.MessageId;
		cmd.Dto.IsSuccess = result.IsSuccess;

		await this.Fire(EventCondition, serviceBusContext);
	}
}

Provider considerations

• Validate channel support via SupportsChannel(...) before sending.

• Keep secrets (Twilio/AuthToken, AWS keys, Firebase credentials) out of source control. ["action"] = "verify", ["userId"] = 12345 }, Metadata = new Dictionary<string, string> // Tracking metadata { ["campaign"] = "signup", ["source"] = "web" } };

  var result = await _messageProvider.SendAsync(message); }

### Templated Messages

```csharp
public async Task SendTemplatedSmsAsync(string phoneNumber, string userName)
{
    await _messageProvider.SendTemplatedAsync(
        recipient: phoneNumber,
        templateId: "order_shipped",
        templateVariables: new Dictionary<string, string>
        {
            ["userName"] = userName,
            ["orderNumber"] = "ORD-12345",
            ["carrier"] = "FedEx",
            ["trackingUrl"] = "https://track.example.com/123"
        },
        channel: FlexMessageChannel.Sms
    );
}

Bulk Messaging

// Send same message to multiple recipients
public async Task SendBulkSmsAsync(List<string> phoneNumbers, string message)
{
    var result = await _messageProvider.SendToManyAsync(
        recipients: phoneNumbers,
        content: message,
        channel: FlexMessageChannel.Sms
    );

    _logger.LogInformation(
        "Sent SMS to {SuccessCount}/{TotalCount} recipients",
        result.SuccessCount,
        result.TotalCount
    );

    // Log failures
    foreach (var failure in result.Results.Where(r => !r.IsSuccess))
    {
        _logger.LogWarning(
            "Failed to send to {Recipient}: {Error}",
            failure.Recipient,
            failure.ErrorMessage
        );
    }
}

// Send different messages
public async Task SendPersonalizedMessagesAsync(List<User> users)
{
    var messages = users.Select(user => new FlexMessage
    {
        Recipients = new List<string> { user.PhoneNumber },
        Content = $"Hello {user.Name}, your order is ready!",
        Channel = FlexMessageChannel.Sms
    });

    var result = await _messageProvider.SendBulkAsync(messages);
}

Slack/Teams Integration

// Slack message
public async Task SendSlackNotificationAsync(string channel, string message)
{
    var slackMessage = new FlexMessage
    {
        Recipients = new List<string> { channel },  // "#general" or "U1234567890"
        Content = "Deployment to production completed successfully! ✅",
        Channel = FlexMessageChannel.Slack,
        Data = new Dictionary<string, object>
        {
            ["blocks"] = new[]
            {
                new { type = "header", text = new { type = "plain_text", text = "Deployment Complete" } },
                new { type = "section", text = new { type = "mrkdwn", text = "*Version:* 1.2.3\n*Environment:* Production" } }
            }
        }
    };

    await _messageProvider.SendAsync(slackMessage);
}

// Teams message
public async Task SendTeamsNotificationAsync(string channelId, string message)
{
    var teamsMessage = new FlexMessage
    {
        Recipients = new List<string> { channelId },
        Title = "Build Failed",
        Content = "The build for branch `main` has failed.",
        Channel = FlexMessageChannel.Teams,
        Priority = FlexMessagePriority.Urgent
    };

    await _messageProvider.SendAsync(teamsMessage);
}

Key Points to Consider

Best Practices

1. Validate Recipients - Use ValidateRecipient() before sending

2. Handle Delivery Status - Check IsSuccess and log failures

3. Use Console in Dev - Avoid sending real messages during development

4. Set Priorities - Use High priority for time-sensitive messages

5. Include Expiry - Set ExpiresAt for time-sensitive content

6. Handle Rate Limits - Implement retry logic for RATE_LIMITED errors

7. Monitor Costs - Track Cost in results for paid providers

Validation

public async Task<bool> SendIfValidAsync(string phoneNumber, string message)
{
    if (!_messageProvider.ValidateRecipient(phoneNumber, FlexMessageChannel.Sms))
    {
        _logger.LogWarning("Invalid phone number: {PhoneNumber}", phoneNumber);
        return false;
    }

    var result = await _messageProvider.SendSmsAsync(phoneNumber, message);
    return result.IsSuccess;
}

// Check channel support
public async Task SendToSupportedChannelAsync(string recipient, string message)
{
    if (_messageProvider.SupportsChannel(FlexMessageChannel.WhatsApp))
    {
        await _messageProvider.SendAsync(recipient, message, FlexMessageChannel.WhatsApp);
    }
    else
    {
        // Fallback to SMS
        await _messageProvider.SendSmsAsync(recipient, message);
    }
}

Error Handling

public async Task<bool> SendWithRetryAsync(FlexMessage message, int maxRetries = 3)
{
    for (int attempt = 1; attempt <= maxRetries; attempt++)
    {
        try
        {
            var result = await _messageProvider.SendAsync(message);
            
            if (result.IsSuccess)
            {
                return true;
            }

            switch (result.ErrorCode)
            {
                case "INVALID_RECIPIENT":
                    _logger.LogError("Invalid recipient, not retrying");
                    return false;
                
                case "RATE_LIMITED":
                    _logger.LogWarning("Rate limited, waiting before retry");
                    await Task.Delay(TimeSpan.FromSeconds(5 * attempt));
                    break;
                
                case "INSUFFICIENT_FUNDS":
                    _logger.LogError("Insufficient account balance");
                    return false;
                
                default:
                    _logger.LogWarning(
                        "Send failed (attempt {Attempt}/{Max}): {Error}",
                        attempt, maxRetries, result.ErrorMessage
                    );
                    break;
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unexpected error sending message");
            
            if (attempt == maxRetries)
                throw;
            
            await Task.Delay(TimeSpan.FromSeconds(2 * attempt));
        }
    }

    return false;
}

Testing Connection

// In startup/health check
public async Task<bool> VerifyMessageServiceAsync()
{
    var isConnected = await _messageProvider.TestConnectionAsync();
    
    if (!isConnected)
    {
        _logger.LogError("Message provider is not configured correctly");
        return false;
    }

    _logger.LogInformation(
        "Message provider connected: {Provider}, Channels: {Channels}",
        _messageProvider.ProviderName,
        string.Join(", ", _messageProvider.SupportedChannels)
    );
    
    return true;
}

Examples

Complete Notification Service

public class NotificationService : INotificationService
{
    private readonly IFlexTextMessageProvider _messageProvider;
    private readonly ILogger<NotificationService> _logger;

    public NotificationService(
        IFlexTextMessageProvider messageProvider,
        ILogger<NotificationService> logger)
    {
        _messageProvider = messageProvider;
        _logger = logger;
    }

    public async Task<bool> SendVerificationCodeAsync(
        string phoneNumber,
        string code)
    {
        try
        {
            var result = await _messageProvider.SendSmsAsync(
                phoneNumber: phoneNumber,
                content: $"Your verification code is: {code}. Valid for 10 minutes.",
                senderId: "MYAPP"
            );

            if (result.IsSuccess)
            {
                _logger.LogInformation(
                    "Verification code sent to {PhoneNumber} (MessageId: {MessageId})",
                    phoneNumber, result.MessageId
                );
                return true;
            }

            _logger.LogError(
                "Failed to send verification code to {PhoneNumber}: {Error}",
                phoneNumber, result.ErrorMessage
            );
            return false;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error sending verification code to {PhoneNumber}", phoneNumber);
            return false;
        }
    }

    public async Task SendOrderNotificationAsync(Order order)
    {
        var message = $"Your order #{order.Id} has been confirmed. Total: ${order.Total:F2}";

        // Send SMS if phone number available
        if (!string.IsNullOrEmpty(order.User.PhoneNumber))
        {
            await _messageProvider.SendSmsAsync(order.User.PhoneNumber, message);
        }

        // Send push notification if device token available
        if (!string.IsNullOrEmpty(order.User.DeviceToken))
        {
            await _messageProvider.SendPushAsync(
                order.User.DeviceToken,
                "Order Confirmed",
                message,
                new Dictionary<string, object>
                {
                    ["orderId"] = order.Id,
                    ["action"] = "view_order"
                }
            );
        }
    }
}

Multi-Channel Alert System

public class AlertService
{
    private readonly IFlexTextMessageProvider _messageProvider;

	public AlertService(IFlexTextMessageProvider messageProvider)
		=> _messageProvider = messageProvider;

    public async Task SendCriticalAlertAsync(string title, string message)
    {
        var tasks = new List<Task>();

        // SMS to on-call engineers
        tasks.Add(_messageProvider.SendToManyAsync(
            GetOnCallPhoneNumbers(),
            $"[CRITICAL] {title}: {message}",
            FlexMessageChannel.Sms
        ));

        // Slack notification
        tasks.Add(_messageProvider.SendAsync(
            "#alerts",
            $"🚨 *{title}*\n{message}",
            FlexMessageChannel.Slack
        ));

        // Teams notification
        tasks.Add(_messageProvider.SendAsync(
            GetTeamsChannelId(),
            message,
            FlexMessageChannel.Teams
        ));

        await Task.WhenAll(tasks);
    }
}

Testing

public class MessageServiceTests
{
    [Fact]
    public async Task SendSmsAsync_WithValidNumber_Succeeds()
    {
        // Arrange
        var provider = new FlexConsoleTextMessageProvider(
            Options.Create(new FlexConsoleMessageOptions())
        );

        // Act
        var result = await provider.SendSmsAsync(
            "[phone]",
            "Test message"
        );

        // Assert
        Assert.True(result.IsSuccess);
        Assert.NotNull(result.MessageId);
    }

    [Fact]
    public void ValidateRecipient_WithInvalidNumber_ReturnsFalse()
    {
        // Arrange
        var provider = new FlexConsoleTextMessageProvider(
            Options.Create(new FlexConsoleMessageOptions())
        );

        // Act
        var isValid = provider.ValidateRecipient("invalid", FlexMessageChannel.Sms);

        // Assert
        Assert.False(isValid);
    }
}

See Also

• Email Providers - Email sending

• FlexMessage Provider Reference - Detailed API documentation