RepletoryLib.Communication.WhatsApp 1.0.0

RepletoryLib.Communication.WhatsApp

360Dialog WhatsApp Business API implementation with support for text, template, and media messages.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Communication.WhatsApp provides a 360Dialog WhatsApp Business API implementation of the IWhatsAppService interface from RepletoryLib.Communication.Abstractions. It sends messages via the 360Dialog REST API using a named HttpClient configured with the D-SECRET-KEY authentication header.

The service supports three message types: free-form text messages, pre-approved template messages (with body parameter substitution), and media messages (image, video, audio, document) with optional captions. It uses snake_case JSON serialization for the 360Dialog API and extracts message IDs from the messages[0].id response path.

Key Features

• Text messages -- Send free-form text messages to WhatsApp users
• Template messages -- Send pre-approved WhatsApp Business templates with body parameter substitution
• Media messages -- Send images, videos, audio files, and documents with optional captions
• Bulk send -- Send multiple text messages with per-message success/failure tracking
• Named HttpClient -- Pre-configured with base URL and D-SECRET-KEY header via IHttpClientFactory
• Error extraction -- Parses 360Dialog error responses for actionable error messages
• Unified routing -- Automatically registers ICommunicationService for cross-channel messaging

Installation

dotnet add package RepletoryLib.Communication.WhatsApp

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Communication.WhatsApp" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Prerequisites

• 360Dialog WhatsApp Business API account
• API key from the 360Dialog dashboard
• WhatsApp Business-approved templates (for template messages)
• Phone numbers must be in E.164 format (e.g., +27821234567)

Quick Start

using RepletoryLib.Communication.WhatsApp;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRepletoryWhatsApp(builder.Configuration);

{
  "Communication": {
    "WhatsApp": {
      "ApiKey": "your-360dialog-api-key",
      "ApiBaseUrl": "https://waba.360dialog.io/v1",
      "PhoneNumberId": "optional-phone-number-id"
    }
  }
}

Configuration

WhatsAppOptions

Section name: "Communication:WhatsApp"

Usage Examples

Register Services

using RepletoryLib.Communication.WhatsApp;

var builder = WebApplication.CreateBuilder(args);

// Register the 360Dialog WhatsApp service
builder.Services.AddRepletoryWhatsApp(builder.Configuration);

var app = builder.Build();

Send a Text Message

using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.WhatsApp;

public class CustomerSupportService
{
    private readonly IWhatsAppService _whatsAppService;

    public CustomerSupportService(IWhatsAppService whatsAppService) => _whatsAppService = whatsAppService;

    public async Task SendSupportReplyAsync(string phoneNumber, string replyText)
    {
        var result = await _whatsAppService.SendTextAsync(new WhatsAppTextMessage
        {
            To = phoneNumber,     // E.164 format: "+27821234567"
            Body = replyText
        });

        if (!result.Success)
            throw new InvalidOperationException($"WhatsApp message failed: {result.Error}");

        Console.WriteLine($"Message sent. MessageId: {result.MessageId}");
    }
}

Send a Template Message

using RepletoryLib.Communication.Abstractions.Models.WhatsApp;

// Template without parameters
var result = await _whatsAppService.SendTemplateAsync(new WhatsAppTemplateMessage
{
    To = "+27821234567",
    TemplateName = "hello_world",
    LanguageCode = "en"
});

// Template with body parameters
var result2 = await _whatsAppService.SendTemplateAsync(new WhatsAppTemplateMessage
{
    To = "+27821234567",
    TemplateName = "order_confirmation",
    LanguageCode = "en",
    Parameters = ["John Doe", "ORD-2024-001", "R 299.99"]
});

Send a Media Message

using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Models.WhatsApp;

// Send an image
var imageResult = await _whatsAppService.SendMediaAsync(new WhatsAppMediaMessage
{
    To = "+27821234567",
    MediaType = WhatsAppMediaType.Image,
    MediaUrl = "https://cdn.example.com/products/widget.jpg",
    Caption = "Check out our new Widget!"
});

// Send a document
var docResult = await _whatsAppService.SendMediaAsync(new WhatsAppMediaMessage
{
    To = "+27821234567",
    MediaType = WhatsAppMediaType.Document,
    MediaUrl = "https://cdn.example.com/invoices/inv-001.pdf",
    Caption = "Invoice #001"
});

// Send a video
var videoResult = await _whatsAppService.SendMediaAsync(new WhatsAppMediaMessage
{
    To = "+27821234567",
    MediaType = WhatsAppMediaType.Video,
    MediaUrl = "https://cdn.example.com/tutorials/setup.mp4",
    Caption = "Setup tutorial"
});

// Send audio (no caption support)
var audioResult = await _whatsAppService.SendMediaAsync(new WhatsAppMediaMessage
{
    To = "+27821234567",
    MediaType = WhatsAppMediaType.Audio,
    MediaUrl = "https://cdn.example.com/audio/welcome.mp3"
});

Bulk Send

var messages = phoneNumbers.Select(phone => new WhatsAppTextMessage
{
    To = phone,
    Body = "Reminder: Your appointment is tomorrow at 10:00 AM."
});

var bulkResult = await _whatsAppService.SendBulkAsync(messages);

Console.WriteLine($"Sent: {bulkResult.SuccessCount}, Failed: {bulkResult.FailureCount}");

foreach (var failure in bulkResult.Results.Where(r => !r.Success))
{
    Console.WriteLine($"Failed: {failure.Error}");
}

Using the Unified Communication Facade

using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Common;

public class NotificationService
{
    private readonly ICommunicationService _communication;

    public NotificationService(ICommunicationService communication) => _communication = communication;

    public async Task SendWhatsAppNotificationAsync(string phoneNumber, string message)
    {
        var result = await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.WhatsApp,
            Recipient = phoneNumber,
            Body = message
        });
    }
}

Multi-Channel Registration

using RepletoryLib.Communication.Email;
using RepletoryLib.Communication.Sms;
using RepletoryLib.Communication.WhatsApp;

var builder = WebApplication.CreateBuilder(args);

// Register email, SMS, and WhatsApp -- ICommunicationService routes to all three
builder.Services.AddRepletoryEmail(builder.Configuration);
builder.Services.AddRepletrySms(builder.Configuration);
builder.Services.AddRepletoryWhatsApp(builder.Configuration);

API Reference

ServiceCollectionExtensions

WhatsAppService (implements IWhatsAppService)

WhatsAppOptions

HTTP Client Configuration

The named HttpClient ("RepletoryWhatsApp") is pre-configured with:

Integration with Other RepletoryLib Packages

Testing

using Moq;
using Moq.Protected;
using System.Net;
using System.Net.Http.Json;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Models.WhatsApp;
using RepletoryLib.Communication.WhatsApp.Options;
using RepletoryLib.Communication.WhatsApp.Services;

[Fact]
public async Task SendTextAsync_returns_success_with_message_id()
{
    var responseJson = """{"messages": [{"id": "wamid.abc123"}]}""";

    var handler = new Mock<HttpMessageHandler>();
    handler
        .Protected()
        .Setup<Task<HttpResponseMessage>>(
            "SendAsync",
            ItExpr.IsAny<HttpRequestMessage>(),
            ItExpr.IsAny<CancellationToken>())
        .ReturnsAsync(new HttpResponseMessage(HttpStatusCode.OK)
        {
            Content = new StringContent(responseJson, System.Text.Encoding.UTF8, "application/json")
        });

    var httpClient = new HttpClient(handler.Object) { BaseAddress = new Uri("https://waba.360dialog.io/v1") };
    var mockFactory = new Mock<IHttpClientFactory>();
    mockFactory.Setup(f => f.CreateClient("RepletoryWhatsApp")).Returns(httpClient);

    var options = Options.Create(new WhatsAppOptions
    {
        ApiKey = "test-key",
        ApiBaseUrl = "https://waba.360dialog.io/v1"
    });

    var service = new WhatsAppService(mockFactory.Object, options, NullLogger<WhatsAppService>.Instance);

    var result = await service.SendTextAsync(new WhatsAppTextMessage
    {
        To = "+27821234567",
        Body = "Hello from WhatsApp!"
    });

    result.Success.Should().BeTrue();
    result.MessageId.Should().Be("wamid.abc123");
    result.Channel.Should().Be(CommunicationChannel.WhatsApp);
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.