.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 7.0 or later
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
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.MessageId}");
}
catch (ApiException ex)
{
    Console.WriteLine($"Failed to send message: {ex.Message}");
}

Methods prefixed with Try never throw exceptions. They return an ApiResponse<T> object:

var response = await messagesClient.TrySendTextAsync(request);
if (response.IsSuccess)
{
    Console.WriteLine($"Message sent with ID: {response.Result.MessageId}");
}
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.SenderName);
                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

Create an authorization attribute

public class WebhookAuthorizationAttribute : Attribute, IAuthorizationFilter
{
    public void OnAuthorization(AuthorizationFilterContext context)
    {
        var config = context.HttpContext.RequestServices
            .GetRequiredService<IConfiguration>();
        var header = config["WSAPI:WebhookHeader"];
        var secret = config["WSAPI:WebhookSecret"];

        if (string.IsNullOrEmpty(header) || string.IsNullOrEmpty(secret))
            return;

        if (!context.HttpContext.Request.Headers
                .TryGetValue(header, out var value) || value != secret)
        {
            context.Result = new UnauthorizedObjectResult(
                "Invalid or missing webhook secret");
        }
    }
}

Create the webhook controller

[ApiController]
[Route("wsapi")]
public class WebhookController : ControllerBase
{
    private readonly ILogger<WebhookController> _logger;

    public WebhookController(ILogger<WebhookController> logger)
    {
        _logger = logger;
    }

    [WebhookAuthorization]
    [HttpPost("webhook")]
    public async Task<IActionResult> Webhook(CancellationToken ct)
    {
        var json = await new StreamReader(
            HttpContext.Request.Body).ReadToEndAsync(ct);
        var evt = EventFactory.ParseEvent(json);

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

        return Ok();
    }
}

Configure appsettings.json

{
  "WSAPI": {
    "ApiKey": "sk_your_api_key_here",
    "InstanceId": "ins_your_instance_id_here",
    "WebhookHeader": "X-Auth-Secret",
    "WebhookSecret": "your_webhook_secret_here"
  }
}

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

GitHub

​Installation

​Requirements

​Quick start

​Dependency injection (recommended)

​Error handling

​Receiving events via SSE

​Handling webhooks

​GitHub

Installation

Requirements

Quick start

Dependency injection (recommended)

Error handling

Receiving events via SSE

Handling webhooks

GitHub