BotoZap: a API oficial do WhatsApp, do jeito que devia ser

Sua chave de API

Gere e gerencie suas chaves no painel, em Chaves de API. Cada chave pertence à sua conta e concede acesso apenas aos recursos dela.

Trate a chave como um segredo: guarde em variável de ambiente, nunca no controle de versão nem no código do cliente. Se uma chave vazar, revogue-a no painel e gere outra. Toda chamada usa HTTPS.

Como autenticar

Envie a chave em um dos dois headers aceitos: Authorization no formato Bearer, ou X-API-Key. Escolha um só. A conta é resolvida a partir da chave, então você nunca passa um id de conta no corpo da requisição.

# Authorization: Bearer
curl https://botozap.com.br/api/v1/messages \
  -H "Authorization: Bearer $BOTOZAP_KEY"

# ou X-API-Key
curl https://botozap.com.br/api/v1/messages \
  -H "X-API-Key: $BOTOZAP_KEY"

Sandbox vs. produção

Ao gerar uma chave você escolhe o ambiente: Produção (prefixo bz_live_) ou Sandbox (prefixo bz_sandbox_). O ambiente autoritativo é o registrado no servidor para aquela chave. O prefixo é só cosmético para você reconhecer a chave em logs e no painel.

Uma chave sandbox nunca chama a Meta e nunca consome quota. Por segurança, ela só pode acessar uma allow-list bem restrita de rotas: POST /api/v1/messages, GET /api/v1/messages (lista) e GET /api/v1/messages/{id}. Qualquer outra rota responde 403 com code: "sandbox_forbidden". Isso é deliberado: uma chave sandbox é tratada como descartável, e nunca deve ter o poder de uma chave de produção em transmissões, mídia, templates etc. Veja o guia completo em Primeiros passos e os cenários simulados em Enviar mensagens.

Escopos

Cada chave pode ser restrita a um conjunto de escopos (ex.: messages:send, broadcasts:write, webhooks:read), um por recurso e ação. Toda rota da referência da API declara o escopo que exige.

Uma chave criada com a lista de escopos vazia tem acesso total (comportamento legado, para não quebrar chaves geradas antes de o sistema de escopos existir). Se você quer restringir o que uma chave pode fazer, selecione escopos específicos ao criá-la. Não deixe a lista vazia por padrão em integrações novas.

Erros de autenticação e autorização

Erros seguem o envelope { error: { code, message } }. Quando a chave está ausente ou é inválida, a API responde 401 com code: "unauthorized"; quando a chave é válida mas não tem o escopo exigido pela rota, responde 403 com code: "forbidden_scope".

{
  "error": {
    "code": "unauthorized",
    "message": "Chave de API ausente ou inválida."
  }
}

Rate limit

Toda rota /v1 soma para o mesmo limite por conta: 120 requisições a cada 10 segundos. Ao excedê-lo, a API responde 429 com code: "rate_limited" e os headers X-RateLimit-*/Retry-After. Detalhes completos (e os outros limites independentes da API) em Transmissões e limites.