Uma API clara para operar seu WhatsApp.

Corpo JSON

{
  "nome": "Atendimento São Paulo",
  "criar_instancia": true,
  "payment_method": "balance"
}

Cabeçalho para saldo

Idempotency-Key: 9f643462-ec66-49f1-977f-3cccf57d42ea

Resposta 201 Created ou 202 Accepted

{
  "status": "success",
  "instance_id": 123,
  "instance_hash": "ID_GERADO_PELO_SERVIDOR",
  "instance_token": "TOKEN_GERADO_PELO_SERVIDOR",
  "payment_status": "PAID",
  "expires_at": "2026-10-01 12:00:00",
  "balance_remaining_cents": 5010,
  "idempotent_replay": false,
  "remote_start_pending": false
}

• nome é obrigatório e aceita de 2 a 120 caracteres.
• O bearer precisa de instances:write; com payment_method: balance, também precisa de billing:balance.
• criar_instancia é opcional; quando enviado, precisa ser true.
• payment_method aceita pix ou balance. Pix devolve payment_url; saldo debita o preço do plano no servidor e libera exatamente 30 dias.
• Para balance, gere uma chave UUID por operação, persista-a e reutilize a mesma Idempotency-Key em timeout ou retry. Trocar payload com a mesma chave retorna 409.
• pagar_nahora: true é aceito como alias legado de payment_method: balance. O valor precisa ser booleano estrito e não pode conflitar com payment_method; caso contrário, retorna 422.
• remote_start_pending: true não desfaz o pagamento: a assinatura já foi liberada e o worker repetirá o início da sessão.
• Replay concluído pode responder 200. Nova criação responde 201; início remoto pendente responde 202.
• Erros possíveis: 400 JSON inválido, 401 credenciais, 402 saldo insuficiente, 403 escopo/conta, 405 método, 409 conflito idempotente, 413 limite de 32 KiB, 422 validação e 503 ledger indisponível.

Cabeçalhos

Authorization: Bearer wzap_live_SEU_BEARER
Idempotency-Key: 9f643462-ec66-49f1-977f-3cccf57d42ea
Content-Type: application/json

Corpo JSON

{
  "instance_hash": "ID_DA_INSTANCIA"
}

Resposta 200 OK ou 202 Accepted

{
  "status": "success",
  "code": "balance_instance_renewed",
  "billing_source": "BALANCE",
  "idempotent_replay": false,
  "operation": "RENEW",
  "operation_id": "UUID_DA_OPERACAO",
  "payment_id": "UUID_DO_PAGAMENTO",
  "instance_id": 123,
  "instance_hash": "ID_DA_INSTANCIA",
  "amount_cents": 4990,
  "balance_remaining_cents": 5010,
  "expires_at": "2026-10-31 12:00:00",
  "vencimento": "2026-10-31 12:00:00",
  "payment_status": "PAID",
  "activation_pending": false,
  "remote_start_pending": false
}

• O JSON aceita somente instance_hash com 32 caracteres hexadecimais. O token da instância não é necessário e nunca é retornado.
• Gere uma UUID por aceite do cliente, persista-a e reutilize a mesma Idempotency-Key após timeout. Um replay devolve o mesmo operation_id sem novo débito.
• Ativação vencida parte do horário atual; renovação ativa parte do vencimento existente. Ambas acrescentam exatamente 30 dias.
• Antes do débito, Pix aberto é consultado. Pix ainda incerto responde 409 payment_in_progress; Pix já pago retorna billing_source: ATIVOPAY e não debita saldo.
• activation_pending ou remote_start_pending indica trabalho remoto pendente, não falha ou reversão financeira.
• Erros: 401 bearer, 402 insufficient_balance, 403 escopo/conta, 404 instance_not_found, 409 pagamento/ativação/conflito/estado, 422 corpo/chave, 429 limite e 503 billing_unavailable.

Corpo JSON

{
  "instance_hash": "ID_DA_INSTANCIA"
}

Resposta 200 OK

{
  "status": "success",
  "message": "Instância excluída.",
  "remote_cleanup_pending": false
}

• Envie instance_hash ou, alternativamente, instance_id numérico. Se ambos forem enviados e o hash for válido, ele prevalece.
• O endpoint também aceita o método DELETE com o mesmo corpo JSON.
• remote_cleanup_pending: true significa que a exclusão local foi concluída, mas a limpeza da sessão ainda não foi confirmada.
• Uma cobrança Pix ou ativação ainda pendente bloqueia a exclusão com 409, evitando que um pagamento tardio fique sem serviço.
• Erros possíveis: 400 JSON inválido, 401 credenciais, 404 instância ausente ou de outra conta, 405 método, 409 cobrança/ativação pendente, 413 limite de 16 KiB, 422 identificador e 500 falha interna.

Resposta 410 Gone

{
  "status": "error",
  "code": "endpoint_retired",
  "message": "Alteração direta de vencimento foi desativada."
}

• Não implemente fallback para esta rota. Use ativar_instancia_saldo.php ou o fluxo Pix.

• Consulte novamente apenas enquanto o status for SCAN_QR_CODE.
• O campo mais comum na resposta é value.

• WORKING indica uma sessão pronta para uso.
• A resposta não inclui metadata, credenciais, webhooks internos ou configuração da engine.

• Não envie corpo JSON.
• Acompanhe a conclusão pela ação status.

• Não exclui o cadastro comercial da instância.
• Esta operação é intencionalmente diferente de reiniciar.

Corpo JSON

{
  "chatId": "[email protected]",
  "text": "Olá! Sua confirmação chegou.",
  "linkPreview": false
}

• A fachada força linkPreview=false para impedir buscas externas pelo motor.
• Use reply_to para responder diretamente a uma mensagem.
• O alias legado to/message é normalizado, mas chatId/text é o formato recomendado.

Corpo JSON

{
  "chatId": "[email protected]",
  "file": {
    "mimetype": "image/jpeg",
    "filename": "comprovante.jpg",
    "url": "https://cdn.exemplo.com/comprovante.jpg"
  },
  "caption": "Seu comprovante"
}

• Para Base64 bruto, sem prefixo data URI, troque file.url por file.data.
• URL e Base64 aceitam até 7 MiB decodificados e passam por detecção do MIME real.

Corpo JSON

{
  "chatId": "[email protected]",
  "file": {
    "mimetype": "video/mp4",
    "filename": "demonstracao.mp4",
    "url": "https://cdn.exemplo.com/demonstracao.mp4"
  },
  "caption": "Veja a demonstração",
  "convert": true
}

• URL e Base64 bruto aceitam até 7 MiB decodificados, com validação do MIME real.
• convert assume true quando omitido.
• asNote pode ser usado em engines compatíveis para vídeo circular.

Corpo JSON

{
  "chatId": "[email protected]",
  "file": {
    "mimetype": "application/pdf",
    "filename": "contrato.pdf",
    "url": "https://cdn.exemplo.com/contrato.pdf"
  },
  "caption": "Contrato para conferência"
}

• O corpo JSON aceita até 10 MiB; URL e Base64 aceitam mídia de até 7 MiB decodificados.
• O MIME real e extensões executáveis são validados antes do envio.

Corpo JSON

{
  "chatId": "[email protected]",
  "url": "https://www.exemplo.com/oferta",
  "title": "Confira sua oferta"
}

• A URL precisa resolver somente para endereços públicos e usar HTTPS.
• A fachada fornece título e descrição ao endpoint de prévia personalizada, sem imagem externa nem busca automática.

Corpo JSON

{
  "chatId": "[email protected]",
  "latitude": -23.55052,
  "longitude": -46.633308,
  "title": "Unidade Centro"
}

• latitude aceita de -90 a 90.
• longitude aceita de -180 a 180.

Corpo JSON

{
  "chatId": "[email protected]",
  "contacts": [
    {
      "fullName": "Atendimento WZAP",
      "organization": "WZAP-API",
      "phoneNumber": "+55 11 99999-9999",
      "whatsappId": "5511999999999",
      "vcard": null
    }
  ]
}

• São aceitos de 1 a 20 contatos por chamada.
• whatsappId não deve conter + nem @c.us.

Corpo JSON

{
  "chatId": "[email protected]",
  "header": "Atendimento",
  "body": "Como podemos ajudar?",
  "footer": "Escolha uma opção",
  "buttons": [
    {"type": "reply", "text": "Financeiro", "id": "financeiro"},
    {"type": "url", "text": "Central", "url": "https://www.exemplo.com"}
  ]
}

• A disponibilidade pode variar conforme a engine e as regras do WhatsApp.
• São aceitos no máximo 10 botões.

Corpo JSON

{
  "chatId": "[email protected]",
  "message": {
    "title": "Menu principal",
    "description": "Selecione o assunto",
    "footer": "Equipe WZAP",
    "button": "Escolher",
    "sections": [
      {
        "title": "Atendimento",
        "rows": [
          {"title": "Financeiro", "rowId": "financeiro", "description": "Pagamentos e notas"},
          {"title": "Suporte", "rowId": "suporte", "description": "Ajuda técnica"}
        ]
      }
    ]
  }
}

• A disponibilidade depende da engine conectada.
• rowId deve ser único dentro da lista.

Corpo JSON

{
  "chatId": "[email protected]",
  "messageIds": [
    "[email protected]_AAAAAAAAAAAAAAAAAAAA"
  ]
}

• messageIds é opcional para marcar as pendências do chat.
• Em grupos, participant pode ser necessário em algumas engines.

Corpo JSON

{
  "chatId": "[email protected]",
  "messageId": "[email protected]_AAAAAAAAAAAAAAAAAAAA"
}

• O WhatsApp aplica limites de tempo e permissão próprios.
• Esta ação apaga mensagem; não exclui a instância.

Corpo JSON

{
  "messageId": "[email protected]_AAAAAAAAAAAAAAAAAAAA",
  "reaction": "👍"
}

• Envie reaction como string vazia para remover a reação.
• Use o messageId completo recebido no webhook.

Corpo JSON

{
  "chatId": "[email protected]",
  "messageId": "[email protected]_AAAAAAAAAAAAAAAAAAAA"
}

• chatId é o destino.
• messageId identifica a mensagem de origem.

Corpo JSON

{
  "chatId": "[email protected]",
  "reply_to": "[email protected]_AAAAAAAAAAAAAAAAAAAA",
  "text": "Recebemos sua mensagem e já vamos ajudar."
}

• messageId/message também são normalizados para reply_to/text.
• A resposta é contabilizada como mensagem de texto.

• limit: 1 a 200; offset: 0 a 100000.
• sortBy: id ou name; sortOrder: asc ou desc.

Corpo JSON

{
  "phone": "5511999999999"
}

• phone aceita de 8 a 15 dígitos no padrão E.164, sem o sinal +.
• A resposta inclui numberExists/number_exists e chatId/chat_id; nenhuma configuração interna é devolvida.

• sortBy: conversationTimestamp, id ou name.
• merge aceita true ou false.

• sortBy: id ou subject.
• exclude aceita somente participants.

• Webhooks operacionais e de integrações privadas nunca são retornados.
• Chaves HMAC e valores de cabeçalhos personalizados são substituídos por indicadores de configuração.

Corpo JSON

{
  "config": {
    "webhooks": [
      {
        "url": "https://app.exemplo.com/webhooks/wzap",
        "events": ["message", "message.ack", "session.status"],
        "hmac": {"key": "uma-chave-secreta-com-32-caracteres"},
        "retries": {
          "policy": "exponential",
          "delaySeconds": 2,
          "attempts": 5
        },
        "customHeaders": [
          {"name": "X-Integration-Id", "value": "wzap-producao"}
        ]
      }
    ]
  }
}

• O destino deve ser HTTPS público na porta 443. DNS e IP são revalidados em cada entrega; redes privadas, reservadas, redirects e proxies são bloqueados.
• Envie config.webhooks como [] para remover todos os webhooks do cliente; o webhook operacional interno é preservado.
• Idempotency-Key é opcional neste PUT; quando enviado, um replay do mesmo payload devolve a resposta persistida e outro payload recebe 409.
• A resposta só confirma os destinos e eventos; HMAC, valores de cabeçalhos, metadata, referência opaca do relay e configuração interna nunca são devolvidos.
• São aceitos até 9 webhooks do cliente e 25 eventos por webhook.
• Depois de um 2xx confirmado, o mesmo corpo autenticado não é reenviado. A entrega continua sendo pelo menos uma vez em timeouts ambíguos; deduplicate pelo X-Webhook-Request-Id.

• Disponível somente para a conta técnica vinculada no servidor; outras credenciais recebem 404.
• Pode ser chamada logo após adopt-integration, mesmo com a instância ainda suspensa; proprietário, token e vínculo gerenciado são revalidados sob lock.
• Configurações diretas legadas precisam ser reconciliadas para o relay antes do upsert.
• Exige Idempotency-Key de 8 a 120 caracteres seguros.
• Se uma gravação/verificação anterior ficar uncertain, repetir exatamente a mesma chave e configuração reexecuta este upsert determinístico; envios ambíguos nunca recebem esse tratamento.
• Não envie URL, eventos ou HMAC: a ação não aceita corpo e usa apenas a configuração privada.
• O servidor confirma a gravação com um novo GET; a resposta nunca contém URL, segredo ou resposta interna.

Corpo JSON

{
  "source_ref": "wdivulga-user-0123456789abcdef0123456789abcdef"
}

• Disponível somente para a conta técnica configurada e uma instância ativa pertencente a ela; outras credenciais recebem 404.
• Exige o token atual da instância e Idempotency-Key de 8 a 120 caracteres seguros.
• A referência deve seguir exatamente wdivulga-user-<32 hex> e estar livre ou já pertencer à mesma instância.
• Uma adoção nova responde 202 e começa suspensa por segurança; em seguida chame resume-integration somente se a assinatura local estiver válida.
• Replays preservam o lifecycle atual e nunca reativam uma instância suspensa.

• Disponível somente para a conta técnica e instâncias com billing externo gerenciado; outras credenciais recebem 404.
• Exige Idempotency-Key de 8 a 120 caracteres seguros.
• HTTP 200 indica pausa confirmada; HTTP 202 indica revogação local aplicada e sincronização remota pendente no worker.
• Repetir a mesma chave devolve a resposta persistida sem aplicar uma segunda transição.

• Disponível somente para a conta técnica e instâncias com billing externo gerenciado; outras credenciais recebem 404.
• Exige Idempotency-Key de 8 a 120 caracteres seguros.
• HTTP 200 indica retomada confirmada; HTTP 202 mantém a fachada bloqueada enquanto o worker tenta novamente.
• A operação não recria nem devolve credenciais da instância.