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

# Installation

> How to install, authenticate, and configure the official VZaps Go SDK

The official VZaps Go SDK wraps authentication, HTTP calls, required headers, realtime events, and the main public API resources.

Use this SDK for Go backends, workers, CLIs, and server-to-server automations.

## Requirements

| Resource | Version        |
| -------- | -------------- |
| Go       | 1.22 or higher |

<Tip>
  Do not expose `ClientSecret` or `InstanceToken` in public front ends. Prefer using the SDK in backends, API routes, jobs, and server-to-server automations.
</Tip>

## Install

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

## Create the client

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

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

client, err := vzaps.NewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})
if err != nil {
	panic(err)
}
```

For quick scripts and examples, `MustNewClient` panics on invalid options:

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

## Credentials

The SDK uses two credential groups:

| Credential      | Where to use          | Description                                          |
| --------------- | --------------------- | ---------------------------------------------------- |
| `ClientToken`   | `ClientOptions`       | Account client token, also sent as `X-Client-Token`. |
| `ClientSecret`  | `ClientOptions`       | Secret used by the SDK to obtain and refresh JWTs.   |
| `InstanceToken` | On each instance call | Instance token, sent as `X-Instance-Token`.          |

`InstanceToken` is not stored on the global client. Always pass it in calls that operate an instance:

```go theme={null}
_, err := client.Messages.SendText(context.Background(), vzaps.MessageSendTextRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: os.Getenv("VZAPS_INSTANCE_TOKEN"),
		},
		Phone: "5511999999999",
	},
	Message: "Hello from VZaps",
})
```

## Automatic authentication

The SDK obtains a JWT automatically with `ClientToken` and `ClientSecret`, caches it in memory, and refreshes it before expiry.

You rarely need to call `Auth.GetAccessToken()` manually. When you need to integrate with custom logic:

```go theme={null}
accessToken, err := client.Auth.GetAccessToken(ctx)
```

## Client options

| Option         | Type              | Default              | Use                                                     |
| -------------- | ----------------- | -------------------- | ------------------------------------------------------- |
| `ClientToken`  | `string`          | -                    | Required. Account client token.                         |
| `ClientSecret` | `string`          | -                    | Required. Account secret.                               |
| `Timeout`      | `time.Duration`   | `30s`                | HTTP request timeout.                                   |
| `TokenSkew`    | `time.Duration`   | `1m`                 | Refresh JWT before actual expiry.                       |
| `HTTPClient`   | `HTTPDoer`        | `http.DefaultClient` | Customize HTTP transport in tests or specific runtimes. |
| `Dialer`       | `WebSocketDialer` | gorilla default      | Customize WebSocket transport for realtime.             |
| `UserAgent`    | `string`          | -                    | `User-Agent` header for HTTP requests.                  |

## Recommended environment variables

```bash theme={null}
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=your-instance-token
```

## Typing responses

Resource methods return `map[string]any` because the API can evolve. Unmarshal into your own structs or use `client.Request` with a typed output:

```go theme={null}
var instance map[string]any
err := client.Request(ctx, http.MethodPost, "/instances/get", vzaps.RequestOptions{
	Body: map[string]string{"id": "VZ..."},
}, &instance)
```

For list responses, define structs with `json` tags that match the public API.

## Next steps

* Follow the [Starter Guide](/en/sdk/go/starter-guide) to create an instance, subscribe it, pair WhatsApp, and send the first message.
* See [Messages](/en/sdk/go/messages) for every send method.
* See [Instances and billing](/en/sdk/go/instances-and-billing), [Session](/en/sdk/go/session), and [Chats](/en/sdk/go/chats) for core instance resources.
* See [Webhooks](/en/sdk/go/webhooks), [Queues](/en/sdk/go/queues), [Groups](/en/sdk/go/groups), [TypeBot](/en/sdk/go/typebot), and [Chatwoot](/en/sdk/go/chatwoot) for configuration and integrations.