Quick start

Este guia assume que você já tem uma conta admin na plataforma. Se você é o operador da plataforma e ainda não criou seu projeto, faça login no Admin primeiro.

Crie um projeto no Admin

Acesse o Admin: http://localhost:3012
Em Projetos, clique em Novo projeto
Preencha: nome, slug, plano (ACTIVE), quotas
Salve

O projeto recebe um identificador único (CUID). Anote — você vai usar em chamadas API.

Gere uma API key

Ainda no Admin, abra o projeto recém-criado
Vá em API Keys → Gerar nova
Copie o valor — só é mostrado uma vez (formato pzk_live_xxx...)

A chave é hashada (SHA-256) no banco. Se perder, gera nova. Nunca commita uma chave em código — use variável de ambiente.

Crie sua primeira instância

curl -X POST http://localhost:3010/v1/instances \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "atendimento-vendas" }'

Resposta:

{
  "id": "cm5x8a9k20001abc123def456",
  "name": "atendimento-vendas",
  "status": "DISCONNECTED",
  "phoneNumber": null,
  "createdAt": "2026-05-23T22:15:00.000Z"
}

Escanear o QR

Abra o Manager: http://localhost:3011/instances/cm5x8a9k20001abc123def456

Aponte a câmera do WhatsApp (no celular do chip) pra esse QR.

Status muda automaticamente: DISCONNECTED → QR_PENDING → CONNECTED em poucos segundos.

Enviar a primeira mensagem

curl -X POST http://localhost:3010/v1/instances/cm5x8a9k20001abc123def456/messages/text \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Olá do PEPINO ZAP!"
  }'

Resposta:

{
  "id": "msg_cm5x8...",
  "jobId": "outbound-cm5x8...:7281",
  "status": "PENDING"
}

A mensagem entra na fila (River postgres-native) e é despachada pelo worker respeitando o rate-limit configurado da instância.

Pronto

Você tem instância conectada e mensagem saindo. Próximos passos sugeridos:

Configurar webhooks — receber mensagens entrantes no seu sistema
Conceitos: anti-ban — warmup, ramp-up e por que sua conta não banir
API Reference — endpoints completos