> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Starter Guide

> Complete first integration flow with the VZaps .NET SDK

This guide shows the common integration path: create the client, validate authentication, prepare an instance, configure event delivery, and send messages.

## 1. Install and create the client

```bash theme={null}
dotnet add package VZaps.SDK
```

```csharp theme={null}
using VZaps;
using VZaps.Models;

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

## 2. Validate authentication

```csharp theme={null}
var token = await client.Auth.GetAccessTokenAsync();
Console.WriteLine(token[..Math.Min(20, token.Length)]);
```

## 3. List existing instances

```csharp theme={null}
var instances = await client.Instances.ListAsync<object>(new InstanceListRequest
{
    Page = 1,
    PageSize = 20,
});
```

## 4. Create an instance

```csharp theme={null}
var created = await client.Instances.CreateAsync<object>(new InstanceCreateRequest
{
    Name = "support",
    Webhook = "https://example.com/vzaps/webhook",
    EventsSubscribe = new[] { "Message", "Connected", "Disconnected" },
});
```

## 5. Subscribe the instance

```csharp theme={null}
await client.Instances.SubscribeAsync<object>(
    "VZ...",
    new { plan = "direct" },
    new InstanceRequestOptions { InstanceToken = "instance-token" });
```

Use `ResumeSubscriptionAsync` to resume a subscription and `CancelAsync` to cancel it.

## 6. Pair WhatsApp

```csharp theme={null}
var status = await client.Sessions.StatusAsync<object>("VZ...", new InstanceRequestOptions
{
    InstanceToken = "instance-token",
});

var qr = await client.Sessions.QrAsync<object>("VZ...", new InstanceRequestOptions
{
    InstanceToken = "instance-token",
});

var pairCode = await client.Sessions.PairCodeAsync<object>(
    "VZ...",
    "5511999999999",
    new InstanceRequestOptions { InstanceToken = "instance-token" });
```

## 7. Configure webhook

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

## 8. Subscribe to realtime

```csharp theme={null}
await using var subscription = await client.Events.SubscribeAsync(new VZapsEventSubscribeRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Events = new[] { VZapsEventType.Message, VZapsEventType.Connected },
    Reconnect = true,
    MaxRetries = 10,
});

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

## 9. Send the first message

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

## 10. Send media

```csharp theme={null}
await client.Messages.SendImageAsync<object>(new SendImageMessageRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Phone = "5511999999999",
    Image = "https://cdn.example.com/photo.jpg",
    Caption = "Optional caption",
});
```

See [Messages](/en/sdk/dotnet/messages) for text, image, audio, document, video, sticker, GIF, location, contact, buttons, list, link, and poll.

## 11. Check queues

```csharp theme={null}
await client.Queues.ListMessagesAsync<object>(new QueueRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
});

await client.Queues.ListOperationsAsync<object>(new QueueRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
});
```

## 12. Handle errors

```csharp theme={null}
try
{
    await client.Messages.SendTextAsync<object>(new SendTextMessageRequest
    {
        InstanceId = "VZ...",
        InstanceToken = "instance-token",
        Phone = "5511999999999",
        Message = "Hello",
    });
}
catch (VZapsAuthenticationException ex)
{
    Console.WriteLine(ex.StatusCode);
}
catch (VZapsRateLimitException ex)
{
    Console.WriteLine(ex.StatusCode);
}
catch (VZapsApiException ex)
{
    Console.WriteLine(ex.ResponseBody);
}
```

Every method accepts `CancellationToken cancellationToken = default`.