Documentação da API
O que é a API da OnZap, os dois tipos de instância e a sua primeira requisição.
A OnZap é uma API HTTP de WhatsApp. Cada instância é um número de WhatsApp conectado: pela API você envia mensagens, lê conversas, administra grupos e recebe no seu sistema, por webhook, tudo o que acontece no número.
Endereço base https://app.onzap.io/v1/instances/{instanceId}
Autenticação header X-Instance-Token
Formato JSON (UTF-8), servidor a servidorO que você pode fazer
- Enviar mensagens de texto, imagem, áudio, vídeo, documento, localização, contato, enquete e reação.
- Receber eventos assinados: mensagens recebidas e enviadas, confirmações de entrega e leitura, status da conexão.
- Ler conversas: chats, histórico, contatos e foto de perfil.
- Grupos, canais, status e etiquetas (API OnZap).
- Templates e mensagens interativas (API oficial da Meta).
- Fila de envio: intervalo entre mensagens, "digitando…" e espera enquanto o celular está desconectado.
Tipos de instância
As duas usam as mesmas rotas e o mesmo formato de webhook. Você escolhe o tipo ao criar a instância:
| API OnZap | API oficial (Meta) | |
|---|---|---|
| Conexão | QR Code ou código no celular | Conta do Facebook (WhatsApp Business Platform) |
| Rotas | Todas, exceto as marcadas Só API oficial | As marcadas com o selo API oficial |
| Grupos, canais, status, etiquetas | Sim | Não |
| Botões | Não (o WhatsApp não exibe botões fora da API oficial) | Sim |
| Templates da Meta | Não | Sim |
| Janela de conversa | Livre | Fora das 24 h desde a última mensagem do cliente, só templates |
| Foto de perfil e de grupo | Sim (links assinados em from.picture e chatPicture) | Não (a Meta não fornece) |
| Cobrança por mensagem | Não | A Meta cobra direto na sua conta do WhatsApp Business |
Fluxo básico de integração
- Crie a conta e uma instância no painel.
- Conecte o número: QR Code, código no celular ou conta da Meta.
- Copie o ID e o token da instância em Credenciais da API.
- Envie mensagens pelas rotas de Mensagens.
- Cadastre um webhook para receber as respostas e os status de entrega.
Primeira requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
-H "X-Instance-Token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"chatId": "5511999999999", "text": "Olá! Primeira mensagem pela OnZap."}'A resposta traz o id da mensagem. Guarde-o: é por ele que você acompanha a entrega e a leitura no evento
message.ack e responde ou reage a ela depois.
Versões
A API é versionada no caminho (/v1). Mudanças compatíveis, como campos, rotas e eventos novos, entram sem aviso;
trate campos desconhecidos com tolerância. Mudanças incompatíveis viram uma nova versão, com prazo de transição.