Naty.Core 1.0.0-rc.1

Naty.Core

Official .NET SDK for the Naty platform — a multi-channel corporate messaging system built on WhatsApp.

Naty.Core provides a strongly-typed, async-first HTTP client that wraps the Naty REST API (V2 and V3) with built-in retry logic, rate-limit handling, and transparent error mapping.

Table of Contents

• Naty.Core
  • Table of Contents
  • Installation
  • Quick Start
    • Send a Message
    • Create and Start a Campaign
    • Access V3 Services
  • Configuration
    • Constructor Overloads
  • API Reference
    • V2 Services
    • V3 Services
  • Exception Handling
  • Logging
  • License

Installation

dotnet add package Naty.Core

Or via the NuGet Package Manager:

Install-Package Naty.Core

Requirements: .NET Standard 2.0 compatible runtime (.NET 6+, .NET Framework 4.6.1+, .NET Core 2.0+).

Quick Start

Send a Message

using Naty.Core;
using Naty.Core.Enums;
using Naty.Core.Models;

var settings = new NatySettings
{
    BaseUrl = "https://api.portal.naty.app",
    JwtToken = "your-jwt-token-here"
};

// Use ApiVersion.V2 or ApiVersion.V3
var client = new NatyClient(ApiVersion.V3, settings);

// Send a single WhatsApp message
var response = await client.MessageService.SendAsync(new MessageRequest
{
    WhatsappId = Guid.Parse("your-whatsapp-id"),
    Number     = "5511999999999",
    Text       = "Hello from Naty.Core!"
});

Console.WriteLine($"Message ID: {response.MessageId}");

Create and Start a Campaign

var campaign = await client.CampaignService.CreateAsync(new CampaignRequest
{
    Name       = "My First Campaign",
    WhatsappId = Guid.Parse("your-whatsapp-id"),
    Messages   = new List<MessageRequestItem>
    {
        new MessageRequestItem { Number = "5511999999999", Text = "Hi there!" },
        new MessageRequestItem { Number = "5511888888888", Text = "Hi there!" }
    }
});

await client.CampaignService.StartAsync(campaign.Id);

Access V3 Services

// List open tickets
var tickets = await client.V3.Tickets.ListAsync(new TicketFilter
{
    Status = TicketStatus.Open,
    Page   = 1,
    Limit  = 20
});

foreach (var ticket in tickets.Data)
    Console.WriteLine($"[{ticket.Id}] {ticket.Subject}");

// Trigger a ChatFlow
await client.V3.ChatFlow.TriggerAsync(
    chatFlowId:  Guid.Parse("chatflow-guid"),
    whatsappId:  Guid.Parse("whatsapp-guid"),
    number:      "5511999999999"
);

Configuration

Instantiate NatySettings and pass it to the NatyClient constructor.

Settings are validated at construction time. Invalid values (e.g. bad URL, missing token, MinMsgInterval >= MaxMsgInterval) throw immediately with a descriptive message.

Constructor Overloads

// Without logging
var client = new NatyClient(ApiVersion.V3, settings);

// With Microsoft.Extensions.Logging
ILoggerFactory loggerFactory = LoggerFactory.Create(b => b.AddConsole());
var client = new NatyClient(ApiVersion.V3, settings, loggerFactory);

API Reference

V2 Services

Accessed via the top-level INatyClient properties.

Every method has an overload that accepts IRequestOptions for per-call customization (e.g. custom timeout or headers).

V3 Services

Accessed via client.V3.*.

Exception Handling

try
{
    await client.MessageService.SendAsync(request);
}
catch (MaxRequestPerHourException ex)
{
    Console.WriteLine($"Rate limit hit. Resets at {ex.Reset:u}. Limit: {ex.Limit}");
}
catch (NatyApiV3Exception ex)
{
    Console.WriteLine($"API error [{ex.StatusCode}] {ex.ApiMessage} (requestId: {ex.RequestId})");
}

Error code constants are available in ErrorCodes:

// ErrorCodes.ERR_MAX_REQUEST_PER_HOUR
// ErrorCodes.ERR_SLOW_DOWN

Logging

Pass an ILoggerFactory to enable structured logging inside the SDK:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug));

var client = new NatyClient(ApiVersion.V3, settings, loggerFactory);

The SDK logs HTTP requests, retries, and rate-limit events at Debug / Warning levels.

License

This project is licensed under the MIT License.

© 2026 NatyApp