BotoZap

Documentação da BotoZap

Uma API REST para enviar mensagens e gerenciar clientes na WhatsApp Cloud API oficial, em modelo multi-tenant.

A BotoZap é uma plataforma sobre a WhatsApp Cloud API oficial da Meta. Cada cliente seu conecta a WABA dele, e você envia e recebe mensagens em nome de todos por um endpoint só. Esta documentação cobre a API REST, os webhooks e o SDK.

Opera o negócio e não integra por API? Veja a Central de Ajuda.

Base URL

https://botozap.com.br/api/v1

Autenticação

Toda requisição leva a sua chave de API no header, como Bearer ou como X-API-Key. A conta é derivada da chave, então você nunca passa um id de conta (o isolamento multi-tenant é garantido no servidor).

Authorization: Bearer $BOTOZAP_KEY

Detalhes em Autenticação.

Formato de resposta

  • Sucesso singular: { "data": <objeto> }.
  • Lista: { "data": [...], "paging": {...} } nas rotas paginadas por cursor, ou { "data": [...], "meta": {...} } nas paginadas por página. A referência diz qual vale em cada rota.
  • Erro: { "error": { "code": "...", "message": "..." } }.

Por onde começar

  • Primeiros passos: envie a primeira mensagem em minutos, no sandbox, sem custo e sem credenciais Meta.
  • Quickstart: seu número: do sandbox ao número real do seu negócio, com webhook e envio.
  • Quickstart: revenda: um Cliente por negócio, link de setup e envio pelo número de cada um.
  • Enviar mensagens: texto, template e a janela de 24h.
  • Contatos e funil: contatos, campos personalizados, Etapas do funil e Consentimento.
  • Atendimento: respostas compartilhadas, notas, retornos e organização do Inbox.
  • CRM: oportunidades, demandas e o Radar de pendências.
  • Agenda: compromissos, disponibilidade e sincronização com o Google Calendar.
  • Réguas: sequências automáticas de mensagens e o consentimento que elas exigem.
  • Agente de IA: configure e opere agentes pela API.
  • Webhooks: receba eventos de mensagem e status, com assinatura HMAC.
  • Eventos: os tipos de Evento e a releitura ordenada por GET /api/v1/events.
  • Endpoint para agentes: enfileire Eventos com durabilidade e acorde seu worker sem polling.
  • MCP para agentes: compare o suporte dos clientes a notifications, releitura de resources e novo agent turn; implemente cursor e replay sem prometer wake-up inexistente.
  • Confiabilidade e entrega: o que a API garante: at-least-once, retry, DLQ e replay.
  • Transmissões e limites: os quatro limites independentes de uma transmissão e da quota mensal.
  • Referência da API /v1: todos os endpoints, escopos e paginação.
  • Erros e escopos: o que cada código de erro significa, o que fazer, e o catálogo de escopos das chaves.
  • SDK Node: cliente tipado publicado no npm, com a API REST como fallback estável.
  • Conceitos: WABA, Embedded Signup, multi-tenant e BSUID.