API WhatsApp multi-instancia para integracoes comerciais

Links Rapidos

Autenticacao

x-api-key: woo_sua_api_key

Authorization: Bearer jwt_da_conta

Primeiros Passos

1. Criar ou obter uma instancia

No painel, crie uma nova instancia. A resposta da API ja entrega api_key, webhook_secret e URLs de webhook da instancia.

curl -X POST https://painel.wozapi.com.br/api/v1/instances \
  -H "Authorization: Bearer JWT_DA_CONTA" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atendimento Comercial",
    "webhook_url": "https://seu-n8n.com/webhook/wozapi"
  }'

2. Conectar o WhatsApp

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/connect \
  -H "x-api-key: woo_sua_api_key"

3. Enviar uma mensagem

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/send-text \
  -H "x-api-key: woo_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5548999999999",
    "text": "Ola! Mensagem enviada pela Wozapi."
  }'

Instancias

Instancias representam uma sessao WhatsApp independente. Cada instancia tem status, QR Code, numero conectado, perfil, API key, webhook proprio, logs e limites de uso.

Resposta de criacao

{
  "success": true,
  "data": {
    "id": 17,
    "api_key": "woo_xxx",
    "webhook_secret": "whsec_xxx",
    "webhook": {
      "webhooks_url": "https://painel.wozapi.com.br/api/v1/instances/17/webhooks",
      "webhook_events_url": "https://painel.wozapi.com.br/api/v1/instances/17/webhook-events",
      "webhook_logs_url": "https://painel.wozapi.com.br/api/v1/instances/17/webhook-logs",
      "webhook_test_url": "https://painel.wozapi.com.br/api/v1/instances/17/webhook/test",
      "signing_header": "X-Wooapi-Signature",
      "secret": "whsec_xxx"
    }
  }
}

Mensagens

Os endpoints de mensagem usam a API key da instancia. O destinatario pode ser enviado como number, phone ou jid. Numeros devem incluir DDI e DDD, sem simbolos.

Enviar midia

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/send-media \
  -H "x-api-key: woo_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5548999999999",
    "url": "https://exemplo.com/catalogo.pdf",
    "caption": "Catalogo atualizado",
    "mime_type": "application/pdf",
    "file_name": "catalogo.pdf"
  }'

Envio assincrono

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/send-text \
  -H "x-api-key: woo_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5548999999999",
    "text": "Ola! Esta mensagem sera enviada pela fila.",
    "async": true
  }'

Resposta quando enfileirada

{
  "success": true,
  "message": "Mensagem enfileirada para envio",
  "data": {
    "queued": true,
    "jobId": "12345",
    "pendingMessageId": "out_1710000000000"
  }
}

Enviar localizacao

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/send-location \
  -H "x-api-key: woo_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5548999999999",
    "latitude": -27.5949,
    "longitude": -48.5482,
    "name": "Wozapi",
    "address": "Florianopolis - SC"
  }'

Webhooks

Webhooks entregam eventos da instancia para sistemas externos. Cada webhook tem URL, secret HMAC, eventos filtrados, retentativas e logs de entrega.

Criar webhook

curl -X POST https://painel.wozapi.com.br/api/v1/instances/17/webhooks \
  -H "x-api-key: woo_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "n8n Atendimento",
    "url": "https://seu-n8n.com/webhook/wozapi",
    "events": ["message.received", "message.sent", "instance.connected", "instance.disconnected"],
    "retry_enabled": true,
    "max_attempts": 5
  }'

Eventos principais

• message.received: mensagem recebida.
• message.sent: mensagem enviada pela API/painel.
• message.read, message.edited, message.deleted, message.reaction: eventos de mensagem.
• instance.connected, instance.disconnected, instance.qr, instance.qr_expired: eventos de conexao.
• webhook.sent, webhook.failed, webhook.retrying: eventos operacionais.

Integracao Com n8n

Para conectar no n8n, o integrador precisa apenas da URL da API, ID da instancia e API key. Para receber eventos, crie um node Webhook no n8n e cadastre a URL dele na Wozapi.

Node HTTP Request - enviar texto

{
  "method": "POST",
  "url": "https://painel.wozapi.com.br/api/v1/instances/17/send-text",
  "headers": {
    "x-api-key": "woo_sua_api_key",
    "Content-Type": "application/json"
  },
  "body": {
    "number": "5548999999999",
    "text": "Ola, {{$json.nome}}! Seu atendimento foi iniciado."
  }
}

Fluxo recomendado no n8n

1. Webhook Trigger: recebe message.received da Wozapi.
2. IF/Switch: separa mensagem de texto, midia, grupo ou contato.
3. CRM/Planilha/Banco: registra lead e historico.
4. IA ou regras: gera resposta.
5. HTTP Request: envia resposta pela Wozapi usando a mesma API key.

Postman

A collection Wozapi ja inclui variaveis de ambiente e requests para health, instancias, status, envio, webhooks, contatos, campanhas, logs e administracao.

Variaveis da collection

Contatos e Chats

Perfil e Grupos

Campanhas, Fila e CRM

A Wozapi possui recursos locais de campanhas, recipients, delays, pausar/cancelar, relatorios, leads, tags, notas, respostas rapidas e campos personalizados.

Admin, Observabilidade e Producao

O painel administrativo inclui metricas de instancias, filas, webhooks, alertas, logs, clientes, planos, backups e readiness de producao.

• GET /health: banco, bridge, Redis/fila, readiness e bloqueios.
• GET /api/admin/overview: visao geral de clientes, usuarios, instancias e mensagens.
• GET /api/admin/wooapi-monitor: observabilidade por instancia, filas, webhooks e alertas.
• GET /api/admin/logs?type=webhooks: logs administrativos.
• GET /api/admin/backups, POST /api/admin/backups: backup operacional.
• GET /docs/production-readiness.md: checklist de producao.

Limitacoes Comerciais Importantes

• Botoes interativos nativos oficiais nao fazem parte do produto vendavel nesta versao. Use texto, links, midia, webhooks e fluxos externos.
• Use delays, limites por plano e boas praticas anti-spam.
• Evite disparos massivos sem consentimento.
• Configure Redis/BullMQ em producao para escala real.
• Configure Stripe para billing automatizado e readiness comercial completo.
• Mantenha backup de banco, sessoes e midias.