> ## 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 Go SDK flow: authenticate, create an instance, subscribe, pair, configure events, and send messages

This guide shows the recommended path from zero to a connected instance sending messages through VZaps.

## 1. Install and create the client

```bash theme={null}
go get github.com/vzaps/vzaps-sdk-go/vzaps
```

```go theme={null}
import (
	"context"
	"os"

	vzaps "github.com/vzaps/vzaps-sdk-go/vzaps"
)

client := vzaps.MustNewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})

ctx := context.Background()
```

## 2. Validate authentication

```go theme={null}
jwt, err := client.Auth.GetAccessToken(ctx)
if err != nil {
	panic(err)
}
println(jwt[:16])
```

In most flows you do not need to call `GetAccessToken()`. SDK resources do it automatically.

## 3. List existing instances

```go theme={null}
instances, err := client.Instances.List(ctx, vzaps.InstanceListRequest{
	Page:     1,
	PageSize: 20,
	Search:   "support",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", instances)
```

## 4. Create an instance

```go theme={null}
created, err := client.Instances.Create(ctx, vzaps.InstanceCreateRequest{
	Name:            "Sales Support",
	Webhook:         "https://example.com/webhooks/vzaps",
	EventsSubscribe: []string{"Message", "ReadReceipt", "Connected", "Disconnected"},
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", created)
```

Store from the response:

* `id`: instance identifier.
* `token`: instance token. Use it as `InstanceToken` in instance calls.

## 5. Subscribe the instance

```go theme={null}
subscription, err := client.Instances.Subscribe(ctx, "VZ...", nil, vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", subscription)
```

If a cancellation is scheduled and you want to reactivate the subscription:

```go theme={null}
resumed, err := client.Instances.ResumeSubscription(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
```

## 6. Pair WhatsApp

Check status:

```go theme={null}
status, err := client.Sessions.Status(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", status)
```

Fetch QR code:

```go theme={null}
qr, err := client.Sessions.QR(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", qr)
```

Fetch pairing code by phone:

```go theme={null}
pairCode, err := client.Sessions.PairCode(ctx, "VZ...", "5511999999999", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", pairCode)
```

## 7. Configure webhook

See [Webhooks](/en/sdk/go/webhooks) for full configuration, logs, and examples.

```go theme={null}
_, err = client.Webhooks.Set(ctx, vzaps.WebhookConfigRequest{
	InstanceScopedRequest: vzaps.InstanceScopedRequest{
		InstanceID:    "VZ...",
		InstanceToken: "instance-token",
	},
	WebhookURL: "https://example.com/webhooks/vzaps",
	Events:     []string{"Message", "ReadReceipt", "Connected", "Disconnected"},
})
```

## 8. Subscribe to realtime

See [Realtime](/en/sdk/go/realtime) for subscription details, ack, and reconnection.

```go theme={null}
sub, err := client.Events.Subscribe(ctx, vzaps.EventSubscribeRequest{
	InstanceID:    "VZ...",
	InstanceToken: "instance-token",
	Events:        []vzaps.EventType{vzaps.EventMessage, vzaps.EventConnected, vzaps.EventDisconnected},
	Reconnect:     true,
})
if err != nil {
	panic(err)
}

sub.On(vzaps.EventMessage, func(event vzaps.Event) {
	fmt.Println(event.ID)
	fmt.Printf("%#v\n", event.Data)
})

sub.OnError(func(err error) {
	fmt.Println(err)
})
```

## 9. Send the first message

```go theme={null}
_, err = client.Messages.SendText(ctx, vzaps.MessageSendTextRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: "instance-token",
		},
		Phone: "5511999999999",
	},
	Message: "Hello! This message was sent with VZaps.",
})
```

## 10. Send media

Image:

```go theme={null}
_, err = client.Messages.SendImage(ctx, vzaps.MessageSendImageRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: "instance-token",
		},
		Phone: "5511999999999",
	},
	Image:   "https://example.com/image.jpg",
	Caption: "Image sent with VZaps",
})
```

Document:

```go theme={null}
_, err = client.Messages.SendDocument(ctx, vzaps.MessageSendDocumentRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: "instance-token",
		},
		Phone: "5511999999999",
	},
	Document: "https://example.com/contract.pdf",
	FileName: "contract.pdf",
	Caption:  "Here is the contract",
})
```

See [Messages](/en/sdk/go/messages) for all send types and payloads.

## 11. Check queues

See [Queues](/en/sdk/go/queues) to list, remove, and purge queues.

## 12. Handle errors

```go theme={null}
import (
	"errors"
	"fmt"
)

_, err = client.Messages.SendText(ctx, vzaps.MessageSendTextRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: "instance-token",
		},
		Phone: "5511999999999",
	},
	Message: "Hello",
})
if err != nil {
	var authErr *vzaps.AuthenticationError
	var timeoutErr *vzaps.TimeoutError
	var apiErr *vzaps.Error

	switch {
	case errors.As(err, &authErr):
		fmt.Println("Invalid credentials")
	case errors.As(err, &timeoutErr):
		fmt.Println("Request timed out")
	case errors.As(err, &apiErr):
		fmt.Println(apiErr.Status, apiErr.Message, apiErr.Details)
	}

	panic(err)
}
```