BeeZapdocs
EntrarPainel →

Como começar

Tutorial pra quem recebeu acesso a uma conta no BeeZap. Em 10 minutos: você loga, configura webhook, gera a chave de API e dispara a primeira mensagem.

1. Receber e fazer login

O administrador do hub cria seu usuário e te envia 3 coisas: URL do painel, email e senha. Acesse <URL>/login com essas credenciais.

Troque a senha imediatamente
Por enquanto a senha é entregue por canal externo (email/WhatsApp). Acesse /app/config/usuarios e crie outro usuário com a senha que você quer, depois peça pro hub remover o original. Em breve teremos fluxo de invitation por email.

2. Conhecer o painel

Após o login, você vai cair em /app com:

  • Dashboard — métricas das últimas 24h da sua conta.
  • Sessões WhatsApp — números conectados ao hub, criados pelo cliente quando a engine ativa permite auto-serviço.
  • Conversas — chat estilo WhatsApp Web pra ver e responder em tempo real.
  • Log de mensagens — histórico cru de tudo que entrou e saiu, com filtros.
  • Webhooks — entregas mais recentes do hub pra sua URL, com erros e tentativas.
  • Configurações — webhook URL, API key, equipe.

3. Configurar URL de webhook

O webhook é o endereço HTTP que o BeeZap chama quando algum evento WhatsApp acontece (mensagem recebida, ack de leitura, sessão conectada, etc). Sem ele você só envia, nunca recebe.

  1. Vá em /app/config.
  2. Cole a URL pública do seu sistema, ex: https://meusistema.com.br/webhooks/beezap.
  3. Clique Salvar URL.

Detalhes da carga útil, headers de assinatura HMAC e exemplos de handler estão na seção Webhooks.

4. Gerar a chave da API

A primeira chave é criada pelo admin do hub junto com a sua conta. Pra regenerar (em caso de vazamento ou se alguém saiu da equipe):

  1. Em /app/config, ache o card API key.
  2. Clique em Regenerar API key.
  3. Copie a chave exibida — ela aparece uma única vez.
  4. Atualize seu sistema. A chave antiga deixa de funcionar imediatamente.
Apenas TENANT_ADMIN
Operadores veem a configuração mas não conseguem regenerar chaves nem mudar a URL de webhook.

Secret do webhook (HMAC)

Junto da chave de API existe um webhook secret separado — é com ele que o BeeZap assina os webhooks que manda pra você. Em /app/config dá pra regenerar (idem: aparece uma vez, copia agora).

5. Primeira mensagem

Com a chave em mãos, dispara um teste:

curl -X POST <URL_DO_HUB>/api/v1/messages \
  -H "Authorization: Bearer <SUA_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "chatId": "5511999999999@c.us",
    "text": "Olá do BeeZap"
  }'

Se voltar status 200 com messageId, está pronto. Os campos completos do endpoint estão em API REST.

6. Convidar a equipe

Admins podem convidar mais usuários em /app/config/usuarios:

  1. Clique em + Novo usuário.
  2. Preencha nome, email, senha (mín. 8 chars), papel.
  3. Entregue email + senha pra pessoa por canal seguro.

Papéis disponíveis:

  • Admin — gerencia tudo (webhook, chaves, equipe).
  • Operador — usa conversas e visualiza dados; não muda configs.

Problemas comuns

  • API retorna 503 "No session available" — nenhuma sessão WhatsApp tá conectada no hub. Avise o admin pra checar o status do(s) número(s).
  • Webhook não chega — confira em /app/webhooks se há tentativas. Se o status mostra 4xx/5xx, seu servidor está retornando erro. O BeeZap tenta novamente com backoff exponencial.
  • Mensagem volta com 4xx "Número não registrado" — o destinatário não está no WhatsApp. Verifique o formato (DDI+DDD+número, ex: 5511999999999@c.us).