VZaps.SDK 0.1.1

VZaps .NET SDK

Official .NET client for the VZaps public API. Send WhatsApp messages, manage instances, configure webhooks, and subscribe to realtime events with a resource-oriented, async-first interface.

Targets netstandard2.0 and net8.0. Use it from .NET Framework 4.6.1+, .NET Core 3.1, .NET 6, or any newer runtime; .NET 8+ is recommended for greenfield apps.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Authentication
• Client options
• Resources
• Instance tokens
• Webhooks
• Realtime events
• Error handling
• .NET
• Documentation

Features

• Automatic JWT handling — exchanges ClientToken + ClientSecret for a bearer token and refreshes it before expiry.
• Resource-oriented API — Instances, Messages, Webhooks, Contacts, Groups, and Events mirror the public HTTP contract.
• Async-first — all operations accept CancellationToken.
• Realtime WebSocket client — subscribe to instance events with reconnect, resume (LastEventId), and server-side ack.
• Instance token support — pass InstanceToken on each instance-scoped request.
• Typed request models — exported C# models for common public API payloads.
• Extensible transport — inject a custom HttpClient for tests, proxies, or tracing.

Requirements

The NuGet package is not limited to .NET 8. Legacy apps on .NET 6 (or .NET Core 3.1) consume the netstandard2.0 target automatically. .NET 8+ is recommended only for new projects that want the latest runtime build.

The SDK uses HttpClient by default. No extra HTTP dependency is required.

Installation

dotnet add package VZaps.SDK

Quick start

Create credentials in the VZaps dashboard (ClientToken and ClientSecret), then send a text message:

using VZaps;
using VZaps.Models;

using var client = new VZapsClient(new VZapsClientOptions
{
    ClientToken = Environment.GetEnvironmentVariable("VZAPS_CLIENT_TOKEN"),
    ClientSecret = Environment.GetEnvironmentVariable("VZAPS_CLIENT_SECRET"),
});

await client.Messages.SendTextAsync<object>(new SendTextMessageRequest
{
    InstanceId = "VZKB8AU4S4CWY1SLXX4I5WJGRZQMDDFTV6",
    InstanceToken = Environment.GetEnvironmentVariable("VZAPS_INSTANCE_TOKEN"),
    Phone = "5511999999999",
    Message = "Hello from VZaps",
});

Authentication

VZaps uses a two-step model:

1. Account credentials — ClientToken and ClientSecret identify your integration. The SDK calls POST /token and caches the JWT.
2. Instance token — instance-scoped routes also require X-Instance-Token. Pass it on each instance-scoped request (see Instance tokens).

Every authenticated HTTP request sends:

You rarely need to call Auth.GetAccessTokenAsync directly — resources attach the token for you. Use it when integrating with custom HTTP logic:

var token = await client.Auth.GetAccessTokenAsync(cancellationToken);

Client options

Pass options to new VZapsClient(options):

Pass a custom HttpClient as the second constructor argument when you need proxy, TLS, or test handlers:

using var client = new VZapsClient(options, httpClient);

Resources

The client exposes namespaced resources. Generic response types (TResponse) let you align with your own models or the OpenAPI schema.

All resource methods accept a CancellationToken.

client.Instances

client.Messages

client.Messages wraps the public WhatsApp send and chat endpoints. The most common calls are shown below; the SDK also exposes the other public message operations documented in the API reference, including media, interactive messages, reactions, polls, downloads, edits, deletes, presence, and read receipts.

await client.Messages.SendTextAsync<object>(new SendTextMessageRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Phone = "5511999999999",
    Message = "Hello",
});

await client.Messages.SendImageAsync<object>(new SendImageMessageRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Phone = "5511999999999",
    Image = "https://example.com/photo.jpg",
    Caption = "Check this out",
});

Available send helpers include SendTextAsync, SendImageAsync, SendAudioAsync, SendDocumentAsync, SendVideoAsync, SendStickerAsync, SendGifAsync, SendLocationAsync, SendContactAsync, SendButtonsAsync, SendListAsync, SendLinkAsync, and SendPollAsync. See the API documentation for complete payload examples.

client.Webhooks

client.Contacts

client.Groups

client.Sessions

GET /instances/{id}/session/status returns SessionStatusResponse. When Data.Connected is true, Data includes (in order) Phone, WhatsappJid, PushName, BusinessName, BusinessProfile, ProfilePictureId, ProfilePictureUrl, ProfileUrl, and optional VerifiedName, About, Website. When disconnected, Data only has Connected = false.

Other public namespaces are available as first-class resources too: Sessions, Users, Queues, TypeBots, Chatwoot, and Chats.

client.RequestAsync<TResponse>(method, path, options?)

Escape hatch for advanced calls or newly released endpoints:

var instance = await client.RequestAsync<object>(
    HttpMethod.Post,
    "/instances/get",
    new VZaps.Http.VZapsRequestOptions
    {
        Body = new { id = "VZ..." },
    });

Instance tokens

Instance-scoped routes require the instance token in addition to account credentials. Pass it on each request that targets an instance:

await client.Messages.SendTextAsync<object>(new SendTextMessageRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Phone = "5511999999999",
    Message = "Hello",
});

Or pass InstanceRequestOptions on resource methods that accept it:

await client.Instances.RestartAsync<object>(
    "VZ...",
    new InstanceRequestOptions { InstanceToken = "instance-token" });

Webhooks

Configure HTTP callbacks for instance events (same payload shape as realtime data, delivered to your URL):

await client.Webhooks.SetAsync<object>(new WebhookSetRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    WebhookURL = "https://example.com/webhooks/vzaps",
    Events = new[] { "Message", "Connected", "Disconnected" },
});

Common event types: Message, ReadReceipt, Connected, Disconnected, Presence, ChatPresence, HistorySync, GroupParticipantsAdd, GroupParticipantsRemove, or All.

Event payloads (webhook and realtime) use snake_case, matching the platform. Incoming media events include media_url inside data when platform storage is available.

Realtime events

Subscribe to the same events over the VZaps realtime WebSocket. This is the recommended path for in-app notifications, bots, and dashboards that need low-latency delivery without exposing a public webhook URL.

Subscribe

await using var subscription = await client.Events.SubscribeAsync(
    new VZapsEventSubscribeRequest
    {
        InstanceId = "VZ...",
        InstanceToken = "instance-token",
        Events = new[] { VZapsEventType.Message, VZapsEventType.Connected, VZapsEventType.Disconnected },
        Reconnect = true,
        LastEventId = "evt_previous_id", // optional resume after disconnect
    },
    cancellationToken);

subscription.On(VZapsEventType.Message, evt =>
{
    Console.WriteLine(evt.Data);
});

subscription.OnError(error => Task.CompletedTask);

await subscription.WaitForCloseAsync(cancellationToken);

Event envelope

Each WebSocket message keeps the platform shape (snake_case):

{
  "id": "evt_…",
  "type": "Message",
  "instance_id": "VZ…",
  "created_at": "2026-06-23T22:57:17.000Z",
  "data": {
    "type": "Message",
    "event": { },
    "media_url": "https://…"
  }
}

• data — same payload as webhook delivery (snake_case).
• media_url — present on incoming media messages when platform storage is available.

Delivery and ack

Delivery is at-least-once. After your handler runs, the SDK sends an ack automatically on the WebSocket connection. Use LastEventId when reconnecting if you need to reduce gaps. Deduplicate on evt.Id in your application if you process events idempotently.

Subscribe options

Handler registration

Error handling

The SDK throws typed exceptions you can catch and branch on:

try
{
    await client.Messages.SendTextAsync<object>(request, cancellationToken);
}
catch (VZapsAuthenticationException)
{
    Console.WriteLine("Check client credentials");
}
catch (VZapsTimeoutException)
{
    Console.WriteLine("Request timed out");
}
catch (VZapsRateLimitException)
{
    Console.WriteLine("Rate limited");
}
catch (VZapsApiException ex)
{
    Console.WriteLine(ex.StatusCode, ex.Message, ex.Details);
}

Exception fields include StatusCode, ErrorCode, Details, RequestId, and a truncated ResponseBody when available.

.NET

The package uses PascalCase for C# models and camelCase JSON serialization on HTTP request bodies and API responses. Realtime and webhook event payloads stay in snake_case so both delivery channels match the platform.

Resources accept a generic TResponse when you want strongly typed API responses:

var page = await client.Instances.ListAsync<object>(new InstanceListRequest
{
    Page = 1,
    Size = 20,
    Search = "support",
});

Use RequestAsync<TResponse> when you need full control over method, path, and body.

Documentation

• VZaps docs
• API reference (OpenAPI)
• Postman collections
• Report an issue

License

MIT © VZaps