Pular para o conteúdo principal

Quickstart — primeiro envio em 5 minutos

Você vai conectar um número e enviar a primeira mensagem.

1. Pegue sua API key​

No painel (admin) ou com o super-admin, crie uma API key do seu tenant. Ela vira Authorization: Bearer bz_live_... em toda chamada.

2. Crie um número e conecte por QR​

# cria a instância (número)
curl -X POST https://api.bzapper.com.br/instances \
  -H "Authorization: Bearer $BZ_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"+5511999999999","nickname":"vendas"}'

# inicia a conexão por QR (ou ?method=code para código de pareamento)
curl -X POST "https://api.bzapper.com.br/instances/$ID/connect?method=qr" \
  -H "Authorization: Bearer $BZ_KEY"

A resposta traz qr_code. Renderize como QR e escaneie no WhatsApp em Aparelhos conectados → Conectar um aparelho. Acompanhe o status:

curl "https://api.bzapper.com.br/instances/$ID" -H "Authorization: Bearer $BZ_KEY"
# status: qr_pending → connecting → connected (número novo entra em "warming")

Dica: abra o stream SSE (GET /stream) e veja o status mudar na hora.

O QR não aparece?​

Quando um número já foi pareado antes, pode sobrar uma credencial de aparelho presa ao registro — e o connect não emite QR nenhum. O logout não resolve: ele só solta a referência e deixa o aparelho antigo para trás.

Use o clear-session, que apaga a credencial e devolve o número ao estado de fábrica:

curl -X POST "https://api.bzapper.com.br/instances/$ID/clear-session" \
  -H "Authorization: Bearer $BZ_KEY"
# 204 → chame /connect de novo e o QR aparece

No painel: Números → ⋮ → Limpar sessão.

atenção

É irreversível: o número fica offline e precisa escanear o QR outra vez. O histórico de mensagens é preservado. A operação é idempotente — repetir não causa dano.

3. Envie a primeira mensagem​

Você não precisa dizer de qual número enviar — basta to e body. O bZapper escolhe um número do seu pool automaticamente (distribuição + afinidade de conversa):

curl -X POST https://api.bzapper.com.br/messages/text \
  -H "Authorization: Bearer $BZ_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+5511988888888","body":"Olá do bZapper! 🐝"}'
instance_id é OPCIONAL

Omita instance_id e o gateway escolhe o número (rotação/sticky) — é o caminho recomendado. Só informe instance_id se quiser forçar o envio por um número específico. Para descobrir os ids dos seus números, liste as instâncias:

curl https://api.bzapper.com.br/instances -H "Authorization: Bearer $BZ_KEY"
# → { "data": [ { "id": "<instance_id>", "phone": "+55...", "status": "connected", ... } ] }

No admin, a tela Números exibe o instance_id de cada número com um botão de copiar.

Pronto. O envelope de status (message.sent/delivered/read) chega pelos webhooks e pelo SSE, com seu client_reference ecoado de ponta a ponta.

Próximo: validar webhooks (HMAC).