Skip to main content
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

ResourceVersion
Go1.22 or higher
Do not expose ClientSecret or InstanceToken in public front ends. Prefer using the SDK in backends, API routes, jobs, and server-to-server automations.

​
Install

go get github.com/vzaps/vzaps-sdk-go/vzaps

​
Create the client

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: 
client := vzaps.MustNewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})

​
Credentials

The SDK uses two credential groups:
CredentialWhere to useDescription
ClientTokenClientOptionsAccount client token, also sent as X-Client-Token.
ClientSecretClientOptionsSecret used by the SDK to obtain and refresh JWTs.
InstanceTokenOn each instance callInstance token, sent as X-Instance-Token.
InstanceToken is not stored on the global client. Always pass it in calls that operate an instance: 
_, 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: 
accessToken, err := client.Auth.GetAccessToken(ctx)

​
Client options

OptionTypeDefaultUse
ClientTokenstring-Required. Account client token.
ClientSecretstring-Required. Account secret.
Timeouttime.Duration30sHTTP request timeout.
TokenSkewtime.Duration1mRefresh JWT before actual expiry.
HTTPClientHTTPDoerhttp.DefaultClientCustomize HTTP transport in tests or specific runtimes.
DialerWebSocketDialergorilla defaultCustomize WebSocket transport for realtime.
UserAgentstring-User-Agent header for HTTP requests.
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: 
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