Pular para o conteúdo principal
O SDK Go oficial da VZaps encapsula autenticação, chamadas HTTP, headers obrigatórios, eventos realtime e os principais recursos da API pública. Use este SDK em backends Go, workers, CLIs e automações server-to-server.

​
Requisitos

RecursoVersão
Go1.22 ou superior
Não exponha ClientSecret nem InstanceToken em front-end público. Prefira usar o SDK em backend, API routes, jobs e automações server-to-server.

​
Instalar

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

​
Criar o cliente

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)
}
Para scripts rápidos, MustNewClient faz panic se as opções forem inválidas: 
client := vzaps.MustNewClient(vzaps.ClientOptions{
	ClientToken:  os.Getenv("VZAPS_CLIENT_TOKEN"),
	ClientSecret: os.Getenv("VZAPS_CLIENT_SECRET"),
})

​
Credenciais

O SDK usa dois grupos de credenciais:
CredencialOnde usarDescrição
ClientTokenClientOptionsToken de cliente da conta, também enviado como X-Client-Token.
ClientSecretClientOptionsSegredo usado pelo SDK para obter e renovar JWTs.
InstanceTokenEm cada chamada de instânciaToken da instância, enviado como X-Instance-Token.
InstanceToken não fica no cliente global. Passe em toda chamada que opera uma instância: 
_, 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: "Olá da VZaps",
})

​
Autenticação automática

O SDK obtém JWT automáticamente com ClientToken e ClientSecret, cacheia em memória e renova antes de expirar. Raramente precisa chamar Auth.GetAccessToken() manualmente. Quando integrar com lógica customizada: 
accessToken, err := client.Auth.GetAccessToken(ctx)

​
Opções do cliente

OpçãoTipoPadrãoUso
ClientTokenstring-Obrigatório. Token de cliente da conta.
ClientSecretstring-Obrigatório. Segredo da conta.
Timeouttime.Duration30sTimeout HTTP.
TokenSkewtime.Duration1mRenovar JWT antes da expiração real.
HTTPClientHTTPDoerhttp.DefaultClientTransporte HTTP customizado em testes ou runtimes específicos.
DialerWebSocketDialergorilla padrãoTransporte WebSocket para realtime.
UserAgentstring-Header User-Agent nas requisições HTTP.

​
Variáveis de ambiente recomendadas

VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=your-instance-token

​
Tipagem de respostas

Métodos de recurso retornam map[string]any porque a API pode evoluir. Deserialize em structs próprias ou use client.Request com saída tipada: 
var instance map[string]any
err := client.Request(ctx, http.MethodPost, "/instances/get", vzaps.RequestOptions{
	Body: map[string]string{"id": "VZ..."},
}, &instance)
Para listas, defina structs com tags json no formato da API pública.

​
Próximos passos