.NET SDK

The WSAPI .NET SDK provides a strongly-typed C# client for sending WhatsApp messages, managing groups and chats, and receiving real-time events via webhooks or Server-Sent Events (SSE).

Installation

NuGet CLI
Package Manager Console

dotnet add package WSApi.Client

Install-Package WSApi.Client

Requirements

.NET 8, 9 or 10
Valid WSAPI API key and instance ID

Quick start

using WSApi.Client.ApiClient;
using WSApi.Client.Models.Requests.Messages;

var httpClient = new HttpClient
{
    BaseAddress = new Uri("https://api.wsapi.chat")
};
httpClient.DefaultRequestHeaders.Add("X-Api-Key", "<your-api-key>");
httpClient.DefaultRequestHeaders.Add("X-Instance-Id", "<instance-id>");

var messagesClient = new MessagesClient(httpClient);
var request = new MessageSendTextRequest
{
    To = "1234567890@s.whatsapp.net",
    Text = "Hello from .NET SDK!"
};
await messagesClient.SendTextAsync(request);

Dependency injection (recommended)

// Program.cs
using WSApi.Client;
builder.Services.AddWsApiClient("<your-api-key>", "<instance-id>");

Then inject IWSApiClient where needed:

public class MyService
{
    private readonly IWSApiClient _wsApiClient;

    public MyService(IWSApiClient wsApiClient)
    {
        _wsApiClient = wsApiClient;
    }

    public async Task SendMessage()
    {
        var request = new MessageSendTextRequest
        {
            To = "1234567890@s.whatsapp.net",
            Text = "Hello from .NET SDK!"
        };
        await _wsApiClient.Messages.SendTextAsync(request);
    }
}

All API endpoints are available via the corresponding client classes in WSApi.Client.ApiClient (e.g., GroupsClient, ChatsClient, ContactsClient) or through the unified IWSApiClient interface.

Error handling

The SDK provides two method variants for every operation:

Exception-based
Try-based (non-throwing)

Standard methods throw exceptions when API calls fail and return the result directly on success:

try
{
    var result = await messagesClient.SendTextAsync(request);
    Console.WriteLine($"Message sent with ID: {result.Id}");
}
catch (ApiException ex)
{
    Console.WriteLine($"Failed to send message: {ex.Message}");
}

Methods prefixed with Try return API failures as response objects. They return an ApiResponse<T> object:

var response = await messagesClient.TrySendTextAsync(request);
if (response.IsSuccess)
{
    Console.WriteLine($"Message sent with ID: {response.Result?.Id}");
}
else
{
    Console.WriteLine($"Failed to send message: {response.Error.Detail}");
}

The ApiResponse<T> object contains:

Result — response data (null if failed)
Error — error details as ProblemDetails (null if successful)
IsSuccess — boolean indicating success

Receiving events via SSE

Create a BackgroundService to handle SSE events:

using WSApi.Client;
using WSApi.Client.Models.Constants;
using WSApi.Client.Models.Events.Messages;
using WSApi.Client.SSE;

public class SSEClientService : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<SSEClientService> _logger;
    private readonly ISSEClient _sseClient;

    public SSEClientService(
        IServiceScopeFactory scopeFactory,
        ILogger<SSEClientService> logger,
        ISSEClient sseClient)
    {
        _scopeFactory = scopeFactory;
        _logger = logger;
        _sseClient = sseClient;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _sseClient.RawEventReceived += OnRawEventReceived;
        _sseClient.ConnectionStateChanged += OnConnectionStateChanged;

        _logger.LogInformation("Starting SSE client...");
        await _sseClient.StartAsync(stoppingToken);
    }

    private void OnRawEventReceived(object? sender, RawEventReceivedEventArgs args)
    {
        var evt = EventFactory.ParseEvent(args.RawJson);

        switch (evt.EventType)
        {
            case EventTypes.Message:
                var messageEvent = (MessageEvent)evt;
                _logger.LogInformation(
                    "Message received: {Text} From: {From}",
                    messageEvent.Text, messageEvent.Sender.Id);
                break;
        }
    }

    private void OnConnectionStateChanged(
        object? sender, SSEConnectionStateChangedEventArgs args)
    {
        _logger.LogInformation("SSE state changed to: {State}", args.State);
    }
}

builder.Services.AddWsApiClient(apiKey, instanceId);
builder.Services.AddHostedService<SSEClientService>();

Handling webhooks

Read the original request bytes before parsing JSON. Configure the same signing secret on the instance and in your application; do not compare a static authentication header.

using System.Security.Cryptography;
using System.Text;
using WSApi.Client;
using WSApi.Client.Models.Events.Messages;

var signingSecret = builder.Configuration["WSAPI:SigningSecret"]
    ?? throw new InvalidOperationException("Configure WSAPI:SigningSecret");
var app = builder.Build();

app.MapPost("/wsapi/webhook", async (HttpRequest request, CancellationToken ct) =>
{
    using var body = new MemoryStream();
    await request.Body.CopyToAsync(body, ct);
    var bytes = body.ToArray();
    var expected = "sha256=" + Convert.ToHexString(
        HMACSHA256.HashData(Encoding.UTF8.GetBytes(signingSecret), bytes)
    ).ToLowerInvariant();
    var received = request.Headers["X-Webhook-Signature"].ToString();
    if (!CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(received)))
        return Results.Unauthorized();

    var evt = EventFactory.ParseEvent(Encoding.UTF8.GetString(bytes));
    if (evt is MessageEvent message)
        Console.WriteLine($"Message from {message.Sender.Id}: {message.Text}");

    return Results.Ok();
});
app.Run();

Compatibility and recent fields

Message events (including history) expose optional AdReferral; persist message.AdReferral?.CtwaClid when present. Media requests support the current optional caption, MIME type and view-once fields. QR image methods return PNG bytes; QR text methods return the code string. Existing C# group setting property names are preserved while their JSON fields match the REST API. GroupInviteLink.InviteLink reads link; GroupJoined.GroupId reads id. Join-by-invite receives HTTP 204 and returns the requested group ID for compatibility. Contacts.UpdateAsync now uses the contact upsert endpoint. Breaking change: SynchronizeAllAsync and TrySynchronizeAllAsync have been removed from ChatsClient and IChatsClient because there is no current REST endpoint for them. Use ListAsync to list chats or RequestMessagesAsync to request history for a specific chat (and their Try variants). Account management and SSE are Cloud features, not OSS admin APIs. Create a named Cloud instance using CreateSubscriptionInstanceAsync(subscriptionId, name: "Support"); the existing cancellation-token parameter remains compatible.

GitHub

github.com/wsapi-chat/wsapi-dotnet

Getting Started

Basics

SDKs & Libraries

Integrations

Installation

Requirements

Quick start

Dependency injection (recommended)

Error handling

Receiving events via SSE

Handling webhooks

Compatibility and recent fields

GitHub

​Installation

​Requirements

​Quick start

​Dependency injection (recommended)

​Error handling

​Receiving events via SSE

​Handling webhooks

​Compatibility and recent fields

​GitHub

Installation

Requirements

Quick start

Dependency injection (recommended)

Error handling

Receiving events via SSE

Handling webhooks

Compatibility and recent fields

GitHub