> ## 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

> Fluxo completo para começar com o SDK .NET da VZaps

Este guia mostra o caminho comum de integração: criar o cliente, validar autenticação, preparar uma instância, configurar recebimento de eventos e enviar mensagens.

## 1. Instale e crie o cliente

```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. Valide autenticação

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

## 3. Liste instâncias existentes

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

## 4. Crie uma instância

```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. Assine a instância

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

Use `ResumeSubscriptionAsync` para retomar uma assinatura e `CancelAsync` para cancelar.

## 6. Pareie o 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. Assine 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. Envie a primeira mensagem

```csharp theme={null}
await client.Messages.SendTextAsync<object>(new SendTextMessageRequest
{
    InstanceId = "VZ...",
    InstanceToken = "instance-token",
    Phone = "5511999999999",
    Message = "Olá, sua instância está conectada.",
});
```

## 10. Envie mídia

```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 = "Legenda opcional",
});
```

Veja [Mensagens](/pt-BR/sdk/dotnet/messages) para texto, imagem, áudio, documento, vídeo, sticker, GIF, localização, contato, botões, lista, link e enquete.

## 11. Acompanhe filas

```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. Trate erros

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

Todos os métodos aceitam `CancellationToken cancellationToken = default`.