# ZapZap API

> API para automação de WhatsApp via instâncias gerenciadas.
> Documentação completa: https://app.zapzapapi.com/docs

## Autenticação

Todos os requests requerem dois headers:
- `x-api-key`: sua chave de API (obtida no painel em Configurações > API)
- `x-api-secret`: seu segredo de API (obtido no painel em Configurações > API)

## Base URL

```
https://api.zapzapapi.com/api/v1/{instanceId}
```

Substitua `{instanceId}` pelo ID da instância WhatsApp (visível no painel).

**Endpoints de Gestão** (criar/listar/deletar instâncias, conta) usam:
```
https://api.zapzapapi.com/api/v1/instances
https://api.zapzapapi.com/api/v1/account
```

## Exemplo de requisição

```bash
curl -X POST https://api.zapzapapi.com/api/v1/{instanceId}/send/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"number":"5511999999999","text":"Olá!"}'
```

## Envio humanizado (digitando automático)

Todo envio de mensagem (`/send/*`) exibe automaticamente o "digitando..." no WhatsApp antes de entregar, com duração proporcional ao tamanho do texto. Isso humaniza o disparo e reduz o risco de bloqueio. Você não precisa fazer nada: já vem ligado por padrão.

- **Para desligar** em uma requisição específica, envie `"digitando": false` no corpo (aceita também `"typing": false`). O campo é consumido pelo ZapZap e não é repassado adiante.
- **A resposta continua síncrona**: a requisição retorna com o resultado do envio (status e id da mensagem), como sempre. A forma de uso não muda.
- **Janela de tempo**: por causa do "digitando", uma requisição de envio pode levar até ~20-30s no pior caso (mensagens longas) antes de responder. Se você chama a API de um ambiente com timeout curto (ex: Edge Functions do Supabase, 60s), isso cabe com folga. Para respostas quase imediatas, use `"digitando": false`.
- Cada instância também tem uma velocidade de fila (intervalo entre ações, padrão 2s) configurável no painel, que espaça os envios de forma humanizada.

---

## Conta & Instâncias

### GET /account
**Dados da Conta**

Retorna os dados da sua conta: nome, email, saldo atual, dia de cobrança e status.

**Exemplo de resposta:**
```json
{
  "id": "uuid",
  "name": "João",
  "email": "joao@email.com",
  "balance": "150.00",
  "billing_day": 10,
  "status": "ACTIVE"
}
```

---

### GET /instances
**Listar Instâncias**

Lista todas as instâncias WhatsApp da sua conta com status, nome, telefone e configurações.

**Exemplo de resposta:**
```json
[
  {
    "id": "uuid",
    "name": "minha-instancia",
    "status": "CONNECTED",
    "phone_number": "5511999999999"
  }
]
```

---

### POST /instances
**Criar Instância**

Cria uma nova instância WhatsApp. Debita automaticamente do saldo (taxa de ativação + proporcional). O nome deve conter apenas letras, números, _ e -.

**Body (JSON):**
- `name` (obrigatório): Nome da instância (ex: `minha-instancia`)
- `systemName` (opcional): Nome do sistema (exibido no WhatsApp) (ex: `Meu App`)
- `metadata` (opcional): Dados livres (JSON): vincule ao seu sistema (ex: clientId, plano) (ex: `{"clientId":"123","plan":"pro"}`)

**Exemplo de resposta:**
```json
{
  "instance": {
    "id": "uuid",
    "name": "minha-instancia",
    "status": "PENDING"
  },
  "billing": {
    "charged": 25.5
  }
}
```

---

### GET /instances/cost
**Custo de Criação**

Retorna o custo para criar uma nova instância: taxa de ativação, proporcional e saldo necessário.

**Exemplo de resposta:**
```json
{
  "activationFee": 10,
  "prorate": 15.5,
  "total": 25.5,
  "instancePrice": 49.9,
  "currentBalance": 150
}
```

---

### DELETE /instances/{id}
**Deletar Instância**

Deleta (soft delete) uma instância. O WhatsApp é desconectado e um waiver de taxa de ativação é gerado para a próxima criação.

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Exemplo de resposta:**
```json
{
  "message": "Instância deletada com sucesso"
}
```

---

### GET /instances/{id}
**Detalhes da Instância**

Retorna detalhes de uma instância específica.

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Exemplo de resposta:**
```json
{
  "id": "uuid",
  "name": "MinhaInstancia",
  "status": "CONNECTED",
  "phone_number": "5511999999999"
}
```

---

### PUT /instances/{id}
**Atualizar Instância**

Atualiza webhook_url e/ou metadata de uma instância. O metadata é um JSON livre para vincular a instância ao seu sistema (ex: ID do cliente, plano, etc). O metadata é incluído automaticamente nos webhooks recebidos.

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Body (JSON):**
- `webhook_url` (opcional): URL do webhook (HTTPS) (ex: `https://meusite.com/webhook`)
- `metadata` (opcional): Dados livres (JSON) (ex: `{"clientId":"123"}`)

**Exemplo de resposta:**
```json
{
  "id": "uuid",
  "name": "minha-instancia",
  "webhook_url": "https://meusite.com/webhook",
  "metadata": {
    "clientId": "123"
  }
}
```

---

### GET /instances/{id}/qrcode
**QR Code da Instância**

Retorna o QR Code para conectar o WhatsApp à instância. Escaneie com o celular.

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Exemplo de resposta:**
```json
{
  "connected": true,
  "instance": {
    "status": "connected",
    "profileName": "Nome"
  }
}
```

---

### GET /instances/{id}/webhook
**Ver Webhook**

Retorna a URL de webhook configurada para a instância. O webhook recebe eventos em tempo real (mensagens, status, etc).

⚠️ ATENÇÃO À URL: o {id} já vai no caminho: NÃO adicione duas vezes.

✅ Certo:  GET /api/v1/instances/SEU-INSTANCE-ID/webhook
❌ Errado: GET /api/v1/SEU-INSTANCE-ID/instances/SEU-INSTANCE-ID/webhook  (instanceId duplicado)

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Exemplo de resposta:**
```json
{
  "webhook_url": "https://meusite.com/webhook",
  "configured": true
}
```

---

### PUT /instances/{id}/webhook
**Configurar Webhook**

Define ou atualiza a URL de webhook da instância. A URL deve ser pública e acessível via HTTPS. Eventos como mensagens recebidas, status de entrega e mudanças de conexão serão enviados via POST para essa URL.

⚠️ ATENÇÃO À URL: o {id} já vai no caminho: NÃO adicione duas vezes.

✅ Certo:  PUT /api/v1/instances/SEU-INSTANCE-ID/webhook
❌ Errado: PUT /api/v1/SEU-INSTANCE-ID/instances/SEU-INSTANCE-ID/webhook  (instanceId duplicado)

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Body (JSON):**
- `webhook_url` (obrigatório): URL do webhook (HTTPS) (ex: `https://meusite.com/webhook`)
- `events` (opcional): Eventos para receber (vazio = todos) (ex: `messages,status`)
- `excludeMessages` (opcional): Excluir mensagens próprias (valores: true, false)

**Exemplo de resposta:**
```json
{
  "ok": true,
  "webhook_url": "https://meusite.com/webhook"
}
```

---

### POST /instances/{id}/webhook/test
**Testar Webhook**

Envia um evento de teste para a URL de webhook configurada. Retorna o status code e tempo de resposta. Útil para validar que seu servidor está recebendo os eventos corretamente.

⚠️ ATENÇÃO À URL: o {id} já vai no caminho: NÃO adicione duas vezes.

✅ Certo:  POST /api/v1/instances/SEU-INSTANCE-ID/webhook/test
❌ Errado: POST /api/v1/SEU-INSTANCE-ID/instances/SEU-INSTANCE-ID/webhook/test  (instanceId duplicado)

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Body (JSON):**
- `url` (opcional): URL alternativa para teste (opcional) (ex: `https://meusite.com/webhook`)

**Exemplo de resposta:**
```json
{
  "ok": true,
  "statusCode": 200,
  "responseTime": 150
}
```

---

### GET /instance/wa_messages_limits
**Limites de Novas Conversas (WhatsApp)**

Consulta o limite atual de novas conversas que o WhatsApp permite iniciar a partir deste número (o 'tier' da conta). Útil para acompanhar aquecimento e evitar bloqueio por excesso de disparos.

**Exemplo de resposta:**
```json
{}
```

---

## Enviar Mensagens

### POST /send/carousel
**Enviar Carrossel**

Envia um carrossel de cartões com imagem e botões de ação. Cada item do array `carousel` representa um cartão com `text`, `image` e `buttons: [{type,text,id}]`.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `text` (obrigatório): Texto principal da mensagem (ex: `Confira nossas opções:`)
- `carousel` (obrigatório): Cartões (JSON array) (ex: `[{"text":"Produto 1","image":"https://exemplo.com/img.jpg","buttons":[{"type":"REPLY","text":"Quero!","id":"quero"}]}]`)
- `delay` (opcional): Delay (ms) (ex: `1200`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/contact
**Enviar Contato (vCard)**

Envia um cartão de contato (vCard) com nome e telefone.

**Body (JSON):**
- `number` (obrigatório): Número do destinatário (ex: `5511999999999`)
- `fullName` (obrigatório): Nome completo do contato (ex: `João Silva`)
- `phoneNumber` (obrigatório): Telefones (separados por vírgula) (ex: `5511999999999,5511888888888`)
- `organization` (opcional): Empresa / Organização (ex: `Empresa XYZ`)
- `email` (opcional): E-mail do contato (ex: `joao@empresa.com`)
- `delay` (opcional): Delay (ms) (ex: `1200`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/location
**Enviar Localização**

Envia uma localização geográfica com pin no mapa. O destinatário pode abrir no Google Maps ou Apple Maps diretamente.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `latitude` (obrigatório): Latitude (ex: `-23.5505`)
- `longitude` (obrigatório): Longitude (ex: `-46.6333`)
- `name` (opcional): Nome do local (ex: `Sede da empresa`)
- `address` (opcional): Endereço (ex: `Av. Paulista, 1000 - São Paulo`)
- `delay` (opcional): Delay (ms) (ex: `1200`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/location-button
**Solicitar Localização**

Envia uma mensagem com botao que pede a localizacao do usuario. O botao de compartilhar localizacao e adicionado automaticamente.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `text` (obrigatório): Texto da mensagem (ex: `Compartilhe sua localização para entregarmos seu pedido:`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/media
**Enviar Mídia**

Envia um arquivo de mídia para um contato. O arquivo deve estar acessível em uma URL pública.

Tipos disponíveis:
• image: Imagem (JPG, PNG, GIF, WebP). Suporta legenda via text.
• video: Vídeo (MP4, AVI, MOV). Suporta legenda via text.
• audio: Áudio como arquivo (MP3, OGG, WAV). Aparece com ícone de arquivo de áudio.
• ptt: Push-to-Talk: áudio que aparece como mensagem de voz (bolha de microfone). Ideal para humanizar automações.
• myaudio: Áudio nativo do WhatsApp (OGG/Opus). Semelhante ao ptt, use quando já tiver o arquivo no formato correto.
• ptv: Recado de vídeo (nota de vídeo redonda). Chega sempre em formato circular; vídeo 16:9 é cortado no centro. Ignora legenda (o campo text não aparece). Use MP4 H.264. Aceita durações longas (testado 15 a 180 s) e tamanho dentro do limite de mídia.
• document: Documento (PDF, DOCX, XLSX, etc.). Use docName para definir o nome exibido no chat.
• sticker: Figurinha animada ou estática (WebP).

Limite de tamanho (envio por URL): imagem, vídeo e áudio até ~190 MB; documento até ~500 MB. Acima disso o WhatsApp recusa (HTTP 413 / erro de upload). Observação: ao enviar o arquivo em base64 no corpo da requisição pela API pública (/api/v1), o limite cai para ~2 MB. Por isso, para arquivos maiores, sempre envie por URL.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `type` (obrigatório): Tipo de Mídia (valores: image, video, videoplay, audio, ptt, myaudio, ptv, document, sticker)
- `file` (obrigatório): URL do Arquivo (ex: `https://...`)
- `text` (opcional): Legenda: imagens e vídeos (ex: `Descrição da mídia`)
- `mentions` (opcional): Marcar membros (somente grupo) (ex: `all`)
- `docName` (opcional): Nome do arquivo: obrigatório para document (ex: `arquivo.pdf`)
- `delay` (opcional): Delay (ms) (ex: `1200`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/buttons
**Enviar Botões de Resposta**

Envia botões clicáveis (até 3). Cada objeto do array `buttons` vira um tipo diferente de botão conforme o campo usado:

• `text` + `id` → botão de resposta rápida (contato clica, envia o texto)
• `text` + `url` → botão que abre link externo
• `text` + `phone` → botão de ligação
• `text` + `copy` → botão que copia código pra área de transferência

Sem `image`, a mensagem sai só com texto + botões (header limpo). Com `image`, aparece uma imagem no topo. Limitação WhatsApp: misturar reply com url/phone/copy na mesma mensagem pode exibir aviso 'Abra no celular'.

**Body (JSON):**
- `number` (obrigatório): Número do destinatário (com DDI) (ex: `5511999999999`)
- `text` (obrigatório): Texto da mensagem (ex: `Como podemos ajudar?`)
- `buttons` (obrigatório): Botões (até 3). Use text+id para reply, text+url para link, text+phone para ligar, text+copy para copiar código (ex: `[{"text":"Sim","id":"yes"},{"text":"Nosso site","url":"https://exemplo.com"},{"text":"Ligar","phone":"+5511999999999"}]`)
- `image` (opcional): URL da imagem no topo (opcional) (ex: `https://exemplo.com/banner.jpg`)
- `footer` (opcional): Texto do rodapé (opcional) (ex: `Escolha uma opção`)
- `delay` (opcional): Atraso em ms antes de enviar (opcional) (ex: `1200`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageType": "InteractiveMessage",
  "status": "Pending"
}
```

---

### POST /send/list
**Enviar Lista de Opções**

Envia menu em lista com seções e itens selecionáveis. O contato toca no botão e escolhe uma opção.

**Body (JSON):**
- `number` (obrigatório): Número do destinatário (ex: `5511999999999`)
- `text` (obrigatório): Texto principal (ex: `Escolha uma opção:`)
- `choices` (obrigatório): Opções: use "[Seção]" para cabeçalho e "Item|id|descrição" para cada item (ex: `["[Produtos]","Camiseta|p1|R$ 50","Calça|p2|R$ 120"]`)
- `listButton` (opcional): Texto do botão que abre a lista (ex: `Ver opções`)
- `footerText` (opcional): Rodapé (opcional)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageType": "ListMessage",
  "status": "Pending"
}
```

---

### POST /send/poll
**Enviar Enquete**

Envia enquete nativa do WhatsApp. Contatos votam e o resultado chega via webhook.

Enquete (type poll): use choices (lista de opções) e selectableCount (quantas o usuário pode marcar; >1 = múltipla escolha). O WhatsApp aceita 12+ opções. Os votos chegam pelo webhook de mensagens como PollUpdateMessage com o campo vote já decifrado (texto da opção); em múltipla escolha vem a lista das opções atuais separada por vírgula, e voto removido vem vazio.

**Body (JSON):**
- `number` (obrigatório): Número do destinatário (ex: `5511999999999`)
- `text` (obrigatório): Pergunta da enquete (ex: `Qual o melhor dia?`)
- `choices` (obrigatório): Opções de voto (array de strings) (ex: `["Segunda","Terça","Quarta"]`)
- `selectableCount` (opcional): Votos permitidos por pessoa (0 = ilimitado)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageType": "PollCreationMessage",
  "status": "Pending"
}
```

---

### POST /send/pix-button
**Enviar Botão PIX**

Envia um botão de pagamento PIX nativo do WhatsApp. O contato pode copiar a chave e pagar diretamente.

**Body (JSON):**
- `number` (obrigatório): ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`). (ex: `5511999999999`)
- `pixType` (obrigatório): Tipo da chave PIX. Valores aceitos: CPF, CNPJ, PHONE, EMAIL ou EVP (valores: EMAIL, CPF, CNPJ, PHONE, EVP) (ex: `EVP`)
- `pixKey` (obrigatório): Valor da chave PIX (CPF/CNPJ/telefone/email/EVP) (ex: `123e4567-e89b-12d3-a456-426614174000`)
- `pixName` (opcional): Nome exibido como recebedor do PIX (padrão "Pix" se vazio) (ex: `Loja Exemplo`)
- `async` (opcional): Enfileira o envio para processamento assíncrono (valores: true, false)
- `delay` (opcional): Atraso em milissegundos antes do envio (exibe "digitando..." no WhatsApp) (ex: `1200`)
- `readchat` (opcional): Marca o chat como lido após enviar a mensagem (valores: true, false)
- `readmessages` (opcional): Marca mensagens recentes como lidas após o envio (valores: true, false)
- `replyid` (opcional): ID da mensagem que será respondida
- `mentions` (opcional): Lista de números mencionados separados por vírgula
- `track_source` (opcional): Origem de rastreamento (ex.: chatwoot, crm-interno)
- `track_id` (opcional): Identificador de rastreamento (aceita valores duplicados)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/request-payment
**Solicitar Pagamento**

Envia uma solicitação de pagamento com o botão nativo "Revisar e pagar" do WhatsApp. É obrigatório enviar pelo menos um método de pagamento: `pixKey`, `boletoCode`, `paymentLink` ou `allowCards: true`. Sem isso, a API retorna erro.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `amount` (obrigatório): Valor (BRL) (ex: `49.90`)
- `pixKey` (opcional): Chave PIX (CPF/CNPJ/telefone/email/EVP) (ex: `123e4567-e89b-12d3-a456-426614174000`)
- `pixType` (opcional): Tipo da chave PIX (valores: EVP, CPF, CNPJ, PHONE, EMAIL)
- `itemName` (opcional): Nome do item (ex: `Assinatura Plano Ouro`)
- `invoiceNumber` (opcional): Número da fatura (ex: `PED-123`)
- `title` (opcional): Título do fluxo (ex: `Detalhes do pedido`)
- `footer` (opcional): Rodapé (ex: `Loja Exemplo`)
- `pixName` (opcional): Nome do recebedor (padrão: nome do perfil) (ex: `Loja Exemplo`)
- `text` (opcional): Texto da mensagem (ex: `Pagamento referente ao pedido #123`)
- `paymentLink` (opcional): Link de pagamento externo (ex: `https://pagamento.exemplo.com/123`)
- `fileUrl` (opcional): URL de arquivo anexo (ex: `https://...`)
- `fileName` (opcional): Nome do arquivo anexo (ex: `boleto.pdf`)
- `boletoCode` (opcional): Código do boleto (ex: `34191.79001 01043.510047 91020.150008 8 87350026000`)
- `allowCards` (opcional): Permitir cartão (valores: true, false)
- `currency` (opcional): Moeda (ex: `BRL`)
- `note` (opcional): Nota / Observação (ex: `Pagamento referente ao pedido #123`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/status
**Enviar Status / Story**

Publica um status/story no WhatsApp (texto, imagem ou vídeo). Visível para todos os contatos por 24 horas.

**Body (JSON):**
- `type` (obrigatório): Tipo (valores: text, image, video, audio, ptt)
- `text` (opcional): Texto (para tipo texto) (ex: `Olá mundo!`)
- `background_color` (opcional): Cor de fundo (apenas tipo texto) (valores: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19)
- `font` (opcional): Fonte (apenas tipo texto) (valores: 0, 1, 2, 3, 4, 5, 6, 7, 8)
- `file` (opcional): URL do arquivo (imagem/vídeo/áudio) (ex: `https://...`)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

### POST /send/text
**Enviar Texto**

Envia uma mensagem de texto simples para um número de WhatsApp. O número deve incluir o código do país (DDI), por exemplo: 5511999999999.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `text` (obrigatório): Mensagem (ex: `Olá! Tudo bem?`)
- `mentions` (opcional): Marcar membros (somente grupo) (ex: `all`)
- `delay` (opcional): Delay (ms) (ex: `1200`)
- `replyid` (opcional): ID da mensagem a responder (ex: `ABCDEF123456`)
- `digitando` (opcional): Exibe "digitando..." automatico proporcional ao tamanho da mensagem antes de enviar. Ligado por padrao (humaniza e reduz risco de bloqueio). Envie false para desligar e responder mais rapido. A resposta continua sincrona. (valores: true, false)

**Exemplo de resposta:**
```json
{
  "messageId": "ABCDEF123456",
  "status": "sent"
}
```

---

## Conversas

### POST /chat/archive
**Arquivar Chat**

Arquiva uma conversa, ocultando-a da lista principal do WhatsApp.

**Body (JSON):**
- `number` (obrigatório): Número ou JID do chat (ex: `5511999999999@s.whatsapp.net`)
- `archive` (obrigatório): Arquivar (valores: true, false)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /chat/block
**Bloquear / Desbloquear Contato**

⚠️ ATENÇÃO: Bloqueia um contato. NÃO use block: false . isso pode DESCONECTAR a instância inteira (bug conhecido da WhatsApp). Para desbloquear, use o próprio WhatsApp.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `block` (obrigatório): Ação (valores: true, false)

**Exemplo de resposta:**
```json
{
  "response": "Blocked successfully",
  "blockList": [
    "5511999999999@s.whatsapp.net"
  ]
}
```

---

### GET /chat/blocklist
**Lista de Bloqueados**

Retorna todos os contatos bloqueados pela instância.

**Exemplo de resposta:**
```json
{
  "blocked": [
    "5511999999999@s.whatsapp.net"
  ]
}
```

---

### POST /chat/delete
**Deletar Chat**

Deleta um chat inteiro. Pode limpar apenas no app ou também no banco de dados.

**Body (JSON):**
- `number` (obrigatório): Número do chat no formato internacional.
Para grupos use o ID completo do grupo.
 (ex: `5511999999999`)
- `deleteChatDB` (opcional): Se true, deleta o chat do banco de dados (valores: true, false) (ex: `True`)
- `deleteMessagesDB` (opcional): Se true, deleta todas as mensagens do chat do banco de dados (valores: true, false) (ex: `True`)
- `deleteChatWhatsApp` (opcional): Se true, deleta o chat do WhatsApp.
Para grupos, esta operação não é permitida e o chat será apenas limpo.
 (valores: true, false) (ex: `True`)
- `clearChatWhatsApp` (opcional): Se true, limpa a conversa do chat no WhatsApp (sem sair do chat).
Funciona para grupos e conversas individuais.
 (valores: true, false) (ex: `True`)

**Exemplo de resposta:**
```json
{
  "actions": [],
  "response": "Chat deletion process completed"
}
```

---

### POST /chat/find
**Buscar Chats**

Busca chats com filtros avançados: por nome, label, status, grupo, e mais.

**Body (JSON):**
- `operator` (opcional): Operador lógico entre os filtros (valores: AND, OR)
- `sort` (opcional): Ordenação (+/- campo, ex: -wa_lastMsgTimestamp) (ex: `-wa_lastMsgTimestamp`)
- `limit` (opcional): Quantidade máxima de resultados a retornar
- `offset` (opcional): Número de registros a pular (para paginação)
- `wa_fastid` (opcional): ID interno do chat
- `wa_chatid` (opcional): ID do chat no WhatsApp
- `wa_archived` (opcional): Arquivado? (valores: true, false)
- `wa_contactName` (opcional): Nome do contato
- `wa_name` (opcional): Nome no WhatsApp
- `name` (opcional): Nome
- `wa_isBlocked` (opcional): Bloqueado? (valores: true, false)
- `wa_isGroup` (opcional): É grupo? (valores: true, false)
- `wa_isGroup_admin` (opcional): É admin do grupo? (valores: true, false)
- `wa_isGroup_announce` (opcional): Grupo apenas admins? (valores: true, false)
- `wa_isGroup_member` (opcional): É membro do grupo? (valores: true, false)
- `wa_isPinned` (opcional): Fixado? (valores: true, false)
- `wa_label` (opcional): ID da label aplicada ao chat. Use o valor retornado por `/labels`, não o nome da etiqueta.
- `wa_notes` (opcional): Tem notas?
- `lead_tags` (opcional): Tags do lead
- `lead_isTicketOpen` (opcional): Ticket aberto? (valores: true, false)
- `lead_assignedAttendant_id` (opcional): ID do atendente
- `lead_status` (opcional): Status do lead

**Exemplo de resposta:**
```json
{
  "chats": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "name": "João",
      "unreadCount": 3
    }
  ]
}
```

---

### POST /chat/mute
**Silenciar Chat**

Silencia notificações de uma conversa por um período em milissegundos. Exemplo: 86400000 = 24h.

**Body (JSON):**
- `number` (obrigatório): Número ou JID do chat (ex: `5511999999999@s.whatsapp.net`)
- `duration` (opcional): Duração (ms): ex: 86400000 = 24h (ex: `86400000`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /chat/notes
**Ver Notas do Chat**

Retorna as notas internas (privadas) associadas a um chat.

**Body (JSON):**
- `number` (opcional): JID completo do chat (ex: `5511999999999@s.whatsapp.net`)

**Exemplo de resposta:**
```json
{
  "notes": "Notas internas do chat"
}
```

---

### POST /chat/notes/edit
**Editar Notas do Chat**

Edita as notas internas de um chat. Notas são visíveis apenas para você.

**Body (JSON):**
- `number` (opcional): JID completo do chat (ex: `5511999999999@s.whatsapp.net`)
- `notes` (opcional): Conteúdo da nota a persistir no chat (ex: `Cliente prefere contato no período da tarde`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /chat/notes/refresh
**Recarregar Notas**

Recarrega as notas internas do WhatsApp para o banco local.

**Body (JSON):**
- `number` (opcional): JID completo do chat (ex: `5511999999999@s.whatsapp.net`)
- `force` (opcional): Tente primeiro com `false`.
Use `true` apenas quando a recarga padrão não funcionar bem,
pois esse modo faz uma nova leitura mais completa das notas.
 (valores: true, false) (ex: `False`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /chat/pin
**Fixar / Desfixar Chat**

Fixa ou desfixa uma conversa no topo da lista de chats do WhatsApp.

**Body (JSON):**
- `number` (obrigatório): Número ou JID do chat (ex: `5511999999999@s.whatsapp.net`)
- `pin` (obrigatório): Ação (valores: true, false)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /chat/read
**Marcar Chat como Lido**

Marca todas as mensagens não lidas de uma conversa como lidas, zerando o contador de não lidas.

**Body (JSON):**
- `number` (obrigatório): Número ou JID do chat (ex: `5511999999999@s.whatsapp.net`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /message/delete
**Deletar Mensagem**

Apaga uma mensagem enviada para todos os participantes do chat. So e possivel deletar mensagens enviadas pela propria instancia.

**Body (JSON):**
- `id` (obrigatório): ID da mensagem (ex: `ABCDEF123456`)
- `number` (opcional): Número do destinatário (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "Timestamp": "2026-04-06T04:50:40Z",
  "ID": "3EB0C6074918E013090475",
  "Sender": "..."
}
```

---

### POST /message/download
**Download de Mídia**

Faz o download de uma mídia recebida (imagem, vídeo, áudio, documento) a partir do ID da mensagem. O campo `id` deve vir do webhook ou do endpoint `/message/find`. Obs: o parâmetro transcribe é best-effort e pode não retornar a transcrição. Para transcrição garantida de áudios, use o módulo de IA.

**Body (JSON):**
- `id` (obrigatório): ID da mensagem (ex: `7EB0F01D7244B421048F0706368376E0`)
- `return_link` (opcional): Retornar URL pública do arquivo (valores: true, false)
- `return_base64` (opcional): Retornar arquivo em base64 (valores: false, true)
- `generate_mp3` (opcional): Para áudios: retornar como MP3 (false = OGG) (valores: true, false)
- `transcribe` (opcional): Transcrever áudio (best-effort: pode não retornar texto) (valores: false, true)

**Exemplo de resposta:**
```json
{
  "fileURL": "https://server.example.com/files/abc123.jpg",
  "mimetype": "image/jpeg"
}
```

---

### POST /message/edit
**Editar Mensagem**

Edita o texto de uma mensagem previamente enviada. Aparece com indicador de editada para o destinatario. So funciona com mensagens enviadas pela propria instancia.

**Body (JSON):**
- `id` (obrigatório): ID da mensagem (ex: `ABCDEF123456`)
- `number` (obrigatório): Número do destinatário (ex: `5511999999999`)
- `text` (obrigatório): Novo texto (ex: `Texto corrigido...`)

**Exemplo de resposta:**
```json
{
  "id": "3EB0BB655F4F2AFA22FDE3",
  "messageType": "ExtendedTextMessage",
  "messageTimestamp": 1775450980468,
  "status": "Pending"
}
```

---

### POST /message/find
**Histórico de Mensagens**

Retorna o histórico de mensagens da instância. Filtre por `chatid` para buscar mensagens de uma conversa específica. Suporta paginação via `limit` e `offset`.

**Body (JSON):**
- `chatid` (opcional): ID do chat (JID) (ex: `5511999999999@s.whatsapp.net`)
- `id` (opcional): ID de mensagem específica (ex: `ABCDEF123456`)
- `limit` (opcional): Limite (padrão: 100) (ex: `100`)
- `offset` (opcional): Offset (paginação) (ex: `0`)

**Exemplo de resposta:**
```json
{
  "messages": [],
  "total": 0
}
```

---

### POST /message/history-sync
**Sincronizar Histórico**

Solicita sincronizacao de historico de mensagens antigas de um chat. As mensagens chegam via webhook/SSE.

**Body (JSON):**
- `messageid` (opcional): ID da mensagem de referência usada para buscar mensagens mais antigas do chat (ex: `3EB01234567890ABCDEF`)
- `number` (opcional): JID completo do chat (ex: `5511999999999@s.whatsapp.net`)
- `count` (opcional): Quantidade desejada de mensagens no sync (ex: `20`)

**Exemplo de resposta:**
```json
{
  "ok": true,
  "count": 50
}
```

---

### POST /message/markread
**Marcar como Lida**

Marca uma ou mais mensagens como lidas. Envie um array de IDs.

**Body (JSON):**
- `id` (obrigatório): IDs das mensagens (ex: `["3EB0538DA65A59F6D8A251"]`)

**Exemplo de resposta:**
```json
{
  "results": [
    {
      "message_id": "5511999990001:3EB0CECA26BF34A157FC71",
      "status": "success"
    }
  ]
}
```

---

### POST /message/presence
**Indicador de Digitando...**

Mostra "digitando..." ou "gravando áudio..." para o contato. O indicador some automaticamente após alguns segundos.

**Body (JSON):**
- `number` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `presence` (obrigatório): Tipo (valores: composing, recording, paused)
- `delay` (opcional): Duração (ms, máx. 300000) (ex: `3000`)

**Exemplo de resposta:**
```json
{
  "response": "ok"
}
```

---

### POST /message/react
**Reagir com Emoji**

Envia uma reação (emoji) a uma mensagem existente. Envie emoji vazio para REMOVER a reação. O id deve ser o messageId achatado no formato OWNER:MSGID (ex: 5511999990003:2A6E2F02CE4125FDBA1B): não use o formato Baileys concatenado com JID, vai dar 404. O webhook de confirmação chega com messageType=ReactionMessage e inclui o atalho 'reaction' no envelope.

**Body (JSON):**
- `number` (obrigatório): Número do contato (ex: `5511999999999`)
- `id` (obrigatório): ID da mensagem (formato OWNER:MSGID) (ex: `5511999990003:2A6E2F02CE4125FDBA1B`)
- `emoji` (obrigatório): Emoji da reação (vazio = remover): alias: text (ex: `👍`)

**Exemplo de resposta:**
```json
{
  "messageType": "ReactionMessage",
  "status": "Pending"
}
```

---

### POST /chat/ephemeral
**Mensagens Temporárias (conversa privada)**

Liga ou desliga as mensagens temporárias (que somem sozinhas) numa conversa privada. Vale para as próximas mensagens da conversa. Duração em segundos, seguindo o padrão do WhatsApp: 0 desliga, 86400 = 24 horas, 604800 = 7 dias, 7776000 = 90 dias.

**Body (JSON):**
- `number` (obrigatório): Número do contato (com DDI) (ex: `5511999999999`)
- `duration` (obrigatório): Duração antes de sumir (valores: 0, 86400, 604800, 7776000)

**Exemplo de resposta:**
```json
{
  "status": "success"
}
```

---

## Contatos & Perfil

### POST /chat/check
**Verificar Número**

Verifica se um ou mais numeros estao registrados no WhatsApp. Retorna JID, nome verificado e status.

**Body (JSON):**
- `numbers` (obrigatório): Números para verificar (array) (ex: `["5511999999999", "5521888888888"]`)

**Exemplo de resposta:**
```json
[
  {
    "query": "5511999999999",
    "isInWhatsapp": true,
    "jid": "5511999999999@s.whatsapp.net"
  }
]
```

---

### POST /chat/details
**Detalhes do Contato**

Retorna detalhes completos de um contato: nome, foto, status, verificação, e-commerce.

**Body (JSON):**
- `number` (obrigatório): Número do telefone ou ID do grupo (ex: `5511999999999`)
- `preview` (opcional): Controla o tamanho da imagem de perfil retornada:
- `true`: Retorna imagem em tamanho preview (menor, otimizada para listagens)
- `false` (padrão): Retorna imagem em tamanho full (resolução original, maior qualidade)
 (valores: true, false)

**Exemplo de resposta:**
```json
{
  "jid": "5511999999999@s.whatsapp.net",
  "name": "João",
  "pushName": "João Silva",
  "profilePicUrl": "https://..."
}
```

---

### POST /contact/add
**Adicionar Contato**

Adiciona um novo contato à agenda do WhatsApp conectado com nome e número.

**Body (JSON):**
- `phone` (obrigatório): Telefone (com DDI) (ex: `5511999999999`)
- `name` (obrigatório): Nome completo (ex: `João Silva`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /contact/remove
**Remover Contato**

Remove um contato da agenda do WhatsApp.

**Body (JSON):**
- `number` (obrigatório): Número de telefone no formato internacional com código do país obrigatório. 
Para Brasil, deve começar com 55. Aceita variações com/sem símbolo +, 
com/sem parênteses, com/sem hífen e com/sem espaços. Também aceita formato 
JID do WhatsApp (@s.whatsapp.net). Não aceita contatos comerciais (@lid) 
nem grupos (@g.us).
 (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### GET /contacts
**Listar Contatos (Rápido)**

Lista todos os contatos salvos na agenda do WhatsApp.

**Exemplo de resposta:**
```json
[
  {
    "jid": "5511999999999@s.whatsapp.net",
    "name": "João"
  }
]
```

---

### POST /contacts/list
**Listar Contatos**

Busca contatos com paginacao. Use limit e offset para navegar.

**Body (JSON):**
- `limit` (opcional): Limite (ex: `50`)
- `offset` (opcional): Offset (ex: `0`)

**Exemplo de resposta:**
```json
{
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "contact_name": "João Silva"
    }
  ]
}
```

---

### POST /profile/image
**Alterar Foto**

Altera a imagem de perfil da sua instancia. Envie URL, base64 ou "remove" para remover.

**Body (JSON):**
- `image` (obrigatório): URL, base64 ou "remove" (ex: `https://exemplo.com/logo.jpg`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /profile/name
**Alterar Nome**

Altera o nome do perfil da sua instancia no WhatsApp.

**Body (JSON):**
- `name` (obrigatório): Novo nome (máx. 25 caracteres) (ex: `Minha Empresa`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

## Grupos

### POST /community/create
**Criar Comunidade**

Cria uma Comunidade do WhatsApp, estrutura que agrupa multiplos grupos sob um mesmo canal de anuncios central. O numero conectado sera o dono da comunidade.

**Body (JSON):**
- `name` (obrigatório): Nome da comunidade (ex: `Comunidade da Empresa`)
- `description` (opcional): Descrição (ex: `Descrição da comunidade`)
- `participants` (opcional): Participantes (números com DDI) (ex: `["5511999999999"]`)

**Exemplo de resposta:**
```json
{
  "JID": "120363000000000001@g.us",
  "Name": "Comunidade da Empresa",
  "IsParent": true,
  "DefaultSubGroupId": "120363000000000002@g.us",
  "Participants": [
    {
      "JID": "...",
      "IsAdmin": true,
      "IsSuperAdmin": true
    }
  ]
}
```

---

### POST /community/editgroups
**Gerenciar Grupos da Comunidade**

Adiciona ou remove grupos de uma comunidade existente. Use action: add ou action: remove com o array de JIDs de grupos.

**Body (JSON):**
- `community` (obrigatório): JID da comunidade (ex: `120363000000000001@g.us`)
- `action` (obrigatório): Ação (valores: add, remove)
- `groups` (obrigatório): JIDs dos grupos (JSON array) (ex: `["120363000000000000@g.us"]`)

**Exemplo de resposta:**
```json
{
  "failed": null,
  "message": "community updated",
  "success": null
}
```

---

### POST /group/create
**Criar Grupo**

Cria um novo grupo do WhatsApp com os participantes indicados. O número conectado é automaticamente adicionado como administrador. Nome: mín. 1, máx. 100 caracteres. Máximo de 50 participantes.

**Body (JSON):**
- `name` (obrigatório): Nome do Grupo (ex: `Meu Time`)
- `participants` (obrigatório): Participantes (JSON array de números com DDI) (ex: `["5511999990001","5511999990002"]`)

**Exemplo de resposta:**
```json
{
  "groupJID": "120363000000000000@g.us",
  "success": true
}
```

---

### POST /group/info
**Informações do Grupo**

Retorna detalhes completos de um grupo: nome, descrição, participantes, admins, data de criação e configurações. Use `getInviteLink: true` para incluir o link de convite na resposta.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `getInviteLink` (opcional): Incluir link de convite (valores: false, true)

**Exemplo de resposta:**
```json
{
  "id": "120363000000000000@g.us",
  "name": "Meu Grupo",
  "description": "Descrição",
  "inviteLink": "https://chat.whatsapp.com/...",
  "participants": [
    {
      "id": "5511...@s.whatsapp.net",
      "isAdmin": true
    }
  ]
}
```

---

### POST /group/inviteInfo
**Info pelo Convite**

Obtem informacoes de um grupo pelo codigo ou link de convite.

**Body (JSON):**
- `invitecode` (obrigatório): Código de convite ou URL completo do grupo.
Pode ser um código curto ou a URL completa do WhatsApp.


**Exemplo de resposta:**
```json
{
  "jid": "120363000000000000@g.us",
  "name": "Meu Grupo",
  "size": 15
}
```

---

### POST /group/join
**Entrar em Grupo via Link**

Faz a instância entrar em um grupo utilizando um link de convite do WhatsApp. Aceita a URL completa (https://chat.whatsapp.com/...) ou apenas o código.

**Body (JSON):**
- `invitecode` (obrigatório): Código ou URL de convite (ex: `https://chat.whatsapp.com/XXXXXXXXXXXXXXXX`)

**Exemplo de resposta:**
```json
{
  "success": true,
  "groupJID": "120363000000000000@g.us"
}
```

---

### POST /group/leave
**Sair do Grupo**

Remove o número conectado do grupo especificado. Esta ação não pode ser desfeita pelo sistema. Funciona também para sair de comunidades.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)

**Exemplo de resposta:**
```json
{
  "response": "Group leave successful"
}
```

---

### GET /group/list
**Listar Grupos**

Lista todos os grupos do WhatsApp. Retorna array com JID, nome e dados de cada grupo.

**Exemplo de resposta:**
```json
{
  "groups": [
    {
      "id": "120363000000000000@g.us",
      "name": "Meu Grupo"
    }
  ]
}
```

---

### POST /group/list
**Buscar Grupos**

Lista grupos com opcao de incluir participantes. Retorna objeto com array "groups".

**Body (JSON):**
- `getParticipants` (opcional): Incluir participantes (valores: false, true)

**Exemplo de resposta:**
```json
{}
```

---

### POST /group/resetInviteCode
**Resetar Código de Convite**

Gera um novo codigo de convite para o grupo. O link anterior sera invalidado.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)

**Exemplo de resposta:**
```json
{
  "InviteLink": "https://chat.whatsapp.com/YYYYYYYYYYYYYYYY"
}
```

---

### POST /group/updateAnnounce
**Modo Somente Admins**

Ativa ou desativa o modo em que apenas administradores podem enviar mensagens. Ideal para canais de comunicação unidirecional.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `announce` (obrigatório): Somente admins (valores: true, false)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/updateDescription
**Alterar Descrição do Grupo**

Altera a descricao do grupo. Descricao vazia nao e permitida.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `description` (obrigatório): Nova descrição (máx. 512 caracteres) (ex: `Descrição do grupo...`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/updateImage
**Alterar Foto do Grupo**

Altera a imagem do grupo. Envie URL da imagem ou "remove" para remover.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `image` (obrigatório): URL, base64 ou "remove" (ex: `https://exemplo.com/foto.jpg ou "remove"`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/updateLocked
**Bloquear Edição do Grupo**

Quando ativado, apenas administradores podem alterar nome, foto e descrição do grupo.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `locked` (obrigatório): Bloquear edição (valores: true, false)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/updateName
**Renomear Grupo**

Altera o nome de exibição do grupo. Mín. 1 e máx. 25 caracteres. Requer que o número conectado seja administrador.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `name` (obrigatório): Novo nome (máx. 25 caracteres) (ex: `Nome do grupo`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/updateParticipants
**Gerenciar Participantes**

Gerencia participantes do grupo. Adicionar, remover, promover ou rebaixar.

**Body (JSON):**
- `groupjid` (obrigatório): ID do Grupo (@g.us) (ex: `120363000000000000@g.us`)
- `action` (obrigatório): Ação (valores: add, remove, promote, demote, approve, reject)
- `participants` (obrigatório): Participantes (JSON array de números com DDI) (ex: `["5511999990003"]`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /group/ephemeral
**Mensagens Temporárias (grupo)**

Liga ou desliga as mensagens temporárias no grupo. Duração em segundos, padrão do WhatsApp: 0 desliga, 86400 = 24 horas, 604800 = 7 dias, 7776000 = 90 dias.

**Body (JSON):**
- `groupjid` (obrigatório): JID do grupo (ex: `120363123456789012@g.us`)
- `duration` (obrigatório): Duração antes de sumir (valores: 0, 86400, 604800, 7776000)

**Exemplo de resposta:**
```json
{
  "status": "success"
}
```

---

### POST /group/updateJoinApproval
**Exigir Aprovação para Entrar**

Define se a entrada de novos membros no grupo precisa da aprovação de um administrador.

**Body (JSON):**
- `groupjid` (obrigatório): JID do grupo (ex: `120363123456789012@g.us`)
- `IsJoinApprovalRequired` (obrigatório): Exigir aprovação para entrar (valores: true, false)

**Exemplo de resposta:**
```json
{
  "status": "success"
}
```

---

### POST /group/updateMemberAddMode
**Quem Pode Adicionar Membros**

Define quem pode adicionar novos membros ao grupo: só administradores ou qualquer participante.

**Body (JSON):**
- `groupjid` (obrigatório): JID do grupo (ex: `120363123456789012@g.us`)
- `MemberAddMode` (obrigatório): Quem pode adicionar (valores: admin_add, all_member_add)

**Exemplo de resposta:**
```json
{
  "status": "success"
}
```

---

## Newsletters & Canais

### POST /newsletter/admin/accept
**Aceitar Convite de Admin**

Aceita um convite para ser admin de um canal.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/admin/invite
**Convidar Admin do Canal**

Convida um número para ser admin de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `phone` (obrigatório): Número (com DDI) (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/admin/remove
**Remover Admin do Canal**

Remove um admin de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `phone` (obrigatório): Número (com DDI) (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/admin/revoke
**Revogar Convite de Admin**

Revoga um convite de admin pendente. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `phone` (obrigatório): Número (com DDI) (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/create
**Criar Canal**

Cria um novo canal (newsletter) do WhatsApp.

**Body (JSON):**
- `name` (obrigatório): Nome (ex: `Canal de Promoções`)
- `description` (opcional): Descrição (ex: `Ofertas e novidades da loja`)
- `picture` (opcional): URL, base64 puro ou data URI da imagem do canal. (ex: `https://example.com/newsletter.png`)

**Exemplo de resposta:**
```json
{
  "id": "123",
  "jid": "120363...@newsletter"
}
```

---

### POST /newsletter/delete
**Deletar Canal**

Deleta um canal que você administra.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/description
**Alterar Descrição do Canal**

Atualiza a descrição de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `description` (opcional): Descrição (ex: `Atualizações, ofertas e novidades`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/follow
**Seguir Canal**

Segue um canal para receber suas publicações.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/info
**Info do Canal**

Obtém informações detalhadas de um canal.

**Body (JSON):**
- `id` (opcional): ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. (ex: `120363123456789012`)
- `jid` (opcional): JID completo do canal. (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "id": "123",
  "name": "Meu Canal",
  "description": "...",
  "subscribers": 150
}
```

---

### POST /newsletter/link
**Buscar Canal por Link**

Busca informações de um canal pelo link/chave de convite.

**Body (JSON):**
- `key` (obrigatório): Chave do convite do canal. (ex: `AbCdEfGhIjKlMn`)

**Exemplo de resposta:**
```json
{
  "id": "123",
  "name": "Canal",
  "jid": "120363...@newsletter"
}
```

---

### GET /newsletter/list
**Listar Canais**

Lista todos os canais em que a instância está inscrita.

**Exemplo de resposta:**
```json
{
  "newsletters": []
}
```

---

### POST /newsletter/messages
**Mensagens do Canal**

Busca mensagens publicadas em um canal.

**Body (JSON):**
- `id` (opcional): ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. (ex: `120363123456789012`)
- `jid` (opcional): JID completo do canal. (ex: `120363123456789012@newsletter`)
- `count` (opcional): Quantidade de mensagens/posts a buscar. (ex: `20`)
- `beforeid` (opcional): Retorna mensagens anteriores ao `serverid` informado.
Use para paginação retroativa.
 (ex: `12345`)

**Exemplo de resposta:**
```json
{
  "messages": []
}
```

---

### POST /newsletter/messages/delete
**Deletar Mensagem do Canal**

Deleta uma mensagem de um canal que você administra.

**Body (JSON):**
- `id` (opcional): ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. (ex: `120363123456789012`)
- `jid` (opcional): JID completo do canal. (ex: `120363123456789012@newsletter`)
- `messageid` (opcional): ID lógico da mensagem no canal. (ex: `3EB0B4302B3A8A52F7A1`)
- `serverid` (opcional): Identificador sequencial do post no canal. (ex: `12345`)
- `count` (opcional): Quantidade de mensagens buscadas por página ao localizar o post. (ex: `100`)
- `maxpages` (opcional): Quantidade máxima de páginas buscadas ao localizar o post. (ex: `5`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/messages/edit
**Editar Mensagem do Canal**

Edita uma mensagem recente de um canal que você administra.

**Body (JSON):**
- `id` (opcional): ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. (ex: `120363123456789012`)
- `jid` (opcional): JID completo do canal. (ex: `120363123456789012@newsletter`)
- `messageid` (opcional): ID lógico da mensagem no canal. (ex: `3EB0B4302B3A8A52F7A1`)
- `serverid` (opcional): Identificador sequencial do post no canal. (ex: `12345`)
- `text` (obrigatório): Novo texto ou nova legenda do post. (ex: `Post atualizado`)
- `count` (opcional): Quantidade de mensagens buscadas por página ao localizar o post. (ex: `100`)
- `maxpages` (opcional): Quantidade máxima de páginas buscadas ao localizar o post. (ex: `5`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/mute
**Silenciar Canal**

Silencia notificações de um canal.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/name
**Alterar Nome do Canal**

Atualiza o nome de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `name` (obrigatório): Nome (ex: `Canal de Promoções VIP`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/owner/transfer
**Transferir Dono do Canal**

Transfere a propriedade do canal para outro número.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `phone` (obrigatório): Número (com DDI) (ex: `5511999999999`)
- `quitAdmin` (opcional): Sair como admin após transferir (valores: true, false) (ex: `False`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/picture
**Alterar Foto do Canal**

Atualiza a foto de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `picture` (obrigatório): URL da imagem (ex: `https://example.com/newsletter.png`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/reaction
**Reagir a Post do Canal**

Reage a um post de um canal.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `serverid` (opcional): Server ID (número inteiro) (ex: `12345`)
- `reaction` (opcional): Emoji de reação (ex: `🔥`)
- `reactionmessageid` (opcional): ID da mensagem de reação (ex: `3EB0AABBCCDD`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/search
**Pesquisar Canais**

Pesquisa canais públicos por texto, país ou categoria.

**Body (JSON):**
- `limit` (opcional): Limite de resultados (ex: `20`)
- `view` (opcional): Tipo de visualização (ex: `RECOMMENDED`)
- `countryCodes` (opcional): Códigos de país (ex: `["BR"]`)
- `searchText` (opcional): Texto de busca (ex: `promo`)
- `after` (opcional): Cursor (paginação) (ex: `YXJyYXljb25uZWN0aW9uOjE5`)

**Exemplo de resposta:**
```json
{
  "results": []
}
```

---

### POST /newsletter/settings
**Configurações do Canal**

Atualiza configurações do canal (ex: códigos de reação permitidos). (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `reactionCodes` (obrigatório): Códigos de reação permitidos (ex: `basic`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/subscribe
**Assinar Updates do Canal**

Assina updates temporários de um canal para receber notificações.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/unfollow
**Deixar de Seguir**

Deixa de seguir um canal.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/unmute
**Reativar Canal**

Reativa notificações de um canal.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### POST /newsletter/updates
**Updates do Canal**

Busca atualizações de mensagens de um canal. (Nota: pode retornar erro GraphQL dependendo da versão da WhatsApp)

**Body (JSON):**
- `id` (opcional): ID numérico do canal. Se informado sem domínio, será convertido para `@newsletter`. (ex: `120363123456789012`)
- `jid` (opcional): JID completo do canal. (ex: `120363123456789012@newsletter`)
- `count` (opcional): Quantidade máxima de updates retornados. (ex: `50`)
- `afterid` (opcional): Retorna apenas updates posteriores ao `serverid` informado. (ex: `12345`)
- `since` (opcional): Timestamp de corte.
- Se maior que `1000000000000`, é interpretado como milissegundos.
- Caso contrário, é interpretado como segundos.
 (ex: `1710000000`)

**Exemplo de resposta:**
```json
{}
```

---

### POST /newsletter/viewed
**Marcar como Visualizado**

Marca posts do canal como visualizados.

**Body (JSON):**
- `id` (opcional): ID (ex: `120363123456789012`)
- `jid` (opcional): JID do canal/contato (ex: `120363123456789012@newsletter`)
- `serverids` (opcional): Server IDs (array de números inteiros, ex: [1, 2, 3]) (ex: `[1, 2, 3]`)

**Exemplo de resposta:**
```json
{}
```

---

## Campanhas

### POST /sender/advanced
**Disparar Campanha em Lote**

Dispara mensagens em lote com conteudo individualizado por destinatario. Cada item do array messages pode ter numero e texto diferentes.

**Body (JSON):**
- `messages` (obrigatório): Mensagens (array de objetos) (ex: `[{"number":"5511999999999","text":"Olá!"}]`)
- `delayMin` (opcional): Delay mínimo (segundos) (ex: `1`)
- `delayMax` (opcional): Delay máximo (segundos) (ex: `5`)
- `folder_id` (opcional): ID da pasta (ex: `folder_abc123`)
- `info` (opcional): Informacoes adicionais sobre a campanha (ex: `Campanha lancamento`)
- `scheduled_for` (opcional): Agendar para (timestamp em milissegundos ou minutos a partir de agora) (ex: `1`)

**Exemplo de resposta:**
```json
{
  "count": 1,
  "folder_id": "r5eb3b483c43f69",
  "status": "queued"
}
```

---

### DELETE /sender/clearall
**Limpar Toda a Fila**

Limpa toda a fila de mensagens, incluindo pendentes e em andamento.

**Exemplo de resposta:**
```json
{
  "folders_deleted": 0,
  "messages_deleted": 0,
  "status": "processed"
}
```

---

### POST /sender/cleardone
**Limpar Campanhas Concluídas**

Remove da lista todas as campanhas com status concluído dentro da pasta informada.

**Body (JSON):**
- `folder_id` (obrigatório): ID da pasta de campanha (ex: `folder_abc123`)

**Exemplo de resposta:**
```json
{
  "status": "cleanup started"
}
```

---

### POST /sender/edit
**Controlar Campanha**

Controla uma campanha de envio em massa: pausar, retomar ou cancelar.

**Body (JSON):**
- `folder_id` (obrigatório): Identificador único da campanha de envio (ex: `folder_123`)
- `action` (obrigatório): Ação na campanha (valores: stop, continue, delete) (ex: `stop`)

**Exemplo de resposta:**
```json
{
  "message": "Folder deletion has been initiated",
  "status": "deleting"
}
```

---

### GET /sender/listfolders
**Listar Campanhas**

Lista todas as campanhas/pastas de envio em massa. Retorna array direto.

**Exemplo de resposta:**
```json
[
  {
    "id": "r5819c9fba43b98",
    "info": "",
    "status": "scheduled",
    "scheduled_for": 1775449285668,
    "delayMax": 3,
    "delayMin": 1,
    "log_delivered": 0,
    "log_failed": 0,
    "log_played": 0,
    "log_read": 0,
    "log_sucess": 0,
    "log_total": 1,
    "owner": "5511999999999"
  }
]
```

---

### POST /sender/listmessages
**Listar Mensagens da Campanha**

Retorna as mensagens de uma campanha especifica com status de envio e paginacao.

**Body (JSON):**
- `folder_id` (obrigatório): ID da pasta de campanha (ex: `folder_abc123`)

**Exemplo de resposta:**
```json
{
  "messages": [
    {
      "id": "5511999990002:3EB01C21C13D0C4BA33F40",
      "chatid": "5511999990001@s.whatsapp.net",
      "status": "Sent",
      "text": "Teste",
      "messageType": "Conversation",
      "send_folder_id": "r5819c9fba43b98"
    }
  ],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "totalRecords": 1
  }
}
```

---

### POST /sender/simple
**Disparar Mensagem Simples**

Dispara uma mensagem para uma lista de numeros com delay aleatorio entre cada envio. Retorna um folder_id para acompanhamento.

**Body (JSON):**
- `numbers` (obrigatório): Números (JSON array) (ex: `["5511999999999","5511888888888"]`)
- `type` (obrigatório): Tipo da mensagem (valores: text, image, video, document, audio, contact, location)
- `text` (opcional): Texto da mensagem (ex: `Olá! Temos uma promoção...`)
- `file` (opcional): URL da mídia (se não for texto) (ex: `https://...`)
- `folder` (opcional): Nome da campanha (ex: `promo-abril`)
- `delayMin` (obrigatório): Delay mínimo (segundos) (ex: `1`)
- `delayMax` (obrigatório): Delay máximo (segundos) (ex: `5`)
- `scheduled_for` (opcional): Agendar para (timestamp em milissegundos) (ex: `1775534400000`)
- `info` (opcional): Informacoes adicionais sobre a campanha (ex: `Campanha Janeiro`)

**Exemplo de resposta:**
```json
{
  "count": 1,
  "folder_id": "r37d5cc380a7f31",
  "status": "queued"
}
```

---

## Chamadas

### POST /call/make
**Fazer Chamada**

Inicia uma chamada de voz para um numero do WhatsApp. A chamada toca no destino mas nao estabelece comunicacao de voz real.

**Body (JSON):**
- `number` (obrigatório): Número do contato no formato internacional (ex: 5511999999999) (ex: `5511999999999`)
- `call_duration` (opcional): Duracao da chamada em segundos. Apos esse tempo a chamada e encerrada automaticamente. (ex: `15`)

**Exemplo de resposta:**
```json
{
  "call": {
    "callCreator": "5511999@s.whatsapp.net",
    "wasSentByAPI": true
  },
  "response": "Call successful"
}
```

---

### POST /call/reject
**Rejeitar Chamada**

Rejeita uma chamada recebida.

**Body (JSON):**
- `number` (opcional): (Opcional) Número do contato no formato internacional (ex: 5511999999999) (ex: `5511999999999`)
- `id` (opcional): (Opcional) ID único da chamada a ser rejeitada

**Exemplo de resposta:**
```json
{
  "response": "Call rejected"
}
```

---

## WhatsApp Business

### POST /business/catalog/delete
**Deletar Produto do Catálogo**

Remove permanentemente produtos do catálogo do WhatsApp Business. Envie um array de IDs no campo `productIds`. Atenção: timeout (504) pode ocorrer se os IDs forem inválidos.

**Body (JSON):**
- `productIds` (obrigatório): IDs dos Produtos (array) (ex: `["prod_abc123"]`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

### POST /business/catalog/hide
**Ocultar Produto do Catálogo**

Oculta um produto do catálogo público sem removê-lo. ⚠️ Pode retornar erro 501 em contas que não suportam esta feature . é uma limitação do WhatsApp, não da API.

**Body (JSON):**
- `id` (obrigatório): ID do Produto (ex: `prod_abc123`)

**Exemplo de resposta:**
```json
{
  "response": "Product hidden"
}
```

---

### POST /business/catalog/info
**Info do Produto**

Retorna informações detalhadas de um produto específico do catálogo.

**Body (JSON):**
- `jid` (obrigatório): JID do catálogo a consultar (ex: `5511999999999@s.whatsapp.net`)
- `id` (obrigatório): O ID do produto.

**Exemplo de resposta:**
```json
{
  "id": "123",
  "name": "Produto",
  "price": 9990,
  "currency": "BRL"
}
```

---

### POST /business/catalog/list
**Listar Catálogo de Produtos**

Retorna todos os produtos cadastrados no catálogo do WhatsApp Business do JID informado.

**Body (JSON):**
- `jid` (obrigatório): JID do catálogo (ex: `5511999999999@s.whatsapp.net`)

**Exemplo de resposta:**
```json
{
  "response": [
    {
      "id": "prod_abc123",
      "name": "Produto 1",
      "price": "49.90",
      "currency": "BRL"
    }
  ]
}
```

---

### POST /business/catalog/show
**Exibir Produto no Catálogo**

Torna um produto visível no catálogo público do WhatsApp Business. ⚠️ Pode retornar erro 501 em contas que não suportam esta feature . é uma limitação do WhatsApp, não da API.

**Body (JSON):**
- `id` (obrigatório): ID do Produto (ex: `prod_abc123`)

**Exemplo de resposta:**
```json
{
  "response": "Product shown"
}
```

---

### GET /business/get/categories
**Listar Categorias Comerciais**

Retorna a lista de categorias disponíveis para o perfil comercial do WhatsApp Business.

**Exemplo de resposta:**
```json
{
  "categories": [
    {
      "id": "1",
      "name": "Shopping and Retail"
    }
  ]
}
```

---

### POST /business/get/profile
**Ver Perfil Comercial**

Retorna os dados do perfil comercial do WhatsApp Business: descrição, endereço, e-mail, site e categorias. Envie o `jid` com o número (sem @s.whatsapp.net). Obrigatório informar o número.

**Body (JSON):**
- `jid` (obrigatório): JID do contato (obrigatório, ex: 5511999999999@s.whatsapp.net) (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "response": {
    "description": "Loja de produtos...",
    "address": "Av. Paulista, 1000",
    "email": "contato@empresa.com"
  }
}
```

---

### POST /business/update/profile
**Atualizar Perfil Comercial**

Atualiza os dados do perfil do WhatsApp Business. É obrigatório enviar pelo menos um dos campos: `description`, `address` ou `email`. Atenção: este endpoint pode retornar 403 forbidden se a instância não for do tipo Business.

**Body (JSON):**
- `description` (opcional): Descrição (ex: `Especialistas em automação WhatsApp`)
- `address` (opcional): Endereço (ex: `Av. Paulista, 1000 - SP`)
- `email` (opcional): E-mail (ex: `contato@empresa.com`)
- `websites` (opcional): Sites (array) (ex: `["https://empresa.com"]`)

**Exemplo de resposta:**
```json
{
  "success": true
}
```

---

## Configurações

### POST /chat/labels
**Aplicar Etiqueta ao Chat**

Gerencia labels (etiquetas) de um chat. Use `labelids` para definir todas as labels de uma vez, `add_labelid` para adicionar uma label, ou `remove_labelid` para remover. Envie apenas um desses campos por requisição.

**Body (JSON):**
- `number` (obrigatório): Número do contato (ex: `5511999999999`)
- `labelids` (opcional): IDs das Labels (array, substitui todas) (ex: `["1","2"]`)
- `add_labelid` (opcional): Adicionar Label (ID) (ex: `1`)
- `remove_labelid` (opcional): Remover Label (ID) (ex: `1`)

**Exemplo de resposta:**
```json
{
  "response": "Label added to chat"
}
```

---

### POST /instance/connect
**Conectar Instância**

Conecta a instância ao WhatsApp. Necessário escanear QR code após esta chamada.

**Body (JSON):**
- `phone` (opcional): Número de telefone no formato internacional (ex: 5511999999999). Se informado, gera código de pareamento. Se omitido, gera QR code. (ex: `5511999999999`)

**Exemplo de resposta:**
```json
{
  "connected": true,
  "instance": {
    "id": "raa287d88df6336",
    "status": "connected",
    "name": "minha-instancia"
  },
  "response": "Already connected",
  "status": {
    "connected": true,
    "loggedIn": true
  }
}
```

---

### POST /instance/disconnect
**Desconectar Instância**

Desconecta a instancia do WhatsApp. Sera necessario escanear o QR code novamente para reconectar.

**Exemplo de resposta:**
```json
{
  "info": "The device has been successfully disconnected from WhatsApp. A new QR code will be required for the next connection.",
  "instance": {
    "status": "disconnected",
    "lastDisconnect": "2026-04-06T04:56:41Z",
    "lastDisconnectReason": "disconnected by API"
  },
  "response": "Disconnected"
}
```

---

### POST /instance/presence
**Status de Presença**

Define se a instância aparece como online ou offline para os contatos.

**Body (JSON):**
- `presence` (obrigatório): Status de presença (valores: available, unavailable)

**Exemplo de resposta:**
```json
{
  "response": "Presence updated successfully"
}
```

---

### GET /instance/privacy
**Ver Privacidade**

Retorna as configurações de privacidade da conta: quem pode adicionar em grupos, ver último acesso, foto de perfil e confirmações de leitura.

**Exemplo de resposta:**
```json
{
  "calladd": "all",
  "groupadd": "all",
  "last": "contacts",
  "online": "all",
  "profile": "all",
  "readreceipts": "all",
  "status": "contacts"
}
```

---

### POST /instance/privacy
**Alterar Privacidade**

Atualiza as configurações de privacidade. Todos os campos são opcionais . envie apenas o que deseja alterar.

**Body (JSON):**
- `groupadd` (opcional): Adicionar em grupos (valores: all, contacts, contact_blacklist, none)
- `last` (opcional): Último acesso (valores: all, contacts, contact_blacklist, none)
- `profile` (opcional): Foto de perfil (valores: all, contacts, contact_blacklist, none)
- `readreceipts` (opcional): Confirmação de leitura (valores: all, none)
- `online` (opcional): Status online (valores: all, match_last_seen)
- `calladd` (opcional): Receber chamadas de (valores: all, known)
- `status` (opcional): Recado (status text) (valores: all, contacts, contact_blacklist, none)

**Exemplo de resposta:**
```json
{
  "groupadd": "contacts",
  "last": "contacts",
  "profile": "contacts",
  "readreceipts": "all",
  "online": "all",
  "calladd": "all"
}
```

---

### GET /instance/proxy
**Ver Proxy**

Retorna a configuração de proxy da instância.

**Exemplo de resposta:**
```json
{
  "enabled": true,
  "managed": true,
  "proxy_url": "managed_pool://hidden",
  "proxy_fallback": "internal_proxy",
  "last_test_at": 1775449088975,
  "last_test_error": "",
  "validation_error": false
}
```

---

### POST /instance/proxy
**Configurar Proxy**

Configura, altera ou REMOVE o proxy da instância. O campo canônico é `mode`: `custom` (proxy próprio, exige proxy_url), `internal` (proxy gerenciado pelo serviço) ou `none` (remove o proxy, exige confirm_no_proxy=true). Para remover o proxy, envie mode=none e confirm_no_proxy=true.

**Body (JSON):**
- `mode` (obrigatório): Estratégia de proxy (valores: custom, internal, none)
- `proxy_url` (opcional): URL do proxy (obrigatório quando mode=custom). Protocolos: http://, https://, socks5:// (ex: `http://usuario:senha@host:porta`)
- `proxy_fallback` (opcional): Contingência para mode=custom (ex: internal, never) (ex: `internal`)
- `confirm_no_proxy` (opcional): Confirma remoção do proxy (obrigatório quando mode=none) (valores: true, false)
- `rotate_now` (opcional): Troca o proxy interno imediatamente (quando mode=internal) (valores: true, false)

**Exemplo de resposta:**
```json
{
  "details": "Proxy removido",
  "proxy": {
    "enabled": false
  },
  "restart_requested": true
}
```

---

### POST /instance/reset
**Reiniciar Instância**

Reinicia o runtime da instancia. Se a instancia estiver desconectada, sera necessario escanear o QR code novamente.

**Exemplo de resposta:**
```json
{
  "instanceId": "r8ecb82b8e9613c",
  "resetting": true,
  "response": "Instance reset started"
}
```

---

### GET /instance/status
**Informações & Status da Instância**

Retorna dados completos da instância: nome, número de telefone conectado, foto de perfil e status atual da conexão (disconnected, connecting, connected).

**Exemplo de resposta:**
```json
{
  "instance": {
    "status": "connected",
    "name": "minha-instancia",
    "profileName": "Meu Perfil",
    "owner": "5511999999999",
    "msg_delay_min": 1,
    "msg_delay_max": 3
  }
}
```

---

### POST /instance/updateDelaySettings
**Configurar Delay**

Configura o delay minimo e maximo entre mensagens na fila. Retorna o objeto completo da instancia.

**Body (JSON):**
- `msg_delay_min` (obrigatório): Delay mínimo em segundos (0 = sem delay) (ex: `0`)
- `msg_delay_max` (obrigatório): Delay máximo em segundos (ex: `2`)

**Exemplo de resposta:**
```json
{
  "id": "raa287d88df6336",
  "name": "minha-instancia",
  "status": "connected",
  "msg_delay_min": 0,
  "msg_delay_max": 2
}
```

---

### POST /instance/updateInstanceName
**Renomear Instância**

Atualiza o nome interno da instancia. Retorna o objeto completo da instancia.

**Body (JSON):**
- `name` (obrigatório): Novo nome para a instância (ex: `Minha Nova Instância 2024!@#`)

**Exemplo de resposta:**
```json
{
  "id": "raa287d88df6336",
  "name": "Novo Nome",
  "status": "connected",
  "profileName": "Meu Perfil",
  "owner": "5511999999999"
}
```

---

### POST /label/edit
**Criar / Editar Etiqueta**

Cria uma nova etiqueta ou edita/deleta uma existente. Para criar, use labelid "0" com name e color. Para editar, use o labelid real. Cor: numero de 0 a 19.

**Body (JSON):**
- `labelid` (obrigatório): ID da etiqueta. Use "0" para criar nova. (ex: `0`)
- `name` (obrigatório): Nome da etiqueta (ex: `Cliente VIP`)
- `color` (opcional): Cor (0 a 19) (ex: `5`)
- `delete` (opcional): Deletar? (valores: false, true)

**Exemplo de resposta:**
```json
{
  "response": "Label edited successfully"
}
```

---

### GET /labels
**Listar Etiquetas**

Retorna todas as etiquetas criadas na instância.

**Exemplo de resposta:**
```json
[
  {
    "id": "5511999999999:1",
    "name": "Nao lidas",
    "color": 0,
    "colorHex": "#ff9484",
    "labelid": "1",
    "owner": "5511999999999"
  }
]
```

---

### POST /labels/refresh
**Recarregar Etiquetas**

Recarrega as etiquetas do WhatsApp para sincronizar com o banco local.

**Body (JSON):**
- `force` (opcional): Tente primeiro com `false`.
Use `true` apenas quando a recarga padrão não funcionar bem,
pois esse modo faz uma nova leitura mais completa das etiquetas.
 (valores: true, false) (ex: `False`)

**Exemplo de resposta:**
```json
[
  {
    "id": "5511999999999:1",
    "name": "Nao lidas",
    "color": 0,
    "labelid": "1"
  }
]
```

---

### POST /quickreply/edit
**Criar / Editar Resposta Rápida**

Cria ou atualiza um atalho de resposta rápida. Ao digitar "/" seguido do atalho no WhatsApp, a mensagem completa é sugerida. Para editar, envie o campo `id`.

**Body (JSON):**
- `shortCut` (obrigatório): Atalho (ex: bom-dia) (ex: `bom-dia`)
- `text` (obrigatório): Texto da resposta (ex: `Bom dia! Como posso te ajudar hoje?`)
- `type` (obrigatório): Tipo (valores: text, image, video, document)
- `file` (opcional): URL do arquivo (se mídia) (ex: `https://...`)
- `docName` (opcional): Nome do documento (ex: `catalogo.pdf`)
- `keywords` (opcional): Palavras-chave (JSON array) (ex: `["bom dia","bom-dia"]`)
- `id` (opcional): ID (para editar) (ex: `qr_abc123`)
- `delete` (opcional): Deletar a resposta rapida (valores: false, true)

**Exemplo de resposta:**
```json
{
  "message": "Operation completed successfully",
  "quickReplies": [
    {
      "id": "r6e84a8016cbd63",
      "shortCut": "bom-dia",
      "text": "Bom dia!",
      "type": "text"
    }
  ]
}
```

---

### GET /quickreply/showall
**Listar Respostas Rápidas**

Retorna todas as respostas rápidas configuradas na instância.

**Exemplo de resposta:**
```json
[
  {
    "id": "r6e84a8016cbd63",
    "onWhatsApp": false,
    "docName": "",
    "file": "",
    "shortCut": "bom-dia",
    "text": "Bom dia! Como posso te ajudar?",
    "type": "text",
    "owner": "5511999999999"
  }
]
```

---

## Webhooks & Eventos

### GET /sse
**Server-Sent Events (SSE)**

Abre conexão Server-Sent Events para receber eventos em tempo real.

**Exemplo de resposta:**
```json
{}
```

---

### GET /webhook
**Ver Webhook da Instância**

Retorna a configuracao de webhooks da instancia. A resposta e sempre um array, mesmo com um unico webhook.

**Exemplo de resposta:**
```json
[
  {
    "url": "https://example.com",
    "enabled": false,
    "events": [],
    "id": "r1234"
  }
]
```

---

### POST /webhook
**Configurar Webhook da Instância**

Gerencia webhooks da instancia. Suporta modo simples (sem action) e modo multi-webhook (com action: add/update/delete). Para deletar, envie id + action "delete". Os eventos vêm DESATIVADOS por padrão. Ligue só os que for consumir (evita tráfego desnecessário). Eventos de volume alto (presence, history) só ligue se realmente for tratar.

**Body (JSON):**
- `id` (opcional): ID único do webhook (necessário para update/delete) (ex: `123e4567-e89b-12d3-a456-426614174000`)
- `enabled` (opcional): Habilita/desabilita o webhook (valores: true, false) (ex: `True`)
- `url` (obrigatório): URL para receber os eventos (ex: `https://example.com/webhook`)
- `events` (opcional): Lista de eventos que você quer receber no seu webhook. TUDO vem desativado por padrão: envie só os que for usar. Disponíveis: connection (conexão), messages (mensagens recebidas/enviadas), messages_update (status: entregue/lida), history (histórico ao conectar, VOLUME ALTO), newsletter_messages (mensagens de canais), call (chamadas), contacts, groups, chats, labels, chat_labels, presence (online/digitando, VOLUME ALTO), blocks (bloqueios), sender. Exemplo: ["messages","connection","messages_update"]. (ex: `["messages","connection","messages_update"]`)
- `excludeMessages` (opcional): Filtros para excluir tipos de mensagens
- `addUrlEvents` (opcional): Adiciona o tipo do evento como parâmetro na URL.
- `false` (padrão): URL normal
- `true`: Adiciona evento na URL (ex: `/webhook/message`)
 (valores: true, false)
- `addUrlTypesMessages` (opcional): Adiciona o tipo da mensagem como parâmetro na URL.
- `false` (padrão): URL normal  
- `true`: Adiciona tipo da mensagem (ex: `/webhook/conversation`)
 (valores: true, false)
- `action` (opcional): Ação a ser executada:
- add: criar novo webhook
- update: atualizar webhook existente (requer id)
- delete: remover webhook (requer apenas id)
Se não informado, opera no modo simples (único webhook)
 (valores: add, update, delete)

**Exemplo de resposta:**
```json
{
  "status": "Webhook deleted successfully"
}
```

---

### GET /webhook/errors
**Erros do Webhook**

Lista os últimos erros de entrega do webhook.

**Exemplo de resposta:**
```json
[
  {
    "created": "2026-04-06T04:00:00Z",
    "url": "https://...",
    "event": "messages",
    "error": "timeout"
  }
]
```

---

### POST (entregue no seu endpoint)
**Formato do Webhook Recebido (envelope + assinatura)**

Documenta o que o SEU sistema RECEBE. Quando um evento acontece (mensagem, conexão, etc.), o ZapZap faz um POST no seu webhook_url com o envelope abaixo. Responda 2xx rápido: em falha, reentregamos com backoff (30s, 2min, 10min, 1h) e desativamos o webhook após falhas seguidas.

Envelope (corpo do POST):
```json
{
  "delivery_id": "uuid desta entrega (estável entre reenvios)",
  "event_id": "id do evento quando disponível (use para deduplicar)",
  "version": "1",
  "instance_id": "uuid da sua instância no ZapZap",
  "instance_name": "nome da instância",
  "metadata": null,
  "event": "messages",
  "data": { "...": "conteúdo do evento (varia por tipo)" }
}
```

Cabeçalhos enviados:
- X-ZapZap-Id: id da entrega (igual ao delivery_id).
- X-ZapZap-Event: tipo do evento.
- X-ZapZap-Timestamp: unix time do envio.
- X-ZapZap-Signature: t=UNIX,v1=HMAC. Assinatura para você validar a autenticidade.

Como validar a assinatura (recomendado):
1. Pegue t e v1 do header X-ZapZap-Signature.
2. Calcule HMAC-SHA256, em hex, sobre a string t + "." + corpo_bruto, usando o segredo do webhook (disponível na tela do webhook e no GET do webhook).
3. Compare com v1. Se diferente, rejeite.
4. Rejeite se t tiver mais de 5 minutos (proteção contra reenvio malicioso).

Deduplicação: o mesmo evento pode chegar mais de uma vez (reentrega). Ignore se já processou o delivery_id (ou event_id).

**Exemplo de resposta:**
```json
{}
```

---

### GET /instances/{id}/webhook/deliveries
**Entregas Recentes do Webhook**

Lista as últimas entregas de webhook desta instância (janela recente, para depurar): evento, se foi entregue, status HTTP, latência, número da tentativa e horário. Útil pra conferir se o seu endpoint está recebendo e respondendo 2xx.

**Parâmetros de path:**
- `id` (obrigatório): ID da instância

**Query params:**
- `limit` (opcional): Quantidade (máx 100)

**Exemplo de resposta:**
```json
{
  "deliveries": [
    {
      "delivery_id": "uuid",
      "event": "messages",
      "event_id": "abc",
      "ts": 1725600000000,
      "ok": true,
      "status": 200,
      "latency_ms": 142,
      "attempt": 1
    }
  ]
}
```

---

## Fila Async

### DELETE /message/async
**Limpar Fila Async**

Limpa toda a fila de mensagens async.

**Exemplo de resposta:**
```json
{
  "response": "Async queue cleared",
  "stats": {
    "removed": 0,
    "pending": 0
  }
}
```

---

### GET /message/async
**Ver Fila Async**

Consulta a fila de mensagens async pendentes.

**Exemplo de resposta:**
```json
{
  "queue": {
    "status": "idle",
    "pending": 0,
    "processingNow": false,
    "acceptingNewMessages": true
  },
  "response": "Async queue status"
}
```

---

## Chatbot & IA

### POST /agent/edit
**Criar/Editar Agente IA**

Cria, edita ou deleta um agente de IA para atendimento automático. Enviar id vazio para criar; preenchido para editar; delete=true para deletar.

**Body (JSON):**
- `id` (opcional): ID do Agente (ex: `Vazio para criar novo`)
- `delete` (opcional): Deletar (valores: false, true)
- `agent` (obrigatório): Agente (JSON) (ex: `{"name": "Assistente", "provider": "openai", "apikey": "sk-...", "model": "gpt-4o-mini", "basePrompt": "Voce é um assistente...", "maxTokens": 2000, "temperature": 70, "diversityLevel": 50, "frequencyPenalty": 30, "presencePenalty": 30, "signMessages": true, "readMessages": true, "maxMessageLength": 500, "typingDelay_seconds": 3, "contextTimeWindow_hours": 24, "contextMaxMessages": 50, "contextMinMessages": 3}`)

**Exemplo de resposta:**
```json
{
  "id": "read16c9f35642c",
  "name": "Assistente",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "apikey": "sk-...",
  "basePrompt": "Voce e um assistente...",
  "maxTokens": 500,
  "temperature": 70,
  "diversityLevel": 0,
  "frequencyPenalty": 0,
  "presencePenalty": 0,
  "signMessages": false,
  "readMessages": false,
  "maxMessageLength": 0,
  "typingDelay_seconds": 0,
  "contextTimeWindow_hours": 0,
  "contextMaxMessages": 0,
  "contextMinMessages": 0
}
```

---

### GET /agent/list
**Listar Agentes IA**

Lista todos os agentes de IA configurados na instancia. Retorna array vazio se nenhum agente existir.

**Exemplo de resposta:**
```json
[]
```

---

### POST /function/edit
**Criar/Editar Função API**

Cria, edita ou deleta uma funcao de API para integracao com servicos externos. Envie id vazio para criar, preenchido para editar, delete=true para deletar.

**Body (JSON):**
- `id` (obrigatório): ID da função. Vazio para criar nova, preenchido para editar existente.
- `delete` (obrigatório): Se true, deleta a função especificada pelo ID. (valores: true, false)
- `function` (obrigatório): Configuração da função (JSON) (ex: `{"name": "minha_funcao", "description": "Descricao da funcao", "active": false, "method": "GET", "endpoint": "https://api.example.com/endpoint", "headers": {}, "body": {}, "parameters": []}`)

**Exemplo de resposta:**
```json
{
  "id": "r72440ced9503e3",
  "name": "minha_funcao",
  "description": "Descricao da funcao",
  "active": false,
  "method": "GET",
  "endpoint": "https://api.example.com/endpoint",
  "headers": "{}",
  "body": "{}",
  "parameters": "[]"
}
```

---

### GET /function/list
**Listar Funções API**

Lista todas as funcoes de API configuradas. Retorna array vazio se nenhuma funcao existir.

**Exemplo de resposta:**
```json
[]
```

---

### POST /knowledge/edit
**Criar/Editar Conhecimento**

Cria ou edita base de conhecimento para os agentes de IA. (Requer OpenAI API key configurada na instância)

**Body (JSON):**
- `id` (opcional): ID do conhecimento (vazio para criar novo)
- `delete` (opcional): Define se é uma operação de exclusão (valores: true, false)
- `knowledge` (opcional): Conteúdo do conhecimento
- `fileType` (opcional): Tipo do arquivo quando não detectado automaticamente (valores: pdf, txt, html, csv)

**Exemplo de resposta:**
```json
{
  "ok": true
}
```

---

### GET /knowledge/list
**Listar Conhecimentos**

Lista toda a base de conhecimento dos agentes. Retorna array vazio se nenhum conhecimento existir.

**Exemplo de resposta:**
```json
[]
```

---

### POST /trigger/edit
**Criar/Editar Trigger**

Cria, edita ou deleta um trigger de chatbot. Requer um agente existente (agent_id).

**Body (JSON):**
- `id` (opcional): ID do Trigger (ex: `Vazio para criar novo`)
- `delete` (opcional): Deletar (valores: false, true)
- `trigger` (obrigatório): Trigger (JSON) (ex: `{"active": true, "type": "agent", "agent_id": "id_do_agente", "ignoreGroups": true, "priority": 1, "wordsToStart": "ola|oi|iniciar", "responseDelay_seconds": 3, "lead_field": "", "lead_operator": "", "lead_value": ""}`)

**Exemplo de resposta:**
```json
{
  "id": "rbcca9c181c1e5a",
  "active": false,
  "type": "agent",
  "agent_id": "read16c9f35642c",
  "flow_id": "",
  "quickReply_id": "",
  "ignoreGroups": true,
  "lead_field": "",
  "lead_operator": "",
  "lead_value": "",
  "priority": 1,
  "wordsToStart": "ola|oi",
  "responseDelay_seconds": 3
}
```

---

### GET /trigger/list
**Listar Triggers**

Lista todos os triggers de chatbot configurados. Retorna array vazio se nenhum trigger existir.

**Exemplo de resposta:**
```json
[]
```

---

## CRM & Leads

### POST /chat/editLead
**Editar Lead**

Edita dados de lead de um contato. O ID deve incluir @s.whatsapp.net.

**Body (JSON):**
- `id` (obrigatório): ID do chat (formato: numero@s.whatsapp.net) (ex: `5511999999999@s.whatsapp.net`)
- `lead_name` (opcional): Nome do lead (ex: `Joao Silva`)
- `lead_email` (opcional): Email do lead (ex: `joao@email.com`)
- `lead_status` (opcional): Status do lead no funil (ex: `qualificado`)
- `lead_isTicketOpen` (opcional): Ticket aberto (valores: true, false)
- `lead_tags` (opcional): Tags (JSON array) (ex: `["vip","suporte"]`)
- `lead_notes` (opcional): Anotacoes sobre o lead (ex: `Cliente interessado...`)
- `lead_field01` (opcional): Campo personalizado 01
- `lead_field02` (opcional): Campo personalizado 02
- `chatbot_disableUntil` (opcional): Desativar chatbot ate (timestamp UTC, 0 para reativar) (ex: `0`)
- `lead_personalid` (opcional): Lead Personalid
- `lead_field03` (opcional): Lead Field03
- `lead_field04` (opcional): Lead Field04
- `lead_field05` (opcional): Lead Field05

**Exemplo de resposta:**
```json
{
  "chat": {
    "lead_name": "Joao",
    "lead_email": "joao@email.com"
  },
  "source": "local"
}
```

---

### POST /instance/updateFieldsMap
**Campos Personalizados de Lead**

Define os nomes dos campos de lead. Campos sao flat (lead_field01, lead_field02, etc).

**Body (JSON):**
- `lead_field01` (opcional): Campo 01 (ex: `nome`)
- `lead_field02` (opcional): Campo 02 (ex: `email`)
- `lead_field03` (opcional): Campo 03 (ex: `telefone`)
- `lead_field04` (opcional): Campo 04 (ex: `cidade`)
- `lead_field05` (opcional): Campo 05 (ex: `estado`)

**Exemplo de resposta:**
```json
{
  "id": "raa287d88df6336",
  "name": "minha-instancia",
  "fieldsMap": {
    "lead_field01": "nome",
    "lead_field02": "email",
    "lead_field03": "telefone"
  }
}
```

---

## Integração Chatwoot

### GET /chatwoot/config
**Ver Config Chatwoot**

Retorna a configuracao atual da integracao com Chatwoot, incluindo status da conexao.

**Exemplo de resposta:**
```json
{
  "chatwoot_enabled": false,
  "chatwoot_url": "",
  "chatwoot_account_id": 0,
  "chatwoot_inbox_id": 0,
  "chatwoot_inbox_name": "minha-instancia",
  "chatwoot_access_token": "",
  "chatwoot_ignore_groups": false,
  "chatwoot_sign_messages": false,
  "chatwoot_create_new_conversation": false,
  "integration_status": {
    "status": "disabled",
    "message": "Integracao Chatwoot nao esta habilitada",
    "connection_ok": false,
    "credentials_ok": false,
    "inbox_exists": false
  }
}
```

---

### PUT /chatwoot/config
**Configurar Chatwoot**

Atualiza a configuracao da integracao Chatwoot. Os campos usam prefixo chatwoot_. Integracao em beta.

**Body (JSON):**
- `chatwoot_enabled` (obrigatório): Habilitar integracao (valores: true, false)
- `chatwoot_url` (opcional): URL do Chatwoot (sem barra final) (ex: `https://app.chatwoot.com`)
- `chatwoot_access_token` (opcional): Token de acesso do Chatwoot (ex: `pXXGHHHyJPYHYgWHJHYHgJjj`)
- `chatwoot_account_id` (opcional): ID da conta no Chatwoot (ex: `1`)
- `chatwoot_inbox_id` (opcional): ID da inbox no Chatwoot (ex: `5`)
- `chatwoot_ignore_groups` (opcional): Ignorar grupos (valores: true, false)
- `chatwoot_sign_messages` (opcional): Assinar mensagens (valores: true, false)
- `chatwoot_create_new_conversation` (opcional): Sempre criar nova conversa (valores: true, false)

**Exemplo de resposta:**
```json
{
  "message": "Chatwoot config updated successfully"
}
```

---

## Fluxos

### GET /flows
**Listar Fluxos**

Lista todos os fluxos do usuario, incluindo status (habilitado/desabilitado) e tipo de gatilho.

**Exemplo de resposta:**
```json
{
  "flows": [
    {
      "id": "abc-123",
      "name": "Atendimento Delivery",
      "description": "Fluxo de atendimento automatico",
      "enabled": true,
      "trigger": {
        "type": "keyword",
        "value": "menu"
      },
      "created_at": "2026-04-10T12:00:00.000Z",
      "updated_at": "2026-04-15T18:30:00.000Z"
    }
  ]
}
```

---

### POST /flows/{flowId}/trigger
**Disparar Fluxo**

Dispara um fluxo para um contato especifico. O fluxo precisa estar habilitado e a instancia conectada. Variaveis opcionais ficam disponiveis dentro do fluxo como {nome_da_variavel}. Ao chegar num bloco de webhook, todas as variaveis coletadas (respostas, cliques, dados do contato) sao enviadas para a URL configurada.

**Parâmetros de path:**
- `flowId` (obrigatório): ID do fluxo

**Body (JSON):**
- `instance_id` (obrigatório): ID da instancia (ex: `inst-456`)
- `phone` (obrigatório): Telefone do contato (ex: `5511999999999`)
- `variables` (opcional): Variaveis iniciais (objeto JSON) (ex: `{"nome": "Joao", "plano": "premium"}`)

**Exemplo de resposta:**
```json
{
  "execution_id": "exec-789",
  "status": "waiting_reply",
  "flow_id": "abc-123",
  "phone": "5511999999999"
}
```

---

## Traqueamento Meta

### POST /{instanceId}/tracking/conversion
**Registrar venda de um lead de anúncio**

Avisa que um lead que veio de anúncio virou venda. É o que permite a Meta aprender quem realmente compra, em vez de otimizar só por quem responde mensagem. Use quando o pagamento for confirmado no seu sistema. Chamar duas vezes para a mesma venda não duplica.

**Body (JSON):**
- `phone` (obrigatório): undefined
- `value` (opcional): undefined
- `event` (opcional): undefined
- `occurred_at` (opcional): undefined

**Exemplo de resposta:**
```json
{
  "ok": true,
  "message": "Venda registrada e enviada para a Meta.",
  "event": "Purchase",
  "value": 700,
  "ad_id": "120243748541570695",
  "lead_status": "won",
  "status": "queued"
}
```

---