Pular para o conteúdo principal
Este guia mostra o caminho recomendado do zero até uma instância conectada enviando mensagens pela VZaps.

1. Instalar e criar o cliente

go get github.com/vzaps/vzaps-sdk-go/vzaps
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. Validar autenticação

jwt, err := client.Auth.GetAccessToken(ctx)
if err != nil {
	panic(err)
}
println(jwt[:16])
Na maioria dos fluxos não precisa chamar GetAccessToken(). Recursos do SDK fazem isso automáticamente.

3. Listar instâncias existentes

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. Criar uma instância

created, err := client.Instances.Create(ctx, vzaps.InstanceCreateRequest{
	Name:            "Suporte Comercial",
	Webhook:         "https://example.com/webhooks/vzaps",
	EventsSubscribe: []string{"Message", "ReadReceipt", "Connected", "Disconnected"},
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", created)
Guarde da resposta:
  • id: identificador da instância.
  • token: token da instância. Use como InstanceToken nas chamadas de instância.

5. Assinar a instância

subscription, err := client.Instances.Subscribe(ctx, "VZ...", nil, vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", subscription)
Se houver cancelamento agendado e quiser reativar a assinatura:
resumed, err := client.Instances.ResumeSubscription(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})

6. Parear WhatsApp

Verificar status:
status, err := client.Sessions.Status(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", status)
Obter QR code:
qr, err := client.Sessions.QR(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", qr)
Obter código de pareamento por telefone:
pairCode, err := client.Sessions.PairCode(ctx, "VZ...", "5511999999999", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
if err != nil {
	panic(err)
}
fmt.Printf("%#v\n", pairCode)

7. Configurar webhook

Veja Webhooks para configuração completa, logs e exemplos.
_, 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. Assinar realtime

Veja Realtime para detalhes de assinatura, ack e reconexão.
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. Enviar a primeira mensagem

_, err = client.Messages.SendText(ctx, vzaps.MessageSendTextRequest{
	MessageSendBaseRequest: vzaps.MessageSendBaseRequest{
		InstanceScopedRequest: vzaps.InstanceScopedRequest{
			InstanceID:    "VZ...",
			InstanceToken: "instance-token",
		},
		Phone: "5511999999999",
	},
	Message: "Olá! Esta mensagem foi enviada com a VZaps.",
})

10. Enviar mídia

Imagem:
_, 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: "Imagem enviada com VZaps",
})
Documento:
_, 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:    "Aqui está o contrato",
})
Veja Mensagens para todos os tipos de envio e payloads.

11. Consultar filas

Veja Filas para listar, remover e limpar filas.

12. Tratar erros

import (
	"errors"
	"fmt"
)

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

	switch {
	case errors.As(err, &authErr):
		fmt.Println("Credenciais inválidas")
	case errors.As(err, &timeoutErr):
		fmt.Println("Requisição expirou")
	case errors.As(err, &apiErr):
		fmt.Println(apiErr.Status, apiErr.Message, apiErr.Details)
	}

	panic(err)
}