Deveel Messaging Framework

A modern, extensible messaging framework for .NET that provides a unified abstraction layer for various messaging providers including SMS, email, WhatsApp, and push notifications. The framework offers strong type safety, comprehensive validation, and flexible connector architecture.

🚀 Motivation

Modern applications often need to send notifications through multiple channels (SMS, email, WhatsApp, push notifications, webhooks). Each provider has different APIs, authentication methods, and message formats. The Deveel Messaging Framework solves this by:

• Unified API: Single interface for all messaging providers
• Type Safety: Strongly-typed endpoints and configurations prevent runtime errors
• Extensibility: Easy to add new connectors and message types
• Validation: Built-in message and configuration validation
• Webhook Support: Comprehensive webhook handling for message receiving and status updates
• Testability: Comprehensive mocking and testing support
• Performance: Async/await throughout with efficient resource usage

📦 Core Packages

Package	Description	NuGet
Deveel.Messaging.Abstractions	Core messaging abstractions and models
Deveel.Messaging.Connector.Abstractions	Base classes and interfaces for connectors

🔌 Available Connectors

Connector	Provider	Type	Documentation	Package	Nuget
Twilio SMS	Twilio	SMS	📖 Guide	Deveel.Messaging.Connector.Twilio
Twilio WhatsApp	Twilio	WhatsApp	📖 Guide	Deveel.Messaging.Connector.Twilio
Firebase FCM	Firebase	Push	📖 Guide	Deveel.Messaging.Connector.Firebase
SendGrid Email	SendGrid	Email	📖 Guide	Deveel.Messaging.Connector.Sendgrid

📋 Complete Connector Documentation - Detailed installation, configuration, and usage guides for all connectors.

🔧 Quick Installation

Core Framework

# Install core messaging abstractions
dotnet add package Deveel.Messaging.Abstractions

# For building custom connectors
dotnet add package Deveel.Messaging.Connector.Abstractions

Connectors

Each connector has specific installation and setup instructions in its documentation:

• 📱 SMS: Twilio SMS Installation Guide
• 💬 WhatsApp: Twilio WhatsApp Installation Guide
• 🔔 Push: Firebase FCM Installation Guide
• 📧 Email: SendGrid Email Installation Guide

🏁 Quick Start

1. Choose Your Messaging Provider

Pick the connector that matches your needs from the connector documentation.

2. Basic Usage Pattern

All connectors follow the same pattern:

using Deveel.Messaging;

// 1. Define a schema
var schema = new ChannelSchema("Provider", "Type", "1.0.0")
    .WithCapabilities(ChannelCapability.SendMessages)
    .AllowsMessageEndpoint(EndpointType.EmailAddress)
    .AddContentType(MessageContentType.PlainText);

// 2. Create and configure connector
var connector = new ProviderConnector(schema);
await connector.InitializeAsync(cancellationToken);

// 3. Build and send message
var message = new MessageBuilder()
    .WithId("msg-001")
    .WithEmailSender("[email protected]")
    .WithEmailReceiver("[email protected]")
    .WithTextContent("Hello from our service!")
    .Message;

var result = await connector.SendMessageAsync(message, cancellationToken);
if (result.IsSuccess)
{
    Console.WriteLine($"Message sent: {result.Value?.MessageId}");
}

3. Provider-Specific Examples

Each connector has detailed examples in its documentation:

• 📱 Twilio SMS Examples
• 💬 WhatsApp Business Examples
• 🔔 Firebase Push Examples
• 📧 SendGrid Email Examples

🎯 Core Features

Strongly-Typed Endpoints

// Type-safe endpoint creation
var emailEndpoint = Endpoint.EmailAddress("[email protected]");
var phoneEndpoint = Endpoint.PhoneNumber("+1234567890");
var deviceEndpoint = Endpoint.DeviceId("firebase-device-token");

Flexible Content Types

// Rich content support
.WithHtmlContent("<h1>Welcome!</h1>")
.WithTemplateContent("template-name", new { user = "John" })
.WithMediaContent("https://example.com/image.jpg", "image/jpeg")

Webhook Integration

// Bidirectional messaging
[HttpPost("webhook/provider")]
public async Task<IActionResult> ReceiveMessage([FromForm] Dictionary<string, string> data)
{
    var messageSource = MessageSource.FromFormData(data);
    var result = await connector.ReceiveMessagesAsync(messageSource, cancellationToken);
    return Ok();
}

Error Handling

var result = await connector.SendMessageAsync(message, cancellationToken);
if (!result.IsSuccess)
{
    Console.WriteLine($"Error: {result.ErrorMessage}");
    // Handle specific error cases
}

📚 Documentation

Getting Started

• 📖 Getting Started Guide - Step-by-step setup and first message
• 🔌 Connector Documentation - Complete connector guides

Framework Guides

• 🏗️ Channel Schema Guide - Schema configuration
• ⚡ Connector Implementation - Building custom connectors
• 🎯 Endpoint Types - Type-safe endpoint usage
• 🚀 Advanced Configuration - Production patterns

Provider-Specific

• 📱 Twilio SMS - SMS messaging with webhooks
• 💬 Twilio WhatsApp - WhatsApp Business integration
• 🔔 Firebase FCM - Push notifications
• 📧 SendGrid Email - Email delivery

🌟 Latest Features

• 🔥 Firebase Cloud Messaging - Complete FCM connector with multicast support
• 💬 Enhanced WhatsApp Business - Interactive elements, templates, and media
• 📞 Two-Way SMS - Webhook support for incoming messages and status updates
• 📊 Batch Processing - Efficient bulk operations across all connectors
• 🛡️ Health Monitoring - Built-in connection testing and diagnostics

🧪 Testing

The framework includes comprehensive test suites with over 500 tests:

# Run all tests
dotnet test

# Run tests for specific areas
dotnet test test/Deveel.Messaging.Abstractions.XUnit
dotnet test test/Deveel.Messaging.Connector.Twilio.XUnit

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone and build
git clone https://github.com/deveel/deveel.messaging.git
cd deveel.messaging
dotnet build
dotnet test

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 📖 Documentation: docs/README.md
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

---

Built with ❤️ by the Deveel team