# OnZap

> API HTTP de WhatsApp. Cada instância é um número conectado (por QR Code na API OnZap ou pela API oficial da Meta): envie mensagens, leia conversas e receba os eventos por webhook assinado.

- Endereço base: `https://app.onzap.io/v1/instances/{instanceId}`
- Autenticação: header `X-Instance-Token` (e `Client-Token`, se a conta exigir). Só servidor a servidor.
- Erros: `{"error": {"code", "message", "details"}}`; trate pelo `code`.
- Webhooks: envelope `{id, event, instanceId, provider, timestamp, payload, me}`, assinado em `X-OnZap-Signature`.

## Começando

- [Introdução](https://developer.onzap.io/introducao.md): O que é a API da OnZap, os dois tipos de instância e a sua primeira requisição.
- [Autenticação](https://developer.onzap.io/autenticacao.md): Token da instância, Client-Token da conta e como guardar as credenciais.
- [Primeiros passos](https://developer.onzap.io/primeiros-passos.md): Do zero à primeira mensagem enviada e recebida, em poucos minutos.
- [Erros e limites](https://developer.onzap.io/erros-e-limites.md): Formato dos erros, códigos, o que tentar de novo e os limites da API.
## Guias

- [Conversas e números](https://developer.onzap.io/conversas-e-numeros.md): Como identificar contatos e grupos no chatId, e o que são LID e BSUID.
- [Mensagens e mídia](https://developer.onzap.io/mensagens-e-midia.md): Tipos de envio, arquivos por URL ou base64, respostas, reações e a mídia recebida.
- [Fila de mensagens](https://developer.onzap.io/fila.md): Envios com intervalo, "digitando…" e espera enquanto o celular está desconectado.
- [Webhooks](https://developer.onzap.io/webhooks.md): Receba os eventos da instância no seu sistema, confira a assinatura e trate repetições.
- [API oficial (Meta)](https://developer.onzap.io/api-oficial.md): Instâncias da WhatsApp Cloud API: conexão, janela de 24 horas, templates e diferenças.
## IA e agentes

- [Use com IA](https://developer.onzap.io/ia.md): llms.txt, Markdown de cada página e instruções para assistentes de programação.

## Referência da API

- [Instância](https://developer.onzap.io/referencia/instancia.md): Status, configurações e ciclo de vida da conexão.
- [Pareamento](https://developer.onzap.io/referencia/pareamento.md): Conectar o número: QR Code, código por telefone ou passkey.
- [Perfil](https://developer.onzap.io/referencia/perfil.md): Nome, recado e foto do número conectado.
- [Mensagens](https://developer.onzap.io/referencia/mensagens.md): Envio de mensagens de todos os tipos, reações, leitura e "digitando…".
- [Chats](https://developer.onzap.io/referencia/chats.md): Conversas: listar, ler o histórico, editar e apagar mensagens, marcar como lidas.
- [Contatos](https://developer.onzap.io/referencia/contatos.md): Agenda, verificação de números e foto de perfil.
- [Grupos](https://developer.onzap.io/referencia/grupos.md): Criar e administrar grupos, participantes e convites.
- [Canais](https://developer.onzap.io/referencia/canais.md): Canais (newsletters): criar, seguir e buscar.
- [Status (stories)](https://developer.onzap.io/referencia/status-stories.md): Publicar status de texto, imagem, voz e vídeo.
- [Etiquetas](https://developer.onzap.io/referencia/etiquetas.md): Etiquetas do WhatsApp Business.
- [Presença](https://developer.onzap.io/referencia/presenca.md): Online, digitando e visto por último.
- [Chamadas](https://developer.onzap.io/referencia/chamadas.md): Recusar chamadas recebidas.
- [Mídia](https://developer.onzap.io/referencia/midia.md): Converter áudio e vídeo para o formato do WhatsApp.
- [Integrações](https://developer.onzap.io/referencia/integracoes.md): Integrações prontas (ex.: Chatwoot) ligadas à instância.
- [Fila](https://developer.onzap.io/referencia/fila.md): Fila de envio da instância: intervalo entre mensagens, "digitando…" e espera por reconexão.
- [Webhooks](https://developer.onzap.io/referencia/webhooks.md): Endereços que recebem os eventos da instância, com histórico de entregas.
- [Eventos de webhook](https://developer.onzap.io/referencia/eventos-de-webhook.md): Tudo o que pode chegar no seu webhook, com o formato do payload de cada evento.
- [Eventos](https://developer.onzap.io/referencia/eventos.md): Eventos dos últimos 7 dias, no mesmo formato entregue aos webhooks.
- [Templates](https://developer.onzap.io/referencia/templates.md): Modelos de mensagem aprovados pela Meta (obrigatórios fora da janela de 24 h).
- [Perfil comercial](https://developer.onzap.io/referencia/perfil-comercial.md): Descrição, endereço, site e foto do perfil comercial.
- [Número](https://developer.onzap.io/referencia/numero.md): Dados do número na Meta: qualidade, limite de envio e status.

## Opcional

- [Documentação completa em um arquivo](https://developer.onzap.io/llms-full.txt): todos os guias e a referência inteira
- [OpenAPI 3.1](https://developer.onzap.io/openapi.json): contrato da API, para gerar clientes e SDKs

---

# Introdução

> O que é a API da OnZap, os dois tipos de instância e a sua primeira requisição.

A OnZap é uma **API HTTP de WhatsApp**. Cada **instância** é um número de WhatsApp conectado: pela API você envia
mensagens, lê conversas, administra grupos e recebe no seu sistema, por webhook, tudo o que acontece no número.

```text
Endereço base   https://app.onzap.io/v1/instances/{instanceId}
Autenticação    header X-Instance-Token
Formato         JSON (UTF-8), servidor a servidor
```

## O que você pode fazer

- **Enviar mensagens** de texto, imagem, áudio, vídeo, documento, localização, contato, enquete e reação.
- **Receber eventos** assinados: mensagens recebidas e enviadas, confirmações de entrega e leitura, status da conexão.
- **Ler conversas**: chats, histórico, contatos e foto de perfil.
- **Grupos, canais, status e etiquetas** (API OnZap).
- **Templates e mensagens interativas** (API oficial da Meta).
- **Fila de envio**: intervalo entre mensagens, "digitando…" e espera enquanto o celular está desconectado.

## Tipos de instância

As duas usam **as mesmas rotas e o mesmo formato de webhook**. Você escolhe o tipo ao criar a instância:

| | API OnZap | API oficial (Meta) |
|---|---|---|
| Conexão | QR Code ou código no celular | Conta do Facebook (WhatsApp Business Platform) |
| Rotas | Todas, exceto as marcadas **Só API oficial** | As marcadas com o selo **API oficial** |
| Grupos, canais, status, etiquetas | Sim | Não |
| Botões | Não (o WhatsApp não exibe botões fora da API oficial) | Sim |
| Templates da Meta | Não | Sim |
| Janela de conversa | Livre | Fora das 24 h desde a última mensagem do cliente, só templates |
| Foto de perfil e de grupo | Sim (links assinados em `from.picture` e `chatPicture`) | Não (a Meta não fornece) |
| Cobrança por mensagem | Não | A Meta cobra direto na sua conta do WhatsApp Business |

## Fluxo básico de integração

1. Crie a conta e uma instância no [painel](https://app.onzap.io).
2. Conecte o número: QR Code, código no celular ou conta da Meta.
3. Copie o **ID** e o **token** da instância em **Credenciais da API**.
4. Envie mensagens pelas rotas de [Mensagens](https://developer.onzap.io/referencia/mensagens).
5. Cadastre um [webhook](https://developer.onzap.io/webhooks) para receber as respostas e os status de entrega.

## Primeira requisição

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "5511999999999", "text": "Olá! Primeira mensagem pela OnZap."}'
```

A resposta traz o `id` da mensagem. Guarde-o: é por ele que você acompanha a entrega e a leitura no evento
`message.ack` e responde ou reage a ela depois.

## Versões

A API é versionada no caminho (`/v1`). Mudanças compatíveis, como campos, rotas e eventos novos, entram sem aviso;
trate campos desconhecidos com tolerância. Mudanças incompatíveis viram uma nova versão, com prazo de transição.

---

# Autenticação

> Token da instância, Client-Token da conta e como guardar as credenciais.

Toda requisição leva o **token da instância** no header `X-Instance-Token`:

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA" \
  -H "X-Instance-Token: SEU_TOKEN"
```

- O ID e o token ficam no painel, em **Instâncias → sua instância → Credenciais da API**. O ID começa com `i`.
- `Authorization: Bearer SEU_TOKEN` também é aceito.
- Cada token abre **só a própria instância**.
- Em **Gerar novo token**, o token anterior para de funcionar na hora.

Sem token, ou com token errado, a resposta é `401` com o código `missing_token` ou `invalid_token`.

## Client-Token

O Client-Token é um segundo fator da **conta inteira**. Gere em **Configurações → Segurança da API** e ligue
**Exigir em todas as chamadas**. A partir daí, toda requisição precisa dos dois headers:

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Client-Token: SEU_CLIENT_TOKEN"
```

Sem ele, ou com o valor errado, a resposta é `401 invalid_client_token`. Trocar ou desligar o Client-Token vale em
até alguns segundos.

## Boas práticas

- **Só no servidor.** Nunca coloque o token em código que roda no navegador ou no aplicativo do cliente. A API não
  responde a chamadas de navegador (sem CORS), de propósito.
- **Guarde fora do código**, em variável de ambiente ou cofre de segredos (ex.: `ONZAP_TOKEN`).
- **Vazou?** Gere um novo token no painel; o antigo deixa de valer imediatamente.
- **Uma instância, um token.** Integrações com vários números guardam o par ID + token de cada instância.

---

# Primeiros passos

> Do zero à primeira mensagem enviada e recebida, em poucos minutos.

## 1. Crie a instância

No [painel](https://app.onzap.io), entre em **Instâncias → Criar instância** e escolha o tipo:

- **API OnZap**: conecta qualquer número lendo um QR Code, como no WhatsApp Web.
- **API oficial (Meta)**: conecta pela WhatsApp Business Platform, com templates e botões.

A primeira instância da conta tem teste grátis.

## 2. Conecte o número

Na aba **Conexão** da instância, abra o WhatsApp no celular em **Aparelhos conectados → Conectar um aparelho** e
leia o QR Code. Quando o status mudar para **Conectado**, a instância está pronta.

Também dá para conectar pela API:

- `GET /qr-code` devolve o QR Code (imagem ou texto) enquanto a instância estiver em `SCAN_QR_CODE`.
- `POST /pairing-code` com `{"phoneNumber": "5511999999999"}` gera um código de 8 caracteres para digitar no celular,
  sem QR Code (**Aparelhos conectados → Conectar aparelho → Conectar com número de telefone**). No Brasil, se o celular
  disser que o número está errado, peça de novo sem o nono dígito.
- `GET /` mostra o `connectionStatus`: as mensagens só saem em `WORKING`.

## 3. Pegue as credenciais

Em **Credenciais da API**, copie o **ID da instância** e o **token**. Veja [Autenticação](https://developer.onzap.io/autenticacao).

## 4. Envie uma mensagem

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "5511999999999", "text": "Olá! 👋"}'
```

```js
// Node.js 18+
const res = await fetch(`https://app.onzap.io/v1/instances/${process.env.ONZAP_INSTANCE}/messages/text`, {
  method: "POST",
  headers: { "X-Instance-Token": process.env.ONZAP_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({ chatId: "5511999999999", text: "Olá! 👋" }),
});
console.log(res.status, await res.json());
```

O `chatId` aceita o número com DDI e DDD (`5511999999999`); no Brasil o nono dígito é resolvido sozinho. Veja
[Conversas e números](https://developer.onzap.io/conversas-e-numeros).

## 5. Receba as mensagens

Cadastre o endereço do seu sistema como webhook da instância:

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://seu-sistema.com.br/webhooks/onzap", "events": ["message.any", "message.ack"]}'
```

A resposta traz o `secret` do webhook, que você usa para [conferir a assinatura](https://developer.onzap.io/webhooks#assinatura) de cada
evento.

**Ainda não tem um servidor?** Na aba **Inspetor** da instância, um clique cria um webhook apontando para um link da
própria OnZap. Mande uma mensagem para o número e veja o evento chegar na hora, como conversa ou como JSON cru.

---

# Erros e limites

> Formato dos erros, códigos, o que tentar de novo e os limites da API.

## Formato dos erros

Todo erro tem o mesmo formato:

```json
{
  "error": {
    "code": "validation_error",
    "message": "dados inválidos",
    "details": { "chatId": "informe o chatId" }
  }
}
```

- `code` é estável: trate os erros por ele.
- `message` é em português, para leitura humana, e pode mudar.
- `details`, quando existe, diz qual campo está errado.

## Códigos

| Status | Código | Significado |
|---|---|---|
| 400 | `bad_request` | Corpo ou parâmetro inválido |
| 400 | `url_not_allowed` | URL recusada (endereço interno ou porta fora de 80/443) |
| 401 | `missing_token`, `invalid_token` | Token da instância ausente ou errado |
| 401 | `invalid_client_token` | Client-Token ausente ou errado (conta com Client-Token exigido) |
| 402 | `payment_required` | Instância sem assinatura ativa |
| 404 | `not_found` | Recurso não existe (mensagem, grupo, contato…) |
| 409 | `instance_not_provisioned` | A instância ainda não foi ativada |
| 413 | `payload_too_large` | Corpo acima do limite (para arquivos grandes, envie por URL) |
| 422 | `validation_error` | Campo inválido (`details` diz qual) |
| 422 | `instance_not_connected` | O número não está conectado ao WhatsApp (confira `connectionStatus`) |
| 422 | `whatsapp_rejected` | O WhatsApp recusou (ex.: sem permissão no grupo, número inexistente) |
| 429 | `rate_limited` | Muitas requisições; espere o tempo do header `Retry-After` |
| 429 | `trial_limit_reached` | Limite diário de mensagens do teste grátis |
| 429 | `queue_full` | A fila da instância chegou a 10.000 mensagens pendentes |
| 429 | `too_many_attempts` | Muitos pedidos de código de pareamento; aguarde alguns minutos |
| 501 | `not_supported_by_provider` | A rota não existe na API oficial (instância Meta) |
| 501 | `official_api_only` | A rota só existe na API oficial (instância API OnZap) |
| 501 | `not_supported` | Recurso indisponível na API OnZap |
| 4xx/502 | `whatsapp_error` | Erro do WhatsApp ao processar (a `message` explica) |
| 503 | `whatsapp_unavailable` | Serviço temporariamente fora; tente de novo (veja `Retry-After`) |
| 504 | `whatsapp_timeout` | O WhatsApp demorou demais para responder |

## Quando tentar de novo

- **429, 502 e 503:** tente de novo depois do tempo do header `Retry-After`, ou com espera crescente (1 s, 2 s, 4 s…).
- **Outros 4xx:** não adianta repetir; corrija a requisição.
- **Timeout num envio:** antes de reenviar, confira nos eventos (`message.any` com `fromMe: true`) se a mensagem
  já saiu, para não mandar em duplicidade.

## Limites

| Limite | Valor |
|---|---|
| Requisições por instância | 20 por segundo, com rajadas curtas de até 40 |
| Corpo JSON | até 1 MB; com arquivo em base64, até 70 MB |
| Fila de envio | até 10.000 mensagens pendentes por instância |
| Teste grátis | até 300 mensagens por dia |
| Webhooks | até 5 endereços por instância |
| Links de mídia | válidos por 24 horas |

---

# Conversas e números

> Como identificar contatos e grupos no chatId, e o que são LID e BSUID.

Toda conversa é identificada por um `chatId`. Nos envios você pode mandar só o número; nos eventos ele sempre chega
completo.

| Formato | Exemplo | Quando aparece |
|---|---|---|
| Número com DDI e DDD | `5511999999999` | Nos seus envios (vira `5511999999999@c.us`) |
| Contato | `5511999999999@c.us` | Nos eventos, sempre que o número do contato é conhecido |
| LID | `36576092528787@lid` | Só quando o WhatsApp não informa o número por trás do LID |
| Grupo | `120363000000000000@g.us` | Grupos (só API OnZap) |
| BSUID | `BR.abc123@bsuid` | API oficial: usuário com nome de usuário, sem número visível |

- Nos envios, o campo `phone` é aceito como apelido de `chatId`.
- **Nono dígito:** no Brasil, o número é conferido e o nono dígito, resolvido automaticamente. Nos eventos, o `chatId`
  vem como o WhatsApp registrou o número: contas antigas aparecem **sem** o nono dígito (`556199998888@c.us`). Por
  isso use o `chatId` como chave da conversa, e não o número digitado.
- **Número de origem desconhecida?** Use `GET /contacts/check-exists?phone=5511999999999` antes de enviar: ele diz
  se o número tem WhatsApp e devolve o `chatId` certo.

## LID

O WhatsApp está trocando o número pelo **LID** (um identificador de privacidade) em várias conversas, e a mesma
pessoa pode chegar ora como `5561999998888@c.us`, ora como `36576092528787@lid`. Para o seu sistema não ficar com
duas conversas da mesma pessoa, **a OnZap converte o LID no número sempre que ele é conhecido**, em tudo o que você
usa como chave:

- nos eventos, `chatId`, `from.id` e os ids de mensagem (`id`, `quotedId`, e o `messageId` de confirmações,
  reações, mensagens apagadas e editadas) saem com o número (`...@c.us`);
- nas respostas da API (conversas, histórico, contatos, grupos), os JIDs e ids de mensagem seguem a mesma regra; o
  histórico de uma conversa pelo número (`GET /chats/5561999998888@c.us/messages`) já inclui o que chegou pelo LID;
- o LID original vem junto em `chatLid` e `from.lid` (nos eventos) e em `lid` (nas respostas), para quem quiser
  guardar os dois. As rotas `/lids` mostram o par LID ↔ número como ele é;
- só quando o WhatsApp não informa o número o `chatId` continua `...@lid` (e `from.phone` vem vazio). Responda usando
  esse mesmo `chatId`; o envio funciona igual.

Guarde o `chatId` como chave da conversa. Se você já tem conversas antigas com `@lid`, junte-as pelo `chatLid` das
mensagens novas.

## Grupos

Em grupos, o `chatId` é o do grupo (`@g.us`) e `from` é quem mandou a mensagem. As mensagens enviadas pela própria
conta chegam com `fromMe: true` e o mesmo `chatId` do grupo.

## Nome e foto da conversa

Nas mensagens (`message` e `message.any`), `chatName` e `chatPicture` descrevem **a conversa**, não quem mandou:

- **Grupo:** `chatName` é o assunto do grupo e `chatPicture`, a foto do grupo.
- **Contato:** `chatName` é o nome do contato (o da agenda do celular ou, na falta, o do perfil), inclusive nas
  mensagens enviadas pela conta, em que `from` é você.

`chatPicture` (como `from.picture`) é um link temporário; sem foto visível, ele responde `404`. Só na API OnZap.

## Quem mandou: `fromMe` e `from`

| Situação | `fromMe` | `from` |
|---|---|---|
| Mensagem recebida | `false` | O contato (`id`, `phone`, `pushName`, `picture`); em grupo, o participante |
| Enviada pela conta | `true` | A própria conta (na API oficial vem vazio) |

Nas enviadas, `source` diz a origem: `api` (por esta API) ou `app` (pelo celular ou outro aparelho conectado).

---

# Mensagens e mídia

> Tipos de envio, arquivos por URL ou base64, respostas, reações e a mídia recebida.

Todos os envios são `POST` em `/messages/...` com o `chatId` do destino. A lista completa, com todos os campos, está
em [Mensagens](https://developer.onzap.io/referencia/mensagens).

| Envio | Rota | Campos principais |
|---|---|---|
| Texto | `POST /messages/text` | `text`, `reply_to` (opcional) |
| Imagem | `POST /messages/image` | `file`, `caption` |
| Documento | `POST /messages/file` | `file` (com `filename`), `caption` |
| Áudio gravado | `POST /messages/voice` | `file`, `convert` |
| Vídeo | `POST /messages/video` | `file`, `caption`, `convert`, `asNote` |
| Localização | `POST /messages/location` | `latitude`, `longitude`, `title` |
| Contato | `POST /messages/contact-vcard` | `contacts[]` |
| Enquete | `POST /messages/poll` | `poll.name`, `poll.options`, `poll.multipleAnswers` |
| Lista | `POST /messages/list` | `message.sections[].rows[]` |
| Reação | `PUT /messages/reaction` | `messageId`, `reaction` (emoji; vazio remove) |

## Arquivos: por URL ou base64

```json
{
  "chatId": "5511999999999",
  "caption": "Segue o boleto",
  "file": {
    "url": "https://exemplo.com.br/arquivos/boleto.pdf",
    "mimetype": "application/pdf",
    "filename": "boleto.pdf"
  }
}
```

- **Por URL** (`file.url`): o endereço precisa ser público (http/https) e responder rápido. É o jeito recomendado.
- **Em base64** (`file.data`): o conteúdo do arquivo no próprio corpo, até 70 MB por requisição.
- **Áudio e vídeo:** com `convert: true`, o arquivo é convertido para o formato do WhatsApp (OGG/Opus e MP4).

## Responder, reagir e marcar como lida

- **Responder citando:** `reply_to` com o `id` da mensagem original.
- **Reagir:** `PUT /messages/reaction` com `messageId` e o emoji em `reaction`.
- **Marcar como lida:** `POST /messages/seen` com o `chatId`.
- **"Digitando…":** `POST /typing/start` até o envio da resposta (ou `POST /typing/stop`).
- **Editar ou apagar:** `PUT` e `DELETE` em `/chats/{chatId}/messages/{messageId}`.

O `id` de uma mensagem tem o formato `{fromMe}_{chatId}_{id}`, por exemplo
`false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6`.

## Mídia recebida

Imagens, áudios, vídeos e documentos chegam nos eventos com um **link assinado** em `payload.media.url`
(`https://app.onzap.io/v1/files/...`):

```json
"media": {
  "url": "https://app.onzap.io/v1/files/i01j.../false_5511999999999@c.us_3EB0....jpeg?exp=...&sig=...",
  "mimetype": "image/jpeg"
}
```

- Não precisa de token: o link é a autorização.
- Vale por **24 horas**. Baixe e guarde o arquivo no seu armazenamento se precisar dele depois.
- O tipo da mensagem vem em `payload.type`: `text`, `image`, `video`, `audio`, `voice`, `document`, `sticker`,
  `location`, `contact`, `poll`, `button_reply`, `list_reply`, `reaction` ou `unknown`.

---

# Fila de mensagens

> Envios com intervalo, "digitando…" e espera enquanto o celular está desconectado.

A **fila da instância** manda uma mensagem por vez, com intervalo entre elas e "digitando…" antes de cada uma.
Enquanto o número estiver desconectado, ela segura os envios e continua quando ele voltar, até o prazo configurado.
Serve para disparos em sequência e para parecer mais natural a quem recebe.

## Quando um envio vai para a fila

| Como | Efeito |
|---|---|
| `delayMessage` no corpo (0–60 s) | Espera esse tempo antes de enviar esta mensagem |
| `delayTyping` no corpo (0–15 s) | Mostra "digitando…" por esse tempo antes de enviar |
| Header `X-Queue: true` | Força a fila neste envio |
| Header `X-Queue: false` | Envia na hora (não combina com `delayMessage` nem `delayTyping`) |
| Nada disso | Vale o modo da instância: `direct` (na hora) ou `queue` (sempre fila) |

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "5511999999999", "text": "Olá!", "delayTyping": 3}'
```

Um envio enfileirado responde **`202`** com o `id` dele na fila. O resultado chega depois nos eventos `queue.sent`
(com o `id` da mensagem no WhatsApp) ou `queue.failed`, e também em `GET /queue/{queueId}`.

## Configuração

`PATCH /queue/settings` muda só os campos enviados:

| Campo | Significado |
|---|---|
| `mode` | `direct` ou `queue` (modo padrão dos envios) |
| `delayMin`, `delayMax` | Intervalo, em segundos, sorteado entre uma mensagem e a próxima |
| `ttlHours` | Por quanto tempo uma mensagem espera na fila (até 168 h); depois vira `queue.failed` |

- `POST /queue/pause` e `POST /queue/resume` param e retomam a fila.
- `DELETE /queue/{queueId}` cancela um envio; `DELETE /queue` cancela todos os pendentes.
- A fila guarda até 10.000 mensagens pendentes por instância (acima disso, `429 queue_full`).

---

# Webhooks

> Receba os eventos da instância no seu sistema, confira a assinatura e trate repetições.

Um webhook é um endereço do seu sistema que recebe, por `POST` em JSON, os eventos da instância: mensagens
recebidas e enviadas, confirmações de entrega e leitura, mudanças de conexão e muito mais.

## Cadastrar

Pelo painel (aba **Webhooks** da instância) ou pela API:

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://seu-sistema.com.br/webhooks/onzap", "events": ["message.any", "message.ack"]}'
```

- Até 5 webhooks por instância, cada um com os seus eventos (`"*"` assina todos).
- A resposta traz o `secret` usado na assinatura; `POST /webhooks/{webhookId}/rotate-secret` gera outro.
- `POST /webhooks/{webhookId}/test` envia um evento de teste para conferir o endereço.

## Formato

Todo evento chega com o mesmo envelope, nos dois tipos de instância:

```json
{
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "event": "message.any",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "provider": "onzap",
  "timestamp": 1767225600000,
  "payload": {
    "id": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "chatId": "5511999999999@c.us",
    "isGroup": false,
    "chatName": "Maria",
    "chatPicture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=…&sig=…",
    "fromMe": false,
    "from": { "id": "5511999999999@c.us", "phone": "5511999999999", "pushName": "Maria" },
    "type": "text",
    "text": "Oi! Vocês entregam em Campinas?"
  },
  "me": { "id": "5511888888888@c.us", "pushName": "Minha Loja" }
}
```

Os headers trazem o tipo (`X-OnZap-Event`), o id do evento (`X-OnZap-Event-Id`), o id da entrega
(`X-OnZap-Delivery`) e a assinatura (`X-OnZap-Signature`). Todos os eventos e os seus formatos estão em
[Eventos de webhook](https://developer.onzap.io/referencia/eventos-de-webhook).

## Eventos principais

| Evento | Quando |
|---|---|
| `message` | Mensagem **recebida** |
| `message.any` | Qualquer mensagem: recebida ou enviada pela conta (`fromMe: true`) |
| `message.ack` | Status de uma mensagem enviada: `sent`, `delivered`, `read`, `played` ou `failed` |
| `message.reaction` | Reação adicionada ou removida (`emoji` vazio) |
| `message.revoked` | Mensagem apagada para todos |
| `message.edited` | Texto de uma mensagem editado |
| `session.status` | Conexão mudou: `WORKING`, `SCAN_QR_CODE`, `STOPPED`, `FAILED`… |
| `queue.sent`, `queue.failed` | Resultado de um envio da [fila](https://developer.onzap.io/fila) |

**`message` ou `message.any`?** `message` traz só as recebidas. Para acompanhar a conversa inteira, inclusive o que
foi enviado pelo celular ou por outro sistema, assine `message.any`. Nas enviadas, `source` diz a origem: `api` ou
`app` (celular).

## Assinatura

O header `X-OnZap-Signature: t=<unix>,v1=<hex>` traz o HMAC-SHA256 de `"<t>.<corpo cru>"` com o `secret` do webhook.
Confira antes de processar e recuse `t` com mais de 5 minutos:

```js
// Node.js
import crypto from "node:crypto";

function assinaturaValida(corpoCru, header, segredo) {
  const partes = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const esperado = crypto.createHmac("sha256", segredo).update(`${partes.t}.${corpoCru}`).digest("hex");
  const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
  return recente && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1 ?? ""));
}
```

```php
// PHP
function assinaturaValida(string $corpoCru, string $header, string $segredo): bool {
    parse_str(str_replace(',', '&', $header), $p);
    $esperado = hash_hmac('sha256', $p['t'] . '.' . $corpoCru, $segredo);
    return abs(time() - (int) $p['t']) < 300 && hash_equals($esperado, $p['v1'] ?? '');
}
```

```python
# Python
import hashlib, hmac, time

def assinatura_valida(corpo_cru: bytes, header: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in header.split(","))
    esperado = hmac.new(segredo.encode(), f"{partes['t']}.".encode() + corpo_cru, hashlib.sha256).hexdigest()
    recente = abs(time.time() - int(partes["t"])) < 300
    return recente and hmac.compare_digest(esperado, partes.get("v1", ""))
```

Use o **corpo cru**, exatamente como chegou: se o seu framework já converteu o JSON, a assinatura não bate.

## Entrega

- **Confirmação:** responda qualquer `2xx` em até 10 segundos. Processe depois, numa fila sua, se for demorado.
- **Novas tentativas:** sem `2xx`, tentamos de novo após 10 s, 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h.
- **Pelo menos uma vez:** o mesmo evento pode chegar mais de uma vez e fora de ordem. Use o `id` do envelope para
  descartar repetidos.
- **Desativação:** um endereço que falha sem parar por 24 horas (ou responde `410`) é desativado, e avisamos por
  e-mail. Reative pelo painel ou por `PATCH /webhooks/{webhookId}`.
- **Histórico:** `GET /webhooks/{webhookId}/deliveries` lista as entregas; `.../retry` reenvia uma.

## Inspetor

Na aba **Inspetor** da instância, um clique cria um webhook apontando para um link da própria OnZap. Os eventos
aparecem na hora, montados como conversa (balões, confirmações, reações e mídia) ou como requisição crua, com
headers e a conferência da assinatura. É o jeito mais rápido de ver o que chega antes de programar o seu endpoint.

---

# API oficial (Meta)

> Instâncias da WhatsApp Cloud API: conexão, janela de 24 horas, templates e diferenças.

Uma instância da **API oficial** usa a WhatsApp Business Platform da Meta. As rotas e o formato dos webhooks são os
mesmos da API OnZap; o que muda são as regras da Meta.

## Conexão

No painel, crie a instância como **API oficial (Meta)** e conecte de um dos jeitos:

- **Com o Facebook:** você entra com a conta da empresa na Meta e escolhe o número. Na **coexistência**, o número
  continua no app WhatsApp Business do celular e também passa a usar a API.
- **Manual:** com as credenciais do seu próprio app na Meta (ID da conta do WhatsApp Business, ID do número, token
  permanente e chave secreta do app).

## Janela de 24 horas

Depois da última mensagem **do cliente**, você tem 24 horas para responder com qualquer tipo de mensagem. Fora dessa
janela, a Meta só aceita **templates** aprovados:

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/template" \
  -H "X-Instance-Token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "5511999999999", "template": "pedido_enviado", "language": "pt_BR", "body": ["Maria", "#1234"]}'
```

- `body` preenche as variáveis do corpo: lista para `{{1}}`, `{{2}}`… ou objeto para variáveis nomeadas.
  `header` e `buttons` preenchem o cabeçalho e os botões; `components` aceita o formato cru da Cloud API.
- `GET /templates` lista os templates da conta; `POST /templates` cria um novo (a Meta revisa antes de aprovar).
- O status da revisão chega no evento `template.status`.

## Botões e mensagens interativas

- `POST /messages/buttons`: até 3 botões de resposta, **ou** um único botão de link.
- `POST /messages/list`: lista com seções e opções.
- `POST /messages/interactive`: o formato interativo da própria Meta, para casos avançados.

O clique do cliente chega como mensagem com `type: button_reply` ou `list_reply`, com o botão escolhido em `reply`.

## Diferenças para a API OnZap

- **Sem grupos, canais, status e etiquetas.** Nessas rotas, a resposta é `501 not_supported_by_provider`.
- **Sem foto de perfil dos contatos**: a Meta não fornece.
- **BSUID:** usuários com nome de usuário podem chegar sem número, como `BR.abc123@bsuid`. Responda com o mesmo
  `chatId`.
- **Cobrança por mensagem:** a Meta cobra as conversas direto na sua conta do WhatsApp Business. O custo de cada
  mensagem chega em `payload.pricing` no evento `message.ack`.
- **Qualidade e limites:** `GET /phone-number` mostra a qualidade do número e o limite de envio; mudanças chegam no
  evento `phone.quality`.

---

# Use com IA

> llms.txt, Markdown de cada página e instruções para assistentes de programação.

Esta documentação foi feita para ser lida também por **assistentes de IA** (Cursor, Claude Code, Copilot, ChatGPT,
Lovable, Bolt…). Dê a eles a fonte certa e o código sai funcionando de primeira.

## Arquivos para a IA

| Arquivo | O que tem |
|---|---|
| [`/llms.txt`](https://developer.onzap.io/llms.txt) | Índice da documentação, com um link para cada página |
| [`/llms-full.txt`](https://developer.onzap.io/llms-full.txt) | A documentação inteira (guias e referência) em um só arquivo Markdown |
| `/{página}.md` | Cada página em Markdown (ex.: [`/webhooks.md`](https://developer.onzap.io/webhooks.md)) |
| [`/openapi.json`](https://developer.onzap.io/openapi.json) | O contrato OpenAPI 3.1, para gerar clientes e SDKs |

Agentes que pedem `Accept: text/markdown` recebem o Markdown no próprio endereço da página, sem o `.md`.

Em toda página, o botão **Copiar página** leva o conteúdo em Markdown para colar no chat da IA; no menu ao lado,
**Abrir no ChatGPT** ou **Abrir no Claude** já abre a conversa com a página como contexto.

## Prompt para começar

```text
Leia https://developer.onzap.io/llms-full.txt. Vou integrar meu sistema com a API de WhatsApp da OnZap.
Regras:
- Chamadas só no servidor, com o header X-Instance-Token (token em variável de ambiente ONZAP_TOKEN).
- Endereço base: https://app.onzap.io/v1/instances/{ONZAP_INSTANCE}.
- Para receber mensagens, crie um endpoint de webhook que confere o X-OnZap-Signature e assine message.any.
- Trate erros pelo campo error.code.
Agora: <descreva o que você quer construir>
```

## Dicas para o código gerado ficar certo

- **Token nunca no front-end.** Se a IA colocar a chamada no navegador, peça para mover para uma rota do servidor.
- **Use o `chatId` do evento para responder**, inclusive quando vier `@lid`.
- **Confira a assinatura com o corpo cru** do webhook e responda `2xx` rápido.
- **Descarte eventos repetidos** pelo `id` do envelope.
- **Mídia recebida:** baixe o arquivo pelo link em até 24 horas.

---

# Instância

> Status, configurações e ciclo de vida da conexão.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Dados e status da instância

`GET /` · API OnZap, API oficial (Meta)

Dados da instância e o status da conexão (`connectionStatus`): `STOPPED`, `STARTING`, `SCAN_QR_CODE`, `WORKING` ou `FAILED`. Só envia mensagens em `WORKING`.

**Na API oficial:** mesmo formato; `connectionStatus` é `WORKING` enquanto a conexão com a Meta estiver válida.

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```

## Atualizar configurações da instância

`PATCH /settings` · API OnZap

Ignorar eventos de grupos, status, canais ou listas de transmissão; nome do aparelho em "Aparelhos conectados"; o que fica guardado localmente.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `client` | object | não | Como a instância aparece em "Aparelhos conectados" no celular. |
| `client.browserName` | string | não | Nome do navegador em "Aparelhos conectados". |
| `client.deviceName` | string | não | Nome do aparelho em "Aparelhos conectados" (até 40 caracteres). |
| `ignore` | object | não | Tipos de conversa cujos eventos não são emitidos. |
| `ignore.broadcast` | boolean | não | Não emitir eventos de listas de transmissão. |
| `ignore.channels` | boolean | não | Não emitir eventos de canais. |
| `ignore.groups` | boolean | não | Não emitir eventos de grupos. |
| `ignore.status` | boolean | não | Não emitir eventos de status (stories). |
| `storage` | object | não | O que a instância guarda para as rotas de leitura (`GET /chats`, `/contacts`, histórico). Desligar economiza memória, mas essas rotas passam a voltar vazias. |
| `storage.chats` | boolean | não | Guardar a lista de conversas. |
| `storage.contacts` | boolean | não | Guardar os contatos. |
| `storage.groups` | boolean | não | Guardar os grupos. |
| `storage.labels` | boolean | não | Guardar as etiquetas. |
| `storage.messageSecrets` | boolean | não | Guardar as chaves de mensagens (necessário para votos de enquete e edições). |
| `storage.messages` | boolean | não | Guardar mensagens (histórico das conversas). |

**Exemplo**

```bash
curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/settings" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```

## Conta do WhatsApp conectada

`GET /me` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/me" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "id": "5511999999999@c.us",
  "jid": "123123:123@s.whatsapp.net",
  "lid": "123123@lid",
  "messageCapping": {
    "cappingStatus": "FIRST_WARNING",
    "cycleEnd": 1785553199,
    "cycleStart": 1782874800,
    "mvStatus": "NOT_ELIGIBLE",
    "oteStatus": "NOT_ELIGIBLE",
    "totalQuota": 1000,
    "usedQuota": 640
  },
  "pushName": "Maria",
  "reachoutTimelock": {
    "enforcementType": "RESTRICT_ALL_COMPANIONS",
    "isActive": true,
    "timeEnforcementEnds": 1784477333
  }
}
```

## Cota de novas conversas (capping)

`GET /capping` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/capping" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "cappingStatus": "FIRST_WARNING",
  "cycleEnd": 1785553199,
  "cycleStart": 1782874800,
  "mvStatus": "NOT_ELIGIBLE",
  "oteStatus": "NOT_ELIGIBLE",
  "totalQuota": 1000,
  "usedQuota": 640
}
```

## Restrição de contato (timelock)

`GET /timelock` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/timelock" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "enforcementType": "RESTRICT_ALL_COMPANIONS",
  "isActive": true,
  "timeEnforcementEnds": 1784477333
}
```

## Iniciar a instância

`POST /start` · API OnZap

Liga a conexão (se o número já foi pareado, reconecta sem QR Code).

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/start" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```

## Parar a instância

`POST /stop` · API OnZap

Desliga a conexão sem desparear: um `start` depois reconecta sem QR Code.

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/stop" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```

## Reiniciar a instância

`POST /restart` · API OnZap

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/restart" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```

## Desconectar o WhatsApp (logout)

`POST /logout` · API OnZap

Desconecta o número (remove o aparelho no celular). Para conectar de novo é preciso ler o QR Code.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `apps` | object | não | Options for the session apps during logout. |
| `apps.purge` | boolean | não | Purge the session apps' storage (messages, caches) as part of logout. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/logout" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200** — Dados da instância

```json
{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}
```


---

# Pareamento

> Conectar o número: QR Code, código por telefone ou passkey.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## QR Code para conectar

`GET /qr-code` · API OnZap

QR Code para ler em WhatsApp → Aparelhos conectados, disponível com a instância em `SCAN_QR_CODE`. `format=image` devolve PNG; `format=raw`, o texto do QR. O código muda a cada ~20 s.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `format` | query | string | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/qr-code?format=VALOR" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "mimetype": "image/jpeg",
  "value": "valor"
}
```

## Código de pareamento por telefone

`POST /pairing-code` · API OnZap

Alternativa ao QR Code: gera um código de 8 caracteres (ex.: `KFXC-T63T`) para digitar no celular (WhatsApp → Aparelhos conectados → Conectar aparelho → Conectar com número de telefone). Envie em `phoneNumber` o número do WhatsApp que vai ser conectado, com DDI e DDD. Só funciona com a instância esperando conexão (`SCAN_QR_CODE`); o código vale por poucos minutos. No Brasil, se o celular disser que o número está errado, peça de novo sem o nono dígito (contas antigas podem estar registradas assim). Limitado a poucos pedidos a cada 10 minutos.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `phoneNumber` | string | sim | Mobile phone number in international format |
| `method` | string | não | How would you like to receive the one time code for registration? \|sms\|voice. Leave empty for Web pairing. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/pairing-code" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "5511999999999"
  }'
```

## Desafio de passkey pendente

`GET /passkey/challenge` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/passkey/challenge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "allowCredentials": [
    {
      "id": "3EB0C0A1B2C3D4E5F6",
      "transports": [
        "internal",
        "hybrid"
      ],
      "type": "public-key"
    }
  ],
  "challenge": "texto",
  "extensions": {},
  "rpId": "web.whatsapp.com",
  "timeout": 60000,
  "userVerification": "required"
}
```

## Enviar assinatura da passkey

`POST /passkey` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | string | sim | Credential ID, as returned by navigator.credentials.get().toJSON(). |
| `rawId` | string | sim | Base64url-encoded raw credential ID. |
| `response` | object | sim |  |
| `response.authenticatorData` | string | sim | Base64url-encoded authenticatorData from the authenticator. |
| `response.clientDataJSON` | string | sim | Base64url-encoded clientDataJSON from the authenticator. |
| `response.signature` | string | sim | Base64url-encoded signature from the authenticator. |
| `response.userHandle` | string | não | Base64url-encoded user handle, if returned by the authenticator. |
| `type` | string | sim | Always "public-key". |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/passkey" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3EB0C0A1B2C3D4E5F6",
    "rawId": "1234567890",
    "response": {
      "authenticatorData": "texto",
      "clientDataJSON": "texto",
      "signature": "t=1767225600,v1=5d41402abc4b2a76b9719d911017c592…"
    },
    "type": "public-key"
  }'
```

## Código de confirmação da passkey

`GET /passkey/confirmation` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/passkey/confirmation" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "code": "1234"
}
```

## Confirmar pareamento por passkey

`POST /passkey/confirm` · API OnZap

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/passkey/confirm" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Perfil

> Nome, recado e foto do número conectado.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Meu perfil

`GET /profile` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/profile" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "id": "5511999999999@c.us",
  "name": "Minha Loja",
  "picture": "https://example.com/picture.jpg"
}
```

## Alterar nome do perfil

`PUT /profile/name` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/profile/name" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Name"
  }'
```

**Resposta 200**

```json
{
  "success": true
}
```

## Alterar recado (about)

`PUT /profile/status` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | string | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/profile/status" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "🎉 Hey there! I am using WhatsApp 🎉"
  }'
```

**Resposta 200**

```json
{
  "success": true
}
```

## Alterar foto do perfil

`PUT /profile/picture` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/profile/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {}
  }'
```

**Resposta 200**

```json
{
  "success": true
}
```

## Remover foto do perfil

`DELETE /profile/picture` · API OnZap

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/profile/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "success": true
}
```


---

# Mensagens

> Envio de mensagens de todos os tipos, reações, leitura e "digitando…".

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Enviar texto

`POST /messages/text` · API OnZap, API oficial (Meta)

Links ganham prévia automaticamente (`linkPreview`). Para responder a uma mensagem, informe `reply_to` com o ID dela.

**Na API oficial:** até 4096 caracteres; prévia de link só com `linkPreview: true`. Fora da janela de 24 h desde a última mensagem do cliente, use `/messages/template`.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `text` | string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `id` | string | não | Pre-generated message id |
| `linkPreview` | boolean | não |  |
| `linkPreviewHighQuality` | boolean | não |  |
| `mentions` | array de string | não | Chat IDs to mention in the message. Use ["all"] to mention all participants in a group. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "text": "Olá! Seu pedido foi confirmado ✅"
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar imagem

`POST /messages/image` · API OnZap, API oficial (Meta)

Envie `file.url` (URL pública) ou `file.data` (base64) com `file.mimetype`.

**Na API oficial:** JPG ou PNG até 5 MB.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |
| `caption` | string | não |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `mentions` | array de string | não | Chat IDs to mention in the message. Use ["all"] to mention all participants in a group. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/image" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Confira o catálogo",
    "chatId": "5511999999999",
    "file": {
      "mimetype": "image/jpeg",
      "url": "https://exemplo.com.br/arquivos/catalogo.jpg"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar arquivo

`POST /messages/file` · API OnZap, API oficial (Meta)

Qualquer tipo de documento. Envie `file.url` ou `file.data` (base64), com `file.filename` e `file.mimetype`.

**Na API oficial:** até 100 MB.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |
| `caption` | string | não |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `mentions` | array de string | não | Chat IDs to mention in the message. Use ["all"] to mention all participants in a group. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/file" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Segue o boleto",
    "chatId": "5511999999999",
    "file": {
      "filename": "boleto.pdf",
      "mimetype": "application/pdf",
      "url": "https://exemplo.com.br/arquivos/boleto.pdf"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar áudio de voz

`POST /messages/voice` · API OnZap, API oficial (Meta)

Aparece como áudio gravado (ptt). Use OGG/Opus; com `convert: true` o áudio é convertido automaticamente.

**Na API oficial:** OGG/Opus até 16 MB.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `convert` | boolean | sim | Convert the input file to the required format using ffmpeg before sending |
| `file` | object | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/voice" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "convert": true,
    "file": {
      "mimetype": "audio/mpeg",
      "url": "https://exemplo.com.br/arquivos/audio.mp3"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar vídeo

`POST /messages/video` · API OnZap, API oficial (Meta)

MP4 (H.264). Com `convert: true` o vídeo é convertido automaticamente; `asNote: true` envia como vídeo redondo.

**Na API oficial:** MP4 ou 3GP até 16 MB.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `convert` | boolean | sim | Convert the input file to the required format using ffmpeg before sending |
| `file` | object | sim |  |
| `asNote` | boolean | não | Send as video note (aka instant or round video). |
| `caption` | string | não |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `mentions` | array de string | não | Chat IDs to mention in the message. Use ["all"] to mention all participants in a group. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/video" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Tutorial",
    "chatId": "5511999999999",
    "convert": true,
    "file": {
      "mimetype": "video/mp4",
      "url": "https://exemplo.com.br/arquivos/video.mp4"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar figurinha

`POST /messages/sticker` · API OnZap, API oficial (Meta)

**Na API oficial:** WEBP (512×512).

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/sticker" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "file": {
      "mimetype": "image/webp",
      "url": "https://exemplo.com.br/arquivos/figurinha.webp"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar link com prévia personalizada

`POST /messages/link-preview` · API OnZap, API oficial (Meta)

**Na API oficial:** vira texto com prévia gerada pelo WhatsApp (a imagem personalizada é ignorada).

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `preview` | object | sim |  |
| `preview.description` | string | sim |  |
| `preview.title` | string | sim |  |
| `preview.url` | string | sim |  |
| `preview.image` | object | não |  |
| `text` | string | sim | The text to send. MUST include the URL provided in preview.url |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `linkPreviewHighQuality` | boolean | não |  |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/link-preview" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "preview": {
      "description": "Até 40% de desconto",
      "title": "Promoção de primavera",
      "url": "https://exemplo.com.br/promo"
    },
    "text": "Veja a promoção: https://exemplo.com.br/promo"
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar botões

`POST /messages/buttons` · API oficial (Meta)

Botões de resposta, link, ligação ou copiar código.

**Na API oficial:** até 3 botões de resposta (20 caracteres) **ou** um único botão de link; ligação e copiar código só em templates.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `body` | string | sim |  |
| `buttons` | array de object | sim |  |
| `buttons[].text` | string | sim |  |
| `buttons[].type` | string | sim | Valores: `reply`, `url`, `call`, `copy`. |
| `buttons[].copyCode` | string | não |  |
| `buttons[].id` | string | não |  |
| `buttons[].phoneNumber` | string | não |  |
| `buttons[].url` | string | não |  |
| `footer` | string | sim |  |
| `header` | string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `headerImage` | object | não |  |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/buttons" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Podemos confirmar sua consulta de amanhã às 14h?",
    "buttons": [
      {
        "text": "Confirmar",
        "type": "reply"
      },
      {
        "text": "Remarcar",
        "type": "reply"
      }
    ],
    "chatId": "5511999999999",
    "footer": "Clínica Exemplo",
    "header": "Confirmação"
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar lista de opções

`POST /messages/list` · API OnZap, API oficial (Meta)

**Na API oficial:** até 10 seções e 10 opções no total; título da opção até 24 caracteres.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `message` | object | sim |  |
| `message.button` | string | sim |  |
| `message.sections` | array de object | sim |  |
| `message.sections[].rows` | array de object | sim |  |
| `message.sections[].title` | string | sim |  |
| `message.title` | string | sim |  |
| `message.description` | string | não |  |
| `message.footer` | string | não |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/list" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "message": {
      "button": "Ver opções",
      "description": "Escolha uma opção",
      "footer": "Pizzaria Exemplo",
      "sections": [
        {
          "rows": [
            {
              "description": "R$ 49,90",
              "rowId": "pizza_margherita",
              "title": "Margherita"
            },
            {
              "description": "R$ 52,90",
              "rowId": "pizza_calabresa",
              "title": "Calabresa"
            }
          ],
          "title": "Pizzas"
        }
      ],
      "title": "Cardápio"
    }
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar enquete

`POST /messages/poll` · API OnZap

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `poll` | object | sim |  |
| `poll.multipleAnswers` | object | sim |  |
| `poll.name` | string | sim |  |
| `poll.options` | array de string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `id` | string | não | Pre-generated message id |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/poll" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "poll": {
      "multipleAnswers": false,
      "name": "Qual o melhor horário?",
      "options": [
        "Manhã",
        "Tarde",
        "Noite"
      ]
    }
  }'
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Votar em enquete

`POST /messages/poll/vote` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `pollMessageId` | string | sim | The ID of the poll message. |
| `votes` | array de array de string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `pollServerId` | number | não | Only for Channels - server message id (if known); if omitted, API may look it up in the storage |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/poll/vote" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pollMessageId": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "votes": [
      "Awesome!"
    ]
  }'
```

## Enviar localização

`POST /messages/location` · API OnZap, API oficial (Meta)

**Na API oficial:** mesmo formato.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `latitude` | number | sim |  |
| `longitude` | number | sim |  |
| `title` | string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `id` | string | não | Pre-generated message id |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/location" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "latitude": -23.5613,
    "longitude": -46.6565,
    "title": "Nossa loja"
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar contato (vCard)

`POST /messages/contact-vcard` · API OnZap, API oficial (Meta)

**Na API oficial:** cada contato precisa de `fullName` e `phoneNumber` (vCard cru não é aceito).

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `contacts` | array de object | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `id` | string | não | Pre-generated message id |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/contact-vcard" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "contacts": [
      {
        "fullName": "Maria Souza",
        "organization": "Loja Exemplo",
        "phoneNumber": "+55 11 98888-7777",
        "whatsappId": "5511988887777"
      }
    ]
  }'
```

**Resposta 200** — API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Encaminhar mensagem

`POST /messages/forward` · API OnZap

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `messageId` | string | sim |  |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `id` | string | não | Pre-generated message id |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/forward" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "messageId": "true_5511888888888@c.us_3EB0C0A1B2C3D4E5F6"
  }'
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Marcar mensagens como lidas

`POST /messages/seen` · API OnZap, API oficial (Meta)

Marca como lidas (tique azul) as mensagens da conversa.

**Na API oficial:** marca a mensagem informada (ou a última recebida) como lida.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `messageId` | string | não |  |
| `messageIds` | array de string | não |  |
| `participant` | string | não |  |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/seen" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
```

**Resposta 200** — API oficial: ação concluída

```json
{
  "ok": false,
  "read": 0
}
```

**Resposta 201**

```json
{}
```

## Reagir a mensagem

`PUT /messages/reaction` · API OnZap, API oficial (Meta)

Emoji vazio (`""`) remove a reação.

**Na API oficial:** mesmo formato.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `messageId` | string | sim |  |
| `reaction` | string | sim | Emoji to react with. Send an empty string to remove the reaction |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/reaction" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "reaction": "👍"
  }'
```

**Resposta 200** — Sucesso · API oficial: mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "3EB0C0A1B2C3D4E5F6",
  "status": "ok"
}
```

## Gerar novo ID de mensagem

`GET /messages/new-id` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/new-id" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "id": "BBBBBBBBBBBBBBBBB"
}
```

## Enviar evento (agenda)

`POST /messages/event` · API OnZap

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `event` | object | sim |  |
| `event.name` | string | sim | Name of the event |
| `event.startTime` | number | sim | Start time of the event (Unix timestamp in seconds) |
| `event.description` | string | não | Description of the event |
| `event.endTime` | number | não | End time of the event (Unix timestamp in seconds) |
| `event.extraGuestsAllowed` | boolean | não | Whether extra guests are allowed |
| `event.location` | object | não | Location of the event |
| `event.location.name` | string | sim | Name of the location |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |
| `reply_to` | string | não | The ID of the message to reply to - false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/event" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "name": "John'\''s Nail Appointment 💅",
      "startTime": 2063137000
    }
  }'
```

**Resposta 201** — Mensagem enviada

```json
{
  "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Começar a digitar

`POST /typing/start` · API OnZap, API oficial (Meta)

Mostra "digitando…" na conversa até `POST /typing/stop` ou o envio da próxima mensagem.

**Na API oficial:** só funciona em resposta a uma mensagem recebida nas últimas 24 h; dura até 25 s ou até a resposta.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/typing/start" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
```

**Resposta 200** — API oficial: ação concluída

```json
{
  "ok": false,
  "read": 0
}
```

## Parar de digitar

`POST /typing/stop` · API OnZap, API oficial (Meta)

**Na API oficial:** a Meta remove o "digitando…" sozinha ao enviar a resposta.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/typing/stop" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
```

**Resposta 200** — API oficial: ação concluída

```json
{
  "ok": false,
  "read": 0
}
```

## Enviar template

`POST /messages/template` · API oficial (Meta)

Única forma de iniciar conversa (ou falar fora da janela de 24 h) na API oficial. Preencha os parâmetros de forma simples (`header`, `body`, `buttons`) ou mande `components` no formato da Cloud API.

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `template` | string | sim | Nome do template (também aceito como `name`). |
| `body` | array de string \| object | não | Variáveis do corpo: lista para `{{1}}`, `{{2}}`… ou objeto para variáveis nomeadas (`{{nome}}`). |
| `buttons` | array de object | não |  |
| `buttons[].index` | integer | sim | Posição do botão no template (0, 1, 2). |
| `buttons[].couponCode` | string | não | Código do botão copiar código. |
| `buttons[].payload` | string | não | Payload do botão de resposta rápida. |
| `buttons[].url` | string | não | Sufixo da URL dinâmica. |
| `chatId` | string | não | Número com DDI e DDD (`5511999999999`) ou `…@bsuid`. Pode ser enviado como `phone`. |
| `components` | array de object | não | Componentes no formato da Cloud API. Se informado, `header`, `body` e `buttons` são ignorados. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `header` | object | não |  |
| `header.document` | string | não | URL do documento do cabeçalho. |
| `header.filename` | string | não | Nome do documento. |
| `header.image` | string | não | URL da imagem do cabeçalho. |
| `header.text` | string | não | Variável do cabeçalho de texto. |
| `header.video` | string | não | URL do vídeo do cabeçalho. |
| `language` | string | não | Idioma do template. |
| `phone` | string | não | Apelido de `chatId`. |
| `reply_to` | string | não | ID da mensagem a responder (citação). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/template" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": [
      "Maria",
      "#1234"
    ],
    "chatId": "5511999999999",
    "language": "pt_BR",
    "template": "pedido_enviado"
  }'
```

**Resposta 200** — Mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Enviar mensagem interativa (formato da Meta)

`POST /messages/interactive` · API oficial (Meta)

Para recursos interativos que `/messages/buttons` e `/messages/list` não cobrem (ex.: `cta_url` com cabeçalho, `location_request_message`, `flow`). O objeto `interactive` vai como na [Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-messages).

Aceita `delayMessage` e `delayTyping` no corpo e o header `X-Queue` (veja **Fila de mensagens** na introdução). Enviada na hora, responde `201`/`200`; enfileirada, `202`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `X-Queue` | header | string | não | `true` manda este envio para a fila da instância; `false` envia na hora. Sem o header, vale o modo da instância (`delayMessage` ou `delayTyping` no corpo também implicam fila). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `interactive` | object | sim | Objeto `interactive` da Cloud API. |
| `chatId` | string | não | Número com DDI e DDD (`5511999999999`) ou `…@bsuid`. Pode ser enviado como `phone`. |
| `delayMessage` | number | não | Segundos de espera antes de enviar esta mensagem (usa a fila da instância). |
| `delayTyping` | number | não | Segundos mostrando "digitando…" antes de enviar (usa a fila da instância). |
| `phone` | string | não | Apelido de `chatId`. |
| `reply_to` | string | não | ID da mensagem a responder (citação). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/interactive" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "interactive": {}
  }'
```

**Resposta 200** — Mensagem aceita pela Meta

```json
{
  "chatId": "5511999999999@c.us",
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjNFQjBDMEExQjJDM0Q0RTVGNgA=",
  "status": "accepted"
}
```

**Resposta 202** — Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```


---

# Chats

> Conversas: listar, ler o histórico, editar e apagar mensagens, marcar como lidas.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar chats

`GET /chats` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `sortBy` | query | string | não | Sort by field |
| `sortOrder` | query | string | não | Sort order - <b>desc</b>ending (Z => A, New first) or <b>asc</b>ending (A => Z, Old first) |
| `merge` | query | boolean | não | Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact |
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Visão geral dos chats

`GET /chats/overview` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `merge` | query | boolean | não | Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact |
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |
| `ids` | query | array de string | não | Filter by chat ids |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/overview" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "_chat": {},
    "id": "5511999999999@c.us",
    "lastMessage": {},
    "name": "Maria Silva",
    "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…"
  }
]
```

## Visão geral dos chats (POST)

`POST /chats/overview` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `pagination` | object | sim |  |
| `pagination.limit` | number | não |  |
| `pagination.merge` | boolean | não | Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact |
| `pagination.offset` | number | não |  |
| `filter` | object | não |  |
| `filter.ids` | array de string | não | Filter by chat ids |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/overview" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": {}
  }'
```

**Resposta 201**

```json
[
  {
    "_chat": {},
    "id": "5511999999999@c.us",
    "lastMessage": {},
    "name": "Maria Silva",
    "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…"
  }
]
```

## Foto do chat

`GET /chats/{chatId}/picture` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `refresh` | query | boolean | não | Refresh the picture from the server (24h cache by default). Do not refresh if not needed, you can get rate limit error |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Mensagens do chat

`GET /chats/{chatId}/messages` · API OnZap

Histórico da conversa, das mais novas para as mais antigas. Com `downloadMedia=true`, as mídias vêm com link assinado.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `sortBy` | query | string | não | Sort by field |
| `sortOrder` | query | string | não | Sort order - <b>desc</b>ending (Z => A, New first) or <b>asc</b>ending (A => Z, Old first) |
| `downloadMedia` | query | boolean | não | Download media for messages |
| `merge` | query | boolean | não | Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact |
| `limit` | query | number | sim |  |
| `offset` | query | number | não |  |
| `filter.timestamp.lte` | query | number | não | Filter messages before this timestamp (inclusive) |
| `filter.timestamp.gte` | query | number | não | Filter messages after this timestamp (inclusive) |
| `filter.fromMe` | query | boolean | não | From me filter (by default shows all messages) |
| `filter.ack` | query | string | não | Filter messages by acknowledgment status |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages?limit=VALOR" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "_data": {},
    "ack": -1,
    "ackName": "READ",
    "author": "5521988887777@c.us",
    "body": "Olá! Seu pedido foi confirmado.",
    "from": "5511999999999@c.us",
    "fromMe": false,
    "hasMedia": false,
    "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "location": {
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "latitude": "-23.5613",
      "live": false,
      "longitude": "-46.6565",
      "name": "Loja Centro",
      "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "media": {
      "error": {},
      "filename": "example.pdf",
      "mimetype": "audio/jpeg",
      "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
    },
    "mediaUrl": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…",
    "participant": "5521988887777@c.us",
    "replyTo": {
      "_data": {},
      "body": "Hello!",
      "hasMedia": false,
      "id": "AAAAAAAAAAAAAAAAAAAA",
      "media": {
        "error": {},
        "filename": "example.pdf",
        "mimetype": "audio/jpeg",
        "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
      },
      "participant": "5511999999999@c.us"
    },
    "source": "api",
    "timestamp": 1666943582,
    "to": "5511999999999@c.us",
    "vCards": [
      "texto"
    ]
  }
]
```

## Ler mensagens não lidas do chat

`POST /chats/{chatId}/messages/read` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `messages` | query | number | não | How much messages to read (latest first) |
| `days` | query | number | não | How much days to read (latest first) |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/read" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 201**

```json
{
  "ids": [
    "texto"
  ]
}
```

## Mensagem por ID

`GET /chats/{chatId}/messages/{messageId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `messageId` | path | string | sim |  |
| `downloadMedia` | query | boolean | não | Download media for messages |
| `merge` | query | boolean | não | Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "_data": {},
  "ack": -1,
  "ackName": "READ",
  "author": "5521988887777@c.us",
  "body": "Olá! Seu pedido foi confirmado.",
  "from": "5511999999999@c.us",
  "fromMe": false,
  "hasMedia": false,
  "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
  "location": {
    "address": "Av. Paulista, 1000 - São Paulo, SP",
    "description": "Atendimento de segunda a sexta, das 9h às 18h.",
    "latitude": "-23.5613",
    "live": false,
    "longitude": "-46.6565",
    "name": "Loja Centro",
    "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
    "url": "https://exemplo.com.br/arquivos/pedido.jpg"
  },
  "media": {
    "error": {},
    "filename": "example.pdf",
    "mimetype": "audio/jpeg",
    "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
  },
  "mediaUrl": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…",
  "participant": "5521988887777@c.us",
  "replyTo": {
    "_data": {},
    "body": "Hello!",
    "hasMedia": false,
    "id": "AAAAAAAAAAAAAAAAAAAA",
    "media": {
      "error": {},
      "filename": "example.pdf",
      "mimetype": "audio/jpeg",
      "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
    },
    "participant": "5511999999999@c.us"
  },
  "source": "api",
  "timestamp": 1666943582,
  "to": "5511999999999@c.us",
  "vCards": [
    "texto"
  ]
}
```

## Apagar mensagem

`DELETE /chats/{chatId}/messages/{messageId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `messageId` | path | string | sim | Message ID in format <code>{fromMe}_{chat}_{message_id}[_{participant}]</code> |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/true_123456789@c.us_BAE6A33293978B16" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Editar mensagem

`PUT /chats/{chatId}/messages/{messageId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `messageId` | path | string | sim | Message ID in format <code>{fromMe}_{chat}_{message_id}[_{participant}]</code> |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `text` | string | sim |  |
| `linkPreview` | boolean | não |  |
| `linkPreviewHighQuality` | boolean | não |  |
| `mentions` | array de string | não | Chat IDs to mention in the message. Use ["all"] to mention all participants in a group. |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/true_123456789@c.us_BAE6A33293978B16" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!"
  }'
```

## Marcar chat como não lido

`POST /chats/{chatId}/unread` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/unread" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 201**

```json
{}
```


---

# Contatos

> Agenda, verificação de números e foto de perfil.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar contatos

`GET /contacts` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `sortBy` | query | string | não | Sort by field |
| `sortOrder` | query | string | não | Sort order - <b>desc</b>ending (Z => A, New first) or <b>asc</b>ending (A => Z, Old first) |
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/contacts" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Verificar se o número tem WhatsApp

`GET /contacts/check-exists` · API OnZap

Confere se o número tem WhatsApp e devolve o `chatId` correto (no Brasil, resolve o nono dígito). Use antes de enviar para números de origem desconhecida.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `phone` | query | string | sim | The phone number to check |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/contacts/check-exists?phone=1213213213" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "chatId": "Chat id for the phone number. Undefined if the number does not exist",
  "numberExists": false,
  "pn": "5511999999999@c.us"
}
```

## Dados do contato

`GET /contacts/{contactId}` · API OnZap, API oficial (Meta)

**Na API oficial:** devolve o que sabemos pelas conversas (nome, telefone, BSUID); a Meta não tem agenda de contatos.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `contactId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/contacts/5511999999999" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — API oficial: o que sabemos do contato pelas conversas

```json
{
  "bsuid": "BR.1349120865530274191",
  "id": "5511999999999@c.us",
  "lid": "36576092528787@lid",
  "phone": "5511999999999",
  "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
  "pushName": "Maria",
  "username": "maria.silva"
}
```

## Criar ou atualizar contato

`PUT /contacts/{contactId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `contactId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `firstName` | string | sim | Contact First Name |
| `lastName` | string | sim | Contact Last Name |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/contacts/5511999999999" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe"
  }'
```

**Resposta 200**

```json
{
  "success": true
}
```

## Foto do contato

`GET /contacts/{contactId}/picture` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `contactId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |
| `refresh` | query | boolean | não | Refresh the picture from the server (24h cache by default). Do not refresh if not needed, you can get rate limit error |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/contacts/5511999999999/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Mapeamento LID → telefone

`GET /lids` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/lids" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "lid": "1111111@lid",
    "pn": "3333333@c.us"
  }
]
```

## Quantidade de LIDs conhecidos

`GET /lids/count` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/lids/count" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "count": 0
}
```

## LID pelo telefone

`GET /lids/pn/{phoneNumber}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `phoneNumber` | path | string | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/lids/pn/PHONENUMBER" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "lid": "1111111@lid",
  "pn": "3333333@c.us"
}
```

## Telefone pelo LID

`GET /lids/{lid}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `lid` | path | string | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/lids/36576092528787@lid" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "lid": "1111111@lid",
  "pn": "3333333@c.us"
}
```


---

# Grupos

> Criar e administrar grupos, participantes e convites.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Criar grupo

`POST /groups` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Equipe Vendas",
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

## Listar grupos

`GET /groups` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `sortBy` | query | string | não | Sort by field |
| `sortOrder` | query | string | não | Sort order - <b>desc</b>ending (Z => A, New first) or <b>asc</b>ending (A => Z, Old first) |
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |
| `exclude` | query | array de string | não | Exclude fields |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{}
```

## Dados do grupo antes de entrar

`GET /groups/join-info` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `code` | query | string | sim | Group code (123) or url (https://chat.whatsapp.com/123) |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/join-info?code=https%3A%2F%2Fchat.whatsapp.com%2F1234567890abcdef" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{}
```

## Entrar no grupo por convite

`POST /groups/join` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `code` | string | sim | Group code (123) or url (https://chat.whatsapp.com/123) |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/join" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "https://chat.whatsapp.com/1234567890abcdef"
  }'
```

**Resposta 200**

```json
{
  "id": "123@g.us"
}
```

## Quantidade de grupos

`GET /groups/count` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/count" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "count": 0
}
```

## Atualizar grupos do servidor

`POST /groups/refresh` · API OnZap

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/refresh" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Dados do grupo

`GET /groups/{groupId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Sair do grupo

`POST /groups/{groupId}/leave` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/leave" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Foto do grupo

`GET /groups/{groupId}/picture` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |
| `refresh` | query | boolean | não | Refresh the picture from the server (24h cache by default). Do not refresh if not needed, you can get rate limit error |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Alterar foto do grupo

`PUT /groups/{groupId}/picture` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {}
  }'
```

**Resposta 200**

```json
{
  "success": true
}
```

## Remover foto do grupo

`DELETE /groups/{groupId}/picture` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "success": true
}
```

## Alterar descrição do grupo

`PUT /groups/{groupId}/description` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `description` | string | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/description" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Atendimento de segunda a sexta, das 9h às 18h."
  }'
```

## Alterar nome do grupo

`PUT /groups/{groupId}/subject` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subject` | string | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/subject" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Equipe Vendas"
  }'
```

## Só admins editam dados do grupo

`PUT /groups/{groupId}/settings/security/info-admin-only` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `adminsOnly` | boolean | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/info-admin-only" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adminsOnly": true
  }'
```

## Consultar: só admins editam dados

`GET /groups/{groupId}/settings/security/info-admin-only` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/info-admin-only" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "adminsOnly": true
}
```

## Só admins enviam mensagens

`PUT /groups/{groupId}/settings/security/messages-admin-only` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `adminsOnly` | boolean | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/messages-admin-only" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adminsOnly": true
  }'
```

## Consultar: só admins enviam mensagens

`GET /groups/{groupId}/settings/security/messages-admin-only` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/messages-admin-only" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "adminsOnly": true
}
```

## Quem pode adicionar membros

`PUT /groups/{groupId}/settings/security/member-add-mode` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `membersCanAddNewMember` | boolean | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/member-add-mode" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "membersCanAddNewMember": true
  }'
```

## Consultar quem pode adicionar membros

`GET /groups/{groupId}/settings/security/member-add-mode` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/member-add-mode" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "membersCanAddNewMember": true
}
```

## Exigir aprovação de novos membros

`PUT /groups/{groupId}/settings/security/membership-approval` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `newMembersApprovalRequired` | boolean | sim |  |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/membership-approval" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newMembersApprovalRequired": false
  }'
```

**Resposta 200**

```json
false
```

## Consultar aprovação de novos membros

`GET /groups/{groupId}/settings/security/membership-approval` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/settings/security/membership-approval" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "newMembersApprovalRequired": false
}
```

## Pedidos pendentes para entrar

`GET /groups/{groupId}/participants/join-requests` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/join-requests" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "addedById": "123456789@c.us",
    "parentGroupId": "123456789@g.us",
    "requestMethod": "invite_link",
    "requesterId": "123456789@c.us",
    "requesterPn": "123456789@c.us",
    "timestamp": 1666943582
  }
]
```

## Aprovar pedidos para entrar

`POST /groups/{groupId}/participants/join-requests/approve` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/join-requests/approve" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

**Resposta 200**

```json
[
  {
    "error": 404,
    "requesterId": "123456789@c.us",
    "success": true
  }
]
```

## Rejeitar pedidos para entrar

`POST /groups/{groupId}/participants/join-requests/reject` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/join-requests/reject" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

**Resposta 200**

```json
[
  {
    "error": 404,
    "requesterId": "123456789@c.us",
    "success": true
  }
]
```

## Código de convite do grupo

`GET /groups/{groupId}/invite-code` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/invite-code" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
"texto"
```

## Revogar código de convite

`POST /groups/{groupId}/invite-code/revoke` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/invite-code/revoke" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
"texto"
```

## Participantes do grupo

`GET /groups/{groupId}/participants` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Participantes do grupo (v2)

`GET /groups/{groupId}/participants/v2` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/v2" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "id": "123456789@lid",
    "pn": "123456789@c.us",
    "role": "participant"
  }
]
```

## Adicionar participantes

`POST /groups/{groupId}/participants/add` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/add" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

## Remover participantes

`POST /groups/{groupId}/participants/remove` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/participants/remove" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

## Promover a admin

`POST /groups/{groupId}/admin/promote` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/admin/promote" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```

## Remover de admin

`POST /groups/{groupId}/admin/demote` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `groupId` | path | string | sim | Group ID |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/groups/123123123@g.us/admin/demote" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      {
        "id": "123456789@c.us"
      }
    ]
  }'
```


---

# Canais

> Canais (newsletters): criar, seguir e buscar.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar canais conhecidos

`GET /channels` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `role` | query | string | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "description": "Atendimento de segunda a sexta, das 9h às 18h.",
    "id": "123123123123@newsletter",
    "invite": "https://www.whatsapp.com/channel/111111111111111111111111",
    "name": "Channel Name",
    "picture": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
    "preview": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
    "role": "OWNER",
    "subscribersCount": 0,
    "verified": false
  }
]
```

## Criar canal

`POST /channels` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `description` | string | não |  |
| `picture` | object | não |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Channel Name"
  }'
```

**Resposta 201**

```json
{
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "id": "123123123123@newsletter",
  "invite": "https://www.whatsapp.com/channel/111111111111111111111111",
  "name": "Channel Name",
  "picture": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
  "preview": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
  "role": "OWNER",
  "subscribersCount": 0,
  "verified": false
}
```

## Buscar canais por visão

`POST /channels/search/by-view` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `categories` | array de string | sim |  |
| `countries` | array de string | sim |  |
| `limit` | number | sim |  |
| `startCursor` | string | sim |  |
| `view` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/search/by-view" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [],
    "countries": [
      "US"
    ],
    "limit": 50,
    "startCursor": "",
    "view": "RECOMMENDED"
  }'
```

**Resposta 200**

```json
{
  "channels": [
    {
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "id": "123123123123@newsletter",
      "invite": "https://www.whatsapp.com/channel/111111111111111111111111",
      "name": "Channel Name",
      "picture": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
      "preview": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
      "subscribersCount": 0,
      "verified": false
    }
  ],
  "page": {
    "endCursor": "eyJvZmZzZXQiOjUwfQ",
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": "eyJvZmZzZXQiOjB9"
  }
}
```

## Buscar canais por texto

`POST /channels/search/by-text` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `categories` | array de string | sim |  |
| `limit` | number | sim |  |
| `startCursor` | string | sim |  |
| `text` | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/search/by-text" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [],
    "limit": 50,
    "startCursor": "",
    "text": "Donald Trump"
  }'
```

**Resposta 200**

```json
{
  "channels": [
    {
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "id": "123123123123@newsletter",
      "invite": "https://www.whatsapp.com/channel/111111111111111111111111",
      "name": "Channel Name",
      "picture": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
      "preview": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
      "subscribersCount": 0,
      "verified": false
    }
  ],
  "page": {
    "endCursor": "eyJvZmZzZXQiOjUwfQ",
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": "eyJvZmZzZXQiOjB9"
  }
}
```

## Visões disponíveis para busca

`GET /channels/search/views` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/search/views" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "name": "Recomendados",
    "value": "RECOMMENDED"
  }
]
```

## Países disponíveis para busca

`GET /channels/search/countries` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/search/countries" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "code": "ABCD-EFGH",
    "name": "Brasil"
  }
]
```

## Categorias disponíveis para busca

`GET /channels/search/categories` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/search/categories" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "name": "Negócios",
    "value": "BUSINESS"
  }
]
```

## Dados do canal

`GET /channels/{channelId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | WhatsApp Channel ID or invite code from invite link https://www.whatsapp.com/channel/11111 |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "id": "123123123123@newsletter",
  "invite": "https://www.whatsapp.com/channel/111111111111111111111111",
  "name": "Channel Name",
  "picture": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
  "preview": "https://mmg.whatsapp.net/m1/v/t24/An&_nc_cat=10",
  "role": "OWNER",
  "subscribersCount": 0,
  "verified": false
}
```

## Prévia das mensagens do canal

`GET /channels/{channelId}/messages/preview` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | Channel id or invite code |
| `downloadMedia` | query | boolean | sim |  |
| `limit` | query | number | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter/messages/preview?downloadMedia=VALOR&limit=VALOR" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "message": {
      "_data": {},
      "ack": -1,
      "ackName": "READ",
      "author": "5521988887777@c.us",
      "body": "Olá! Seu pedido foi confirmado.",
      "from": "5511999999999@c.us",
      "fromMe": false,
      "hasMedia": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "location": {
        "address": "Av. Paulista, 1000 - São Paulo, SP",
        "description": "Atendimento de segunda a sexta, das 9h às 18h.",
        "latitude": "-23.5613",
        "live": false,
        "longitude": "-46.6565",
        "name": "Loja Centro",
        "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
        "url": "https://exemplo.com.br/arquivos/pedido.jpg"
      },
      "media": {
        "error": {},
        "filename": "example.pdf",
        "mimetype": "audio/jpeg",
        "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
      },
      "mediaUrl": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…",
      "participant": "5521988887777@c.us",
      "replyTo": {
        "_data": {},
        "body": "Hello!",
        "hasMedia": false,
        "id": "AAAAAAAAAAAAAAAAAAAA",
        "media": {},
        "participant": "5511999999999@c.us"
      },
      "source": "api",
      "timestamp": 1666943582,
      "to": "5511999999999@c.us",
      "vCards": [
        "texto"
      ]
    },
    "reactions": {
      "❤️": 5,
      "👍": 10
    },
    "viewCount": 0
  }
]
```

## Seguir canal

`POST /channels/{channelId}/follow` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | WhatsApp Channel ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter/follow" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Deixar de seguir canal

`POST /channels/{channelId}/unfollow` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | WhatsApp Channel ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter/unfollow" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Silenciar canal

`POST /channels/{channelId}/mute` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | WhatsApp Channel ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter/mute" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Reativar notificações do canal

`POST /channels/{channelId}/unmute` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `channelId` | path | any | sim | WhatsApp Channel ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/channels/120363000000000000@newsletter/unmute" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Status (stories)

> Publicar status de texto, imagem, voz e vídeo.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Publicar status de texto

`POST /status/text` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `backgroundColor` | string | sim |  |
| `font` | number | sim |  |
| `text` | string | sim |  |
| `contacts` | array de string | não | Contact list to send the status to. |
| `id` | string | não | Pre-generated status message id |
| `linkPreview` | boolean | não |  |
| `linkPreviewHighQuality` | boolean | não |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/text" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backgroundColor": "#38b42f",
    "font": 0,
    "text": "Have a look! https://github.com/"
  }'
```

## Publicar status de imagem

`POST /status/image` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |
| `caption` | string | não |  |
| `contacts` | array de string | não | Contact list to send the status to. |
| `id` | string | não | Pre-generated status message id |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/image" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {}
  }'
```

## Publicar status de voz

`POST /status/voice` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `backgroundColor` | string | sim |  |
| `convert` | boolean | sim | Convert the input file to the required format using ffmpeg before sending |
| `file` | object | sim |  |
| `contacts` | array de string | não | Contact list to send the status to. |
| `id` | string | não | Pre-generated status message id |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/voice" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backgroundColor": "#38b42f",
    "convert": true,
    "file": {}
  }'
```

## Publicar status de vídeo

`POST /status/video` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `convert` | boolean | sim | Convert the input file to the required format using ffmpeg before sending |
| `file` | object | sim |  |
| `caption` | string | não |  |
| `contacts` | array de string | não | Contact list to send the status to. |
| `id` | string | não | Pre-generated status message id |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/video" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "convert": true,
    "file": {}
  }'
```

## Apagar status publicado

`POST /status/delete` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `contacts` | array de string | não | Contact list to send the status to. |
| `id` | string | não | Status message id to delete |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/delete" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Gerar ID para status em lotes

`GET /status/new-message-id` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/status/new-message-id" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "id": "BBBBBBBBBBBBBBBBB"
}
```


---

# Etiquetas

> Etiquetas do WhatsApp Business.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar etiquetas

`GET /labels` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "color": 0,
    "colorHex": "#ff9485",
    "id": "1",
    "name": "Lead"
  }
]
```

## Criar etiqueta

`POST /labels` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim | Label name |
| `color` | number | não | Color number, not hex |
| `colorHex` | string | não | Color in hex |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead"
  }'
```

**Resposta 201**

```json
{
  "color": 0,
  "colorHex": "#ff9485",
  "id": "1",
  "name": "Lead"
}
```

## Etiquetas do chat

`GET /labels/chats/{chatId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels/chats/5511999999999" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "color": 0,
    "colorHex": "#ff9485",
    "id": "1",
    "name": "Lead"
  }
]
```

## Definir etiquetas do chat

`PUT /labels/chats/{chatId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `labels` | array de object | sim |  |
| `labels[].id` | string | sim | Label ID |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels/chats/5511999999999" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": [
      {
        "id": "1"
      }
    ]
  }'
```

## Atualizar etiqueta

`PUT /labels/{labelId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `labelId` | path | string | sim |  |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim | Label name |
| `color` | number | não | Color number, not hex |
| `colorHex` | string | não | Color in hex |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels/LABELID" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead"
  }'
```

**Resposta 200**

```json
{
  "color": 0,
  "colorHex": "#ff9485",
  "id": "1",
  "name": "Lead"
}
```

## Excluir etiqueta

`DELETE /labels/{labelId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `labelId` | path | string | sim |  |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels/LABELID" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{}
```

## Chats com a etiqueta

`GET /labels/{labelId}/chats` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `labelId` | path | string | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/labels/LABELID/chats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Presença

> Online, digitando e visto por último.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Definir presença

`POST /presence` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `presence` | string | sim | Valores: `offline`, `online`, `typing`, `recording`, `paused`. |
| `chatId` | string | não | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). Pode ser enviado como `phone`. |
| `phone` | string | não | Apelido de `chatId`: número com DDI e DDD. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/presence" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "presence": "offline"
  }'
```

## Presenças assinadas

`GET /presence` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/presence" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
[
  {
    "id": "5511999999999@c.us",
    "presences": [
      {
        "lastKnownPresence": "offline",
        "lastSeen": 1686568773,
        "participant": "5511999999999@c.us"
      }
    ]
  }
]
```

## Presença de um chat

`GET /presence/{chatId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/presence/5511999999999" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200**

```json
{
  "id": "5511999999999@c.us",
  "presences": [
    {
      "lastKnownPresence": "offline",
      "lastSeen": 1686568773,
      "participant": "5511999999999@c.us"
    }
  ]
}
```

## Assinar presença de um chat

`POST /presence/{chatId}/subscribe` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `chatId` | path | string | sim | Conversa: número com DDI e DDD (`5511999999999`) ou JID (`…@c.us`, `…@g.us`, `…@lid`). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/presence/5511999999999/subscribe" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Chamadas

> Recusar chamadas recebidas.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Rejeitar chamada recebida

`POST /calls/reject` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `from` | string | sim |  |
| `id` | string | sim | Call ID |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/calls/reject" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "5511999999999@c.us",
    "id": "ABCDEFGABCDEFGABCDEFGABCDEFG"
  }'
```


---

# Mídia

> Converter áudio e vídeo para o formato do WhatsApp.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Converter áudio para o formato do WhatsApp (opus)

`POST /media/convert/voice` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data` | string | não | Base64 content of the file |
| `url` | string | não | The URL for the voice file |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/media/convert/voice" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200**

```json
{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "mimetype": "image/jpeg"
}
```

## Converter vídeo para o formato do WhatsApp (mp4)

`POST /media/convert/video` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data` | string | não | Base64 content of the file |
| `url` | string | não | The URL for the video file |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/media/convert/video" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200**

```json
{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "mimetype": "image/jpeg"
}
```


---

# Integrações

> Integrações prontas (ex.: Chatwoot) ligadas à instância.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar integrações

`GET /integrations` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Criar integração

`POST /integrations` · API OnZap

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `app` | string | sim | Valores: `argentine-phone-numbers`, `brazilian-phone-numbers`, `chatwoot`, `calls`, `mcp`, `mexican-phone-numbers`, `phone-numbers`. |
| `config` | object | sim |  |
| `id` | string | sim |  |
| `enabled` | boolean | não | Enable or disable this app without deleting it. If omitted, treated as enabled (true). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "argentine-phone-numbers",
    "config": {},
    "id": "app_01jabcdefghjkmnpqrstvwxy"
  }'
```

## Dados da integração

`GET /integrations/{appId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `appId` | path | string | sim |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/APPID" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Atualizar integração

`PUT /integrations/{appId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `appId` | path | string | sim |  |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `app` | string | sim | Valores: `argentine-phone-numbers`, `brazilian-phone-numbers`, `chatwoot`, `calls`, `mcp`, `mexican-phone-numbers`, `phone-numbers`. |
| `config` | object | sim |  |
| `id` | string | sim |  |
| `enabled` | boolean | não | Enable or disable this app without deleting it. If omitted, treated as enabled (true). |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/APPID" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "argentine-phone-numbers",
    "config": {},
    "id": "app_01jabcdefghjkmnpqrstvwxy"
  }'
```

## Excluir integração

`DELETE /integrations/{appId}` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `appId` | path | string | sim |  |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/APPID" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar dados armazenados da integração

`POST /integrations/{appId}/purge` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `appId` | path | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/APPID/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar dados de uma integração pelo tipo

`POST /integrations/types/{app}/purge` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `app` | path | string | sim |  |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/types/APP/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache em memória — números (regras próprias)

`GET /integrations/phone-numbers/cache/memory` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/phone-numbers/cache/memory" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache persistente — números (regras próprias)

`GET /integrations/phone-numbers/cache/db` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/phone-numbers/cache/db" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Estatísticas do cache — números (regras próprias)

`GET /integrations/phone-numbers/cache/stats` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/phone-numbers/cache/stats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar cache — números (regras próprias)

`DELETE /integrations/phone-numbers/cache/purge` · API OnZap

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/phone-numbers/cache/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache em memória — números brasileiros (9º dígito)

`GET /integrations/brazilian-phone-numbers/cache/memory` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/brazilian-phone-numbers/cache/memory" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache persistente — números brasileiros (9º dígito)

`GET /integrations/brazilian-phone-numbers/cache/db` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/brazilian-phone-numbers/cache/db" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Estatísticas do cache — números brasileiros (9º dígito)

`GET /integrations/brazilian-phone-numbers/cache/stats` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/brazilian-phone-numbers/cache/stats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar cache — números brasileiros (9º dígito)

`DELETE /integrations/brazilian-phone-numbers/cache/purge` · API OnZap

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/brazilian-phone-numbers/cache/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache em memória — números argentinos

`GET /integrations/argentine-phone-numbers/cache/memory` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/argentine-phone-numbers/cache/memory" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache persistente — números argentinos

`GET /integrations/argentine-phone-numbers/cache/db` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/argentine-phone-numbers/cache/db" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Estatísticas do cache — números argentinos

`GET /integrations/argentine-phone-numbers/cache/stats` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/argentine-phone-numbers/cache/stats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar cache — números argentinos

`DELETE /integrations/argentine-phone-numbers/cache/purge` · API OnZap

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/argentine-phone-numbers/cache/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache em memória — números mexicanos

`GET /integrations/mexican-phone-numbers/cache/memory` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/mexican-phone-numbers/cache/memory" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Cache persistente — números mexicanos

`GET /integrations/mexican-phone-numbers/cache/db` · API OnZap

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `limit` | query | number | não |  |
| `offset` | query | number | não |  |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/mexican-phone-numbers/cache/db" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Estatísticas do cache — números mexicanos

`GET /integrations/mexican-phone-numbers/cache/stats` · API OnZap

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/mexican-phone-numbers/cache/stats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Limpar cache — números mexicanos

`DELETE /integrations/mexican-phone-numbers/cache/purge` · API OnZap

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/integrations/mexican-phone-numbers/cache/purge" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Fila

> Fila de envio da instância: intervalo entre mensagens, "digitando…" e espera por reconexão.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar a fila

`GET /queue` · API OnZap, API oficial (Meta)

Por padrão, só o que ainda vai ser enviado, na ordem de envio. Com `status`, o histórico (7 dias), do mais novo para o mais antigo.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `status` | query | string | não | `pending` (padrão): aguardando envio; `all`: tudo; ou um status final. |
| `limit` | query | integer | não | Itens por página (padrão 50, máximo 100). |
| `cursor` | query | string | não | Continuação: o `nextCursor` da página anterior. |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Página da fila

```json
{
  "data": [
    {
      "attempts": 1,
      "chatId": "5511999999999@c.us",
      "createdAt": "2026-09-30T14:05:00Z",
      "delayMs": 3000,
      "error": "número sem WhatsApp",
      "expiresAt": "2026-09-30T14:05:00Z",
      "finishedAt": "2026-09-30T14:05:00Z",
      "id": "qm_01jabcdefghjkmnpqrstvwxyz",
      "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
      "position": 1,
      "route": "POST /messages/text",
      "status": "queued",
      "typingMs": 2000
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjUwfQ",
  "paused": false,
  "pending": 0
}
```

## Cancelar todos os envios pendentes

`DELETE /queue` · API OnZap, API oficial (Meta)

Cada envio cancelado dispara `queue.failed` com status `cancelled`.

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Envios cancelados

```json
{
  "cancelled": 0
}
```

## Configurações da fila

`GET /queue/settings` · API OnZap, API oficial (Meta)

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/settings" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Configurações

```json
{
  "delayMax": 0,
  "delayMin": 0,
  "mode": "direct",
  "paused": false,
  "pending": 0,
  "ttlHours": 0
}
```

## Alterar configurações da fila

`PATCH /queue/settings` · API OnZap, API oficial (Meta)

Só os campos enviados mudam. `delayMin`/`delayMax` (0–60 s) valem para envios sem `delayMessage`; `ttlHours` (1–168) é quanto um envio espera a reconexão.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `delayMax` | integer | não |  |
| `delayMin` | integer | não |  |
| `mode` | string | não | `direct` ou `queue`. |
| `ttlHours` | integer | não |  |

**Exemplo**

```bash
curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/settings" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200** — Configurações atualizadas

```json
{
  "delayMax": 0,
  "delayMin": 0,
  "mode": "direct",
  "paused": false,
  "pending": 0,
  "ttlHours": 0
}
```

## Pausar a fila

`POST /queue/pause` · API OnZap, API oficial (Meta)

Nada sai da fila até `POST /queue/resume`. Novos envios continuam entrando.

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/pause" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Configurações

```json
{
  "delayMax": 0,
  "delayMin": 0,
  "mode": "direct",
  "paused": false,
  "pending": 0,
  "ttlHours": 0
}
```

## Retomar a fila

`POST /queue/resume` · API OnZap, API oficial (Meta)

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/resume" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Configurações

```json
{
  "delayMax": 0,
  "delayMin": 0,
  "mode": "direct",
  "paused": false,
  "pending": 0,
  "ttlHours": 0
}
```

## Consultar um envio da fila

`GET /queue/{queueId}` · API OnZap, API oficial (Meta)

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `queueId` | path | string | sim | ID do envio na fila (campo `id` da resposta 202). |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Envio

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```

## Cancelar um envio da fila

`DELETE /queue/{queueId}` · API OnZap, API oficial (Meta)

Só envios ainda aguardando (`queued`).

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `queueId` | path | string | sim | ID do envio na fila (campo `id` da resposta 202). |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/queue/01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Envio cancelado

```json
{
  "attempts": 1,
  "chatId": "5511999999999@c.us",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}
```


---

# Webhooks

> Endereços que recebem os eventos da instância, com histórico de entregas.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar webhooks

`GET /webhooks` · API OnZap, API oficial (Meta)

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Webhooks da instância e eventos disponíveis

```json
{
  "data": [
    {
      "consecutiveFailures": 0,
      "createdAt": "2026-09-30T14:05:00Z",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "disabledAt": "2026-09-30T14:05:00Z",
      "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
      "enabled": false,
      "events": [
        "message.any"
      ],
      "failingSince": "2026-09-30T14:05:00Z",
      "headers": {},
      "id": "whk_01jabcdefghjkmnpqrstvwxy",
      "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
      "instanceName": "Loja Centro",
      "lastDeliveryAt": "2026-09-30T14:05:00Z",
      "lastSuccess": false,
      "secret": "8f14e45fceea167a5a36dedd4bea2543",
      "updatedAt": "2026-09-30T14:05:00Z",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    }
  ],
  "events": [
    "message.any"
  ]
}
```

## Criar webhook

`POST /webhooks` · API OnZap, API oficial (Meta)

Até 5 por instância. O `secret` gerado vem na resposta: use-o para conferir `X-OnZap-Signature`.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `events` | array de string | sim | Eventos a receber (`*` = todos). Lista completa na seção Webhooks. |
| `url` | string | sim | Endereço HTTPS público. |
| `description` | string | não | Descrição livre, para você identificar o webhook. |
| `enabled` | boolean | não | Ativa ou desativa sem apagar. |
| `headers` | object | não | Headers extras (não podem sobrescrever Content-Type, User-Agent nem os X-OnZap-*). |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "message",
      "message.ack"
    ],
    "url": "https://seu-sistema.com.br/webhooks/whatsapp"
  }'
```

**Resposta 201** — Webhook criado

```json
{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Consultar webhook

`GET /webhooks/{webhookId}` · API OnZap, API oficial (Meta)

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Webhook

```json
{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Alterar webhook

`PATCH /webhooks/{webhookId}` · API OnZap, API oficial (Meta)

Só os campos enviados mudam. Reativar (`enabled: true`) zera o contador de falhas.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `description` | string | não | Descrição livre, para você identificar o webhook. |
| `enabled` | boolean | não | Ativa ou desativa sem apagar. |
| `events` | array de string | não | Eventos a receber (`*` = todos). Lista completa na seção Webhooks. |
| `headers` | object | não | Headers extras (não podem sobrescrever Content-Type, User-Agent nem os X-OnZap-*). |
| `url` | string | não | Endereço HTTPS público. |

**Exemplo**

```bash
curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200** — Webhook atualizado

```json
{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Excluir webhook

`DELETE /webhooks/{webhookId}` · API OnZap, API oficial (Meta)

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

## Enviar evento de teste

`POST /webhooks/{webhookId}/test` · API OnZap, API oficial (Meta)

Entrega um `webhook.test` só para este webhook (mesmo desativado). Acompanhe em `/deliveries`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/test" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 202** — Teste enfileirado

```json
{
  "event": "webhook.test",
  "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0"
}
```

## Gerar novo segredo

`POST /webhooks/{webhookId}/rotate-secret` · API OnZap, API oficial (Meta)

O segredo anterior deixa de valer imediatamente.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/rotate-secret" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Webhook com o novo segredo

```json
{
  "consecutiveFailures": 0,
  "createdAt": "2026-09-30T14:05:00Z",
  "description": "Atendimento de segunda a sexta, das 9h às 18h.",
  "disabledAt": "2026-09-30T14:05:00Z",
  "disabledReason": "20 falhas seguidas desde 30/09 às 14:05",
  "enabled": false,
  "events": [
    "message.any"
  ],
  "failingSince": "2026-09-30T14:05:00Z",
  "headers": {},
  "id": "whk_01jabcdefghjkmnpqrstvwxy",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "instanceName": "Loja Centro",
  "lastDeliveryAt": "2026-09-30T14:05:00Z",
  "lastSuccess": false,
  "secret": "8f14e45fceea167a5a36dedd4bea2543",
  "updatedAt": "2026-09-30T14:05:00Z",
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}
```

## Histórico de entregas

`GET /webhooks/{webhookId}/deliveries` · API OnZap, API oficial (Meta)

Entregas dos últimos 30 dias, das mais novas para as mais antigas.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |
| `status` | query | string | não | Filtra pelo resultado. |
| `limit` | query | integer | não | Itens por página (padrão 50, máximo 100). |
| `cursor` | query | string | não | Continuação: o `nextCursor` da página anterior. |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Página de entregas

```json
{
  "data": [
    {
      "attempts": 1,
      "createdAt": "2026-09-30T14:05:00Z",
      "durationMs": 0,
      "error": "número sem WhatsApp",
      "event": "message.any",
      "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0",
      "id": "dlv_01jabcdefghjkmnpqrstvwxy",
      "nextAttemptAt": "2026-09-30T14:05:00Z",
      "response": "{\"id\":\"false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6\"}",
      "status": "success",
      "statusCode": 0,
      "updatedAt": "2026-09-30T14:05:00Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjUwfQ"
}
```

## Consultar entrega

`GET /webhooks/{webhookId}/deliveries/{deliveryId}` · API OnZap, API oficial (Meta)

Inclui o corpo exato enviado (`payload`).

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |
| `deliveryId` | path | string | sim | ID da entrega. |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries/dlv_01jabcdefghjkmnpqrstvwxyz0" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Entrega

```json
{
  "attempts": 1,
  "createdAt": "2026-09-30T14:05:00Z",
  "durationMs": 0,
  "error": "número sem WhatsApp",
  "event": "message.any",
  "eventId": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "id": "dlv_01jabcdefghjkmnpqrstvwxy",
  "nextAttemptAt": "2026-09-30T14:05:00Z",
  "response": "{\"id\":\"false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6\"}",
  "status": "success",
  "statusCode": 0,
  "updatedAt": "2026-09-30T14:05:00Z"
}
```

## Reenviar entrega

`POST /webhooks/{webhookId}/deliveries/{deliveryId}/retry` · API OnZap, API oficial (Meta)

Cria uma nova entrega do mesmo evento (o evento precisa ter menos de 7 dias).

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `webhookId` | path | string | sim | ID do webhook. |
| `deliveryId` | path | string | sim | ID da entrega. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/webhooks/whk_01jabcdefghjkmnpqrstvwxyz0/deliveries/dlv_01jabcdefghjkmnpqrstvwxyz0/retry" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 202** — Reenvio enfileirado

```json
{
  "deliveryId": "dlv_01jabcdefghjkmnpqrstvwxy"
}
```


---

# Eventos de webhook

> Tudo o que pode chegar no seu webhook, com o formato do payload de cada evento.

## Status da conexão

`session.status` · API OnZap, API oficial (Meta)

A conexão mudou de status (ex.: `WORKING` → `SCAN_QR_CODE` quando o celular desconecta).

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | string | sim | `STOPPED`, `STARTING`, `SCAN_QR_CODE`, `WORKING` ou `FAILED`. |
| `raw` | any | não |  |
| `reason` | string | não | Motivo, quando a conexão caiu (ex.: token da Meta revogado). |

**Exemplo**

```json
{
  "event": "session.status",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "reason": "a conta da Meta revogou o acesso",
    "status": "WORKING"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Mensagem recebida

`message` · API OnZap, API oficial (Meta)

Mensagem que chegou de outra pessoa (não inclui as enviadas por este número).

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim | Conversa (contato ou grupo). Usa o número (`...@c.us`) sempre que ele é conhecido, mesmo quando o WhatsApp manda o LID. |
| `from` | object | sim | Quem mandou. |
| `from.id` | string | sim | ID para responder: `5511999999999@c.us` (o número, sempre que conhecido), `…@lid` ou, na API oficial, `BR.…@bsuid`. |
| `from.bsuid` | string | não | API oficial: ID do usuário na Meta (usuários com nome de usuário podem não mostrar o número). |
| `from.lid` | string | não | LID do contato, quando o WhatsApp o endereçou assim (`…@lid`); o `id` já vem com o número. |
| `from.phone` | string | não | Número (só dígitos), quando conhecido. |
| `from.picture` | string | não | Link assinado para a foto de perfil (só na API OnZap). |
| `from.pushName` | string | não | Nome que a pessoa definiu no WhatsApp. |
| `from.username` | string | não | API oficial: nome de usuário do WhatsApp, se houver. |
| `fromMe` | boolean | sim | Enviada por este número. |
| `id` | string | sim | ID da mensagem (use em reply_to, reações, lida). |
| `isGroup` | boolean | sim | A conversa é um grupo. |
| `timestamp` | integer | sim | Segundos desde 1970. |
| `type` | string | sim | `text`, `image`, `video`, `audio`, `voice`, `document`, `sticker`, `location`, `contact`, `button_reply`, `list_reply`, `reaction`, `poll` ou `unknown`. |
| `chatLid` | string | não | LID da conversa, quando o WhatsApp a endereçou assim (`...@lid`). O `chatId` já vem com o número. |
| `chatName` | string | não | Nome da conversa: o assunto do grupo ou o nome do contato (agenda do celular ou perfil). |
| `chatPicture` | string | não | Link temporário para a foto da conversa (do grupo ou do contato). Só na API OnZap; sem foto visível, o link responde 404. |
| `contacts` | array de string | não | vCards, em mensagens de contato. |
| `location` | object | não |  |
| `location.latitude` | number | sim |  |
| `location.longitude` | number | sim |  |
| `location.address` | string | não |  |
| `location.name` | string | não |  |
| `location.url` | string | não |  |
| `media` | object | não |  |
| `media.error` | string | não | Por que o arquivo não pôde ser baixado, se for o caso. |
| `media.filename` | string | não |  |
| `media.mimetype` | string | não |  |
| `media.url` | string | não | Link assinado para baixar o arquivo (válido por 24 h). |
| `quotedId` | string | não | ID da mensagem respondida (citada). |
| `raw` | any | não | Evento original do provedor, para campos que o formato padrão não cobre. |
| `reply` | object | não | Botão ou item de lista escolhido. |
| `reply.id` | string | não |  |
| `reply.title` | string | não |  |
| `source` | string | não | `api` (enviada pela API) ou `app` (pelo celular), nas mensagens próprias. |
| `text` | string | não | Texto (ou legenda da mídia). |

**Exemplo**

```json
{
  "event": "message",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "chatLid": "36576092528787@lid",
    "chatName": "Maria Silva",
    "chatPicture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
    "contacts": [
      "texto"
    ],
    "from": {
      "bsuid": "BR.1349120865530274191",
      "id": "5511999999999@c.us",
      "lid": "36576092528787@lid",
      "phone": "5511999999999",
      "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
      "pushName": "Maria",
      "username": "maria.silva"
    },
    "fromMe": false,
    "id": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "isGroup": false,
    "location": {
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "latitude": -23.5613,
      "longitude": -46.6565,
      "name": "Loja Centro",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "media": {
      "error": "número sem WhatsApp",
      "filename": "pedido.pdf",
      "mimetype": "image/jpeg",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "quotedId": "false_5511999999999@c.us_3EB0A1A2A3A4A5A6A7",
    "reply": {
      "id": "confirmar",
      "title": "Confirmação"
    },
    "source": "api",
    "text": "Olá! Seu pedido foi confirmado.",
    "timestamp": 1767225600,
    "type": "text"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Reação

`message.reaction` · API OnZap, API oficial (Meta)

Alguém reagiu (ou removeu a reação) a uma mensagem.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim |  |
| `emoji` | string | sim | Emoji; vazio quando a reação foi removida. |
| `from` | object | sim |  |
| `from.id` | string | sim | ID para responder: `5511999999999@c.us` (o número, sempre que conhecido), `…@lid` ou, na API oficial, `BR.…@bsuid`. |
| `from.bsuid` | string | não | API oficial: ID do usuário na Meta (usuários com nome de usuário podem não mostrar o número). |
| `from.lid` | string | não | LID do contato, quando o WhatsApp o endereçou assim (`…@lid`); o `id` já vem com o número. |
| `from.phone` | string | não | Número (só dígitos), quando conhecido. |
| `from.picture` | string | não | Link assinado para a foto de perfil (só na API OnZap). |
| `from.pushName` | string | não | Nome que a pessoa definiu no WhatsApp. |
| `from.username` | string | não | API oficial: nome de usuário do WhatsApp, se houver. |
| `fromMe` | boolean | sim |  |
| `id` | string | sim |  |
| `messageId` | string | sim | Mensagem que recebeu a reação. |
| `timestamp` | integer | sim |  |
| `raw` | any | não |  |

**Exemplo**

```json
{
  "event": "message.reaction",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "emoji": "👍",
    "from": {
      "bsuid": "BR.1349120865530274191",
      "id": "5511999999999@c.us",
      "lid": "36576092528787@lid",
      "phone": "5511999999999",
      "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
      "pushName": "Maria",
      "username": "maria.silva"
    },
    "fromMe": false,
    "id": "false_5511999999999@c.us_3EB0AA11BB22CC33DD44",
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Qualquer mensagem

`message.any` · API OnZap, API oficial (Meta)

Recebidas e enviadas, inclusive as enviadas pelo celular ou por outro sistema (`fromMe: true`, `source: app`).

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim | Conversa (contato ou grupo). Usa o número (`...@c.us`) sempre que ele é conhecido, mesmo quando o WhatsApp manda o LID. |
| `from` | object | sim | Quem mandou. |
| `from.id` | string | sim | ID para responder: `5511999999999@c.us` (o número, sempre que conhecido), `…@lid` ou, na API oficial, `BR.…@bsuid`. |
| `from.bsuid` | string | não | API oficial: ID do usuário na Meta (usuários com nome de usuário podem não mostrar o número). |
| `from.lid` | string | não | LID do contato, quando o WhatsApp o endereçou assim (`…@lid`); o `id` já vem com o número. |
| `from.phone` | string | não | Número (só dígitos), quando conhecido. |
| `from.picture` | string | não | Link assinado para a foto de perfil (só na API OnZap). |
| `from.pushName` | string | não | Nome que a pessoa definiu no WhatsApp. |
| `from.username` | string | não | API oficial: nome de usuário do WhatsApp, se houver. |
| `fromMe` | boolean | sim | Enviada por este número. |
| `id` | string | sim | ID da mensagem (use em reply_to, reações, lida). |
| `isGroup` | boolean | sim | A conversa é um grupo. |
| `timestamp` | integer | sim | Segundos desde 1970. |
| `type` | string | sim | `text`, `image`, `video`, `audio`, `voice`, `document`, `sticker`, `location`, `contact`, `button_reply`, `list_reply`, `reaction`, `poll` ou `unknown`. |
| `chatLid` | string | não | LID da conversa, quando o WhatsApp a endereçou assim (`...@lid`). O `chatId` já vem com o número. |
| `chatName` | string | não | Nome da conversa: o assunto do grupo ou o nome do contato (agenda do celular ou perfil). |
| `chatPicture` | string | não | Link temporário para a foto da conversa (do grupo ou do contato). Só na API OnZap; sem foto visível, o link responde 404. |
| `contacts` | array de string | não | vCards, em mensagens de contato. |
| `location` | object | não |  |
| `location.latitude` | number | sim |  |
| `location.longitude` | number | sim |  |
| `location.address` | string | não |  |
| `location.name` | string | não |  |
| `location.url` | string | não |  |
| `media` | object | não |  |
| `media.error` | string | não | Por que o arquivo não pôde ser baixado, se for o caso. |
| `media.filename` | string | não |  |
| `media.mimetype` | string | não |  |
| `media.url` | string | não | Link assinado para baixar o arquivo (válido por 24 h). |
| `quotedId` | string | não | ID da mensagem respondida (citada). |
| `raw` | any | não | Evento original do provedor, para campos que o formato padrão não cobre. |
| `reply` | object | não | Botão ou item de lista escolhido. |
| `reply.id` | string | não |  |
| `reply.title` | string | não |  |
| `source` | string | não | `api` (enviada pela API) ou `app` (pelo celular), nas mensagens próprias. |
| `text` | string | não | Texto (ou legenda da mídia). |

**Exemplo**

```json
{
  "event": "message.any",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "chatLid": "36576092528787@lid",
    "chatName": "Maria Silva",
    "chatPicture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
    "contacts": [
      "texto"
    ],
    "from": {
      "bsuid": "BR.1349120865530274191",
      "id": "5511999999999@c.us",
      "lid": "36576092528787@lid",
      "phone": "5511999999999",
      "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
      "pushName": "Maria",
      "username": "maria.silva"
    },
    "fromMe": false,
    "id": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "isGroup": false,
    "location": {
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "latitude": -23.5613,
      "longitude": -46.6565,
      "name": "Loja Centro",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "media": {
      "error": "número sem WhatsApp",
      "filename": "pedido.pdf",
      "mimetype": "image/jpeg",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "quotedId": "false_5511999999999@c.us_3EB0A1A2A3A4A5A6A7",
    "reply": {
      "id": "confirmar",
      "title": "Confirmação"
    },
    "source": "api",
    "text": "Olá! Seu pedido foi confirmado.",
    "timestamp": 1767225600,
    "type": "text"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Status de entrega e leitura

`message.ack` · API OnZap, API oficial (Meta)

Enviada, entregue, lida, ouvida ou falhou.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim |  |
| `id` | string | sim | ID da mensagem. |
| `status` | string | sim | `pending`, `sent`, `delivered`, `read`, `played` ou `failed`. |
| `error` | object | não | Motivo da falha (status `failed`). |
| `error.message` | string | sim |  |
| `error.code` | integer | não |  |
| `pricing` | any | não | API oficial: categoria e cobrança da conversa. |
| `raw` | any | não |  |
| `timestamp` | integer | não |  |

**Exemplo**

```json
{
  "event": "message.ack",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "error": {
      "code": 0,
      "message": "Olá! Seu pedido foi confirmado."
    },
    "id": "true_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "status": "read",
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Status de leitura em grupos

`message.ack.group` · API OnZap

Leitura e entrega por participante em grupos.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `ack` | number | sim | Valores: `-1`, `0`, `1`, `2`, `3`, `4`. |
| `ackName` | string | sim |  |
| `from` | string | sim |  |
| `fromMe` | boolean | sim |  |
| `id` | string | sim | Message ID |
| `participant` | string | sim |  |
| `to` | string | sim |  |
| `_data` | object | não |  |

**Exemplo**

```json
{
  "event": "message.ack.group",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "ack": -1,
    "ackName": "READ",
    "from": "5511999999999@c.us",
    "fromMe": false,
    "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "participant": "5511999999999@c.us",
    "to": "5511999999999@c.us"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Mensagem aguardando

`message.waiting` · API OnZap

O WhatsApp avisou que há uma mensagem que ainda não pôde ser lida ("Aguardando mensagem").

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Exemplo**

```json
{
  "event": "message.waiting",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {},
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Mensagem apagada

`message.revoked` · API OnZap, API oficial (Meta)

Mensagem apagada para todos.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim |  |
| `fromMe` | boolean | sim |  |
| `messageId` | string | sim | Mensagem apagada para todos. |
| `raw` | any | não |  |
| `timestamp` | integer | não |  |

**Exemplo**

```json
{
  "event": "message.revoked",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "fromMe": false,
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Mensagem editada

`message.edited` · API OnZap, API oficial (Meta)

Texto de uma mensagem foi editado.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim |  |
| `from` | object | sim |  |
| `from.id` | string | sim | ID para responder: `5511999999999@c.us` (o número, sempre que conhecido), `…@lid` ou, na API oficial, `BR.…@bsuid`. |
| `from.bsuid` | string | não | API oficial: ID do usuário na Meta (usuários com nome de usuário podem não mostrar o número). |
| `from.lid` | string | não | LID do contato, quando o WhatsApp o endereçou assim (`…@lid`); o `id` já vem com o número. |
| `from.phone` | string | não | Número (só dígitos), quando conhecido. |
| `from.picture` | string | não | Link assinado para a foto de perfil (só na API OnZap). |
| `from.pushName` | string | não | Nome que a pessoa definiu no WhatsApp. |
| `from.username` | string | não | API oficial: nome de usuário do WhatsApp, se houver. |
| `fromMe` | boolean | sim |  |
| `id` | string | sim |  |
| `messageId` | string | sim | Mensagem original. |
| `text` | string | sim | Novo texto. |
| `timestamp` | integer | sim |  |
| `raw` | any | não |  |

**Exemplo**

```json
{
  "event": "message.edited",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "from": {
      "bsuid": "BR.1349120865530274191",
      "id": "5511999999999@c.us",
      "lid": "36576092528787@lid",
      "phone": "5511999999999",
      "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…",
      "pushName": "Maria",
      "username": "maria.silva"
    },
    "fromMe": false,
    "id": "false_5511999999999@c.us_3EB0EE55FF66AA77BB88",
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "text": "Olá! Seu pedido foi confirmado.",
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Mudança de estado do aparelho

`state.change` · API OnZap

Estado interno da conexão com o celular.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Exemplo**

```json
{
  "event": "state.change",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {},
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Entrou em um grupo (legado)

`group.join` · API OnZap

Formato antigo; prefira `group.v2.join`.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Exemplo**

```json
{
  "event": "group.join",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {},
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Saiu de um grupo (legado)

`group.leave` · API OnZap

Formato antigo; prefira `group.v2.leave`.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Exemplo**

```json
{
  "event": "group.leave",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {},
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Entrou em um grupo

`group.v2.join` · API OnZap

Este número foi adicionado ou entrou em um grupo.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `group` | object | sim |  |
| `group.description` | string | sim |  |
| `group.id` | string | sim |  |
| `group.membersCanAddNewMember` | boolean | sim | Members can add new members |
| `group.membersCanSendMessages` | boolean | sim | Members can send messages to the group |
| `group.newMembersApprovalRequired` | boolean | sim | Admin approval required for new members |
| `group.participants` | array de object | sim |  |
| `group.participants[].id` | string | sim | Member ID in @c.us or @lid format |
| `group.participants[].role` | string | sim | Valores: `left`, `participant`, `admin`, `superadmin`. |
| `group.participants[].pn` | string | não | Member ID in @c.us format |
| `group.subject` | string | sim |  |
| `group.invite` | string | não | Invite URL |
| `timestamp` | number | sim | Unix timestamp |

**Exemplo**

```json
{
  "event": "group.v2.join",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "group": {
      "description": "Group Description",
      "id": "123456789@g.us",
      "invite": "https://chat.whatsapp.com/1234567890abcdef",
      "membersCanAddNewMember": false,
      "membersCanSendMessages": false,
      "newMembersApprovalRequired": false,
      "participants": [
        {
          "id": "123456789@lid",
          "pn": "123456789@c.us",
          "role": "participant"
        }
      ],
      "subject": "Group Name"
    },
    "timestamp": 1666943582
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Saiu de um grupo

`group.v2.leave` · API OnZap

Este número saiu ou foi removido de um grupo.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `group` | object | sim |  |
| `group.id` | string | sim |  |
| `timestamp` | number | sim | Unix timestamp |

**Exemplo**

```json
{
  "event": "group.v2.leave",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "group": {
      "id": "123456789@g.us"
    },
    "timestamp": 1666943582
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Grupo alterado

`group.v2.update` · API OnZap

Nome, descrição, foto ou configurações do grupo mudaram.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `group` | object | sim |  |
| `timestamp` | number | sim | Unix timestamp |

**Exemplo**

```json
{
  "event": "group.v2.update",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "group": {},
    "timestamp": 1666943582
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Participantes alterados

`group.v2.participants` · API OnZap

Participantes entraram, saíram, foram promovidos ou rebaixados.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `group` | object | sim |  |
| `group.id` | string | sim |  |
| `participants` | array de object | sim |  |
| `participants[].id` | string | sim | Member ID in @c.us or @lid format |
| `participants[].role` | string | sim | Valores: `left`, `participant`, `admin`, `superadmin`. |
| `participants[].pn` | string | não | Member ID in @c.us format |
| `timestamp` | number | sim | Unix timestamp |
| `type` | string | sim | Type of the event Valores: `join`, `leave`, `promote`, `demote`. |

**Exemplo**

```json
{
  "event": "group.v2.participants",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "group": {
      "id": "123456789@g.us"
    },
    "participants": [
      {
        "id": "123456789@lid",
        "pn": "123456789@c.us",
        "role": "participant"
      }
    ],
    "timestamp": 1666943582,
    "type": "join"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Presença

`presence.update` · API OnZap

Online, digitando ou gravando áudio, para chats com presença assinada (`POST /presence/{chatId}/subscribe`).

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | string | sim | Chat ID - either group id or contact id |
| `presences` | array de object | sim |  |
| `presences[].lastKnownPresence` | string | sim | Valores: `offline`, `online`, `typing`, `recording`, `paused`. |
| `presences[].participant` | string | sim | Chat ID - participant or contact id |
| `presences[].lastSeen` | number | não |  |

**Exemplo**

```json
{
  "event": "presence.update",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "id": "5511999999999@c.us",
    "presences": [
      {
        "lastKnownPresence": "offline",
        "lastSeen": 1686568773,
        "participant": "5511999999999@c.us"
      }
    ]
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Voto em enquete

`poll.vote` · API OnZap

Alguém votou numa enquete enviada por este número.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `poll` | object | sim |  |
| `poll.from` | string | sim |  |
| `poll.fromMe` | boolean | sim |  |
| `poll.id` | string | sim | Message ID |
| `poll.to` | string | sim |  |
| `poll.participant` | string | não |  |
| `vote` | object | sim |  |
| `vote.from` | string | sim |  |
| `vote.fromMe` | boolean | sim |  |
| `vote.id` | string | sim | Message ID |
| `vote.selectedOptions` | array de string | sim | Option that user has selected |
| `vote.timestamp` | number | sim | Timestamp, ms |
| `vote.to` | string | sim |  |
| `vote.participant` | string | não |  |
| `_data` | object | não |  |

**Exemplo**

```json
{
  "event": "poll.vote",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "poll": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "to": "5511888888888@c.us"
    },
    "vote": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "selectedOptions": [
        "Awesome!"
      ],
      "timestamp": 1692861369,
      "to": "5511888888888@c.us"
    }
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Voto não decifrado

`poll.vote.failed` · API OnZap

Chegou um voto que não pôde ser decifrado.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `poll` | object | sim |  |
| `poll.from` | string | sim |  |
| `poll.fromMe` | boolean | sim |  |
| `poll.id` | string | sim | Message ID |
| `poll.to` | string | sim |  |
| `poll.participant` | string | não |  |
| `vote` | object | sim |  |
| `vote.from` | string | sim |  |
| `vote.fromMe` | boolean | sim |  |
| `vote.id` | string | sim | Message ID |
| `vote.selectedOptions` | array de string | sim | Option that user has selected |
| `vote.timestamp` | number | sim | Timestamp, ms |
| `vote.to` | string | sim |  |
| `vote.participant` | string | não |  |
| `_data` | object | não |  |

**Exemplo**

```json
{
  "event": "poll.vote.failed",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "poll": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "to": "5511888888888@c.us"
    },
    "vote": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "selectedOptions": [
        "Awesome!"
      ],
      "timestamp": 1692861369,
      "to": "5511888888888@c.us"
    }
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Conversa arquivada

`chat.archive` · API OnZap

Uma conversa foi arquivada ou desarquivada.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `archived` | boolean | sim |  |
| `id` | string | sim |  |
| `timestamp` | number | sim |  |

**Exemplo**

```json
{
  "event": "chat.archive",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "archived": false,
    "id": "5511999999999@c.us",
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Chamada recebida

`call.received` · API OnZap

Chamada de voz ou vídeo chegando (dá para recusar com `POST /calls/reject`).

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `id` | string | sim | Call ID |
| `isGroup` | boolean | sim |  |
| `isVideo` | boolean | sim |  |
| `timestamp` | number | sim |  |
| `from` | string | não |  |

**Exemplo**

```json
{
  "event": "call.received",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "from": "5511999999999@c.us",
    "id": "ABCDEFGABCDEFGABCDEFGABCDEFG",
    "isGroup": false,
    "isVideo": false,
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Chamada atendida

`call.accepted` · API OnZap

A chamada foi atendida em outro aparelho.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `id` | string | sim | Call ID |
| `isGroup` | boolean | sim |  |
| `isVideo` | boolean | sim |  |
| `timestamp` | number | sim |  |
| `from` | string | não |  |

**Exemplo**

```json
{
  "event": "call.accepted",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "from": "5511999999999@c.us",
    "id": "ABCDEFGABCDEFGABCDEFGABCDEFG",
    "isGroup": false,
    "isVideo": false,
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Chamada recusada

`call.rejected` · API OnZap

A chamada foi recusada.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `_data` | object | sim |  |
| `id` | string | sim | Call ID |
| `isGroup` | boolean | sim |  |
| `isVideo` | boolean | sim |  |
| `timestamp` | number | sim |  |
| `from` | string | não |  |

**Exemplo**

```json
{
  "event": "call.rejected",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "from": "5511999999999@c.us",
    "id": "ABCDEFGABCDEFGABCDEFGABCDEFG",
    "isGroup": false,
    "isVideo": false,
    "timestamp": 1767225600
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Etiqueta criada ou alterada

`label.upsert` · API OnZap

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `color` | number | sim | Color number, not hex |
| `colorHex` | string | sim | Color in hex |
| `id` | string | sim | Label ID |
| `name` | string | sim | Label name |

**Exemplo**

```json
{
  "event": "label.upsert",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "color": 0,
    "colorHex": "#ff9485",
    "id": "1",
    "name": "Lead"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Etiqueta removida

`label.deleted` · API OnZap

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `color` | number | sim | Color number, not hex |
| `colorHex` | string | sim | Color in hex |
| `id` | string | sim | Label ID |
| `name` | string | sim | Label name |

**Exemplo**

```json
{
  "event": "label.deleted",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "color": 0,
    "colorHex": "#ff9485",
    "id": "1",
    "name": "Lead"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Etiqueta aplicada

`label.chat.added` · API OnZap

Uma etiqueta foi aplicada a uma conversa.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim | Chat ID |
| `label` | object | sim |  |
| `label.color` | number | sim | Color number, not hex |
| `label.colorHex` | string | sim | Color in hex |
| `label.id` | string | sim | Label ID |
| `label.name` | string | sim | Label name |
| `labelId` | string | sim | Label ID |

**Exemplo**

```json
{
  "event": "label.chat.added",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "label": {
      "color": 0,
      "colorHex": "#ff9485",
      "id": "1",
      "name": "Lead"
    },
    "labelId": "1"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Etiqueta retirada

`label.chat.deleted` · API OnZap

Uma etiqueta foi retirada de uma conversa.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `chatId` | string | sim | Chat ID |
| `label` | object | sim |  |
| `label.color` | number | sim | Color number, not hex |
| `label.colorHex` | string | sim | Color in hex |
| `label.id` | string | sim | Label ID |
| `label.name` | string | sim | Label name |
| `labelId` | string | sim | Label ID |

**Exemplo**

```json
{
  "event": "label.chat.deleted",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "chatId": "5511999999999@c.us",
    "label": {
      "color": 0,
      "colorHex": "#ff9485",
      "id": "1",
      "name": "Lead"
    },
    "labelId": "1"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Resposta a evento

`event.response` · API OnZap

Alguém respondeu a um evento (agenda).

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `eventCreationKey` | object | sim |  |
| `eventCreationKey.from` | string | sim |  |
| `eventCreationKey.fromMe` | boolean | sim |  |
| `eventCreationKey.id` | string | sim | Message ID |
| `eventCreationKey.to` | string | sim |  |
| `eventCreationKey.participant` | string | não |  |
| `from` | string | sim | ID for the Chat that this message was sent to, except if the message was sent by the current user |
| `fromMe` | boolean | sim | Indicates if the message was sent by the current user |
| `id` | string | sim | Message ID |
| `participant` | string | sim | For groups - participant who sent the message |
| `source` | string | sim | The device that sent the message - either API or APP. Available in events (webhooks/websockets) only and only "fromMe: true" messages. Valores: `api`, `app`. |
| `timestamp` | number | sim | Unix timestamp for when the message was created |
| `to` | string | sim | * ID for who this message is for. * If the message is sent by the current user, it will be the Chat to which the message is being sent. * If the message is sent by another user, it will be the ID for the current user. |
| `_data` | object | não | Message in a raw format that we get from WhatsApp. May be changed anytime, use it with caution! It depends a lot on the underlying backend. |
| `eventResponse` | object | não |  |
| `eventResponse.extraGuestCount` | number | sim |  |
| `eventResponse.response` | string | sim | Valores: `UNKNOWN`, `GOING`, `NOT_GOING`, `MAYBE`. |
| `eventResponse.timestampMs` | number | sim |  |

**Exemplo**

```json
{
  "event": "event.response",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "eventCreationKey": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "to": "5511888888888@c.us"
    },
    "eventResponse": {
      "extraGuestCount": 0,
      "response": "UNKNOWN",
      "timestampMs": 0
    },
    "from": "5511999999999@c.us",
    "fromMe": false,
    "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "participant": "5521988887777@c.us",
    "source": "api",
    "timestamp": 1666943582,
    "to": "5511999999999@c.us"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Resposta a evento não decifrada

`event.response.failed` · API OnZap

Chegou uma resposta que não pôde ser decifrada.

Só na API OnZap. O `payload` segue o formato do WhatsApp Web.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `eventCreationKey` | object | sim |  |
| `eventCreationKey.from` | string | sim |  |
| `eventCreationKey.fromMe` | boolean | sim |  |
| `eventCreationKey.id` | string | sim | Message ID |
| `eventCreationKey.to` | string | sim |  |
| `eventCreationKey.participant` | string | não |  |
| `from` | string | sim | ID for the Chat that this message was sent to, except if the message was sent by the current user |
| `fromMe` | boolean | sim | Indicates if the message was sent by the current user |
| `id` | string | sim | Message ID |
| `participant` | string | sim | For groups - participant who sent the message |
| `source` | string | sim | The device that sent the message - either API or APP. Available in events (webhooks/websockets) only and only "fromMe: true" messages. Valores: `api`, `app`. |
| `timestamp` | number | sim | Unix timestamp for when the message was created |
| `to` | string | sim | * ID for who this message is for. * If the message is sent by the current user, it will be the Chat to which the message is being sent. * If the message is sent by another user, it will be the ID for the current user. |
| `_data` | object | não | Message in a raw format that we get from WhatsApp. May be changed anytime, use it with caution! It depends a lot on the underlying backend. |
| `eventResponse` | object | não |  |
| `eventResponse.extraGuestCount` | number | sim |  |
| `eventResponse.response` | string | sim | Valores: `UNKNOWN`, `GOING`, `NOT_GOING`, `MAYBE`. |
| `eventResponse.timestampMs` | number | sim |  |

**Exemplo**

```json
{
  "event": "event.response.failed",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "_data": {},
    "eventCreationKey": {
      "from": "5511999999999@c.us",
      "fromMe": false,
      "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
      "participant": "5521988887777@c.us",
      "to": "5511888888888@c.us"
    },
    "eventResponse": {
      "extraGuestCount": 0,
      "response": "UNKNOWN",
      "timestampMs": 0
    },
    "from": "5511999999999@c.us",
    "fromMe": false,
    "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "participant": "5521988887777@c.us",
    "source": "api",
    "timestamp": 1666943582,
    "to": "5511999999999@c.us"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Envio da fila concluído

`queue.sent` · API OnZap, API oficial (Meta)

Uma mensagem da fila foi enviada.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `attempts` | integer | sim |  |
| `id` | string | sim | ID do envio na fila. |
| `route` | string | sim | Rota do envio, ex.: `POST /messages/text`. |
| `status` | string | sim | Valores: `sent`, `failed`, `cancelled`, `expired`. |
| `chatId` | string | não |  |
| `error` | string | não | Motivo da falha. |
| `messageId` | string | não | ID da mensagem no WhatsApp (quando enviada). |

**Exemplo**

```json
{
  "event": "queue.sent",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "attempts": 1,
    "chatId": "5511999999999@c.us",
    "error": "número sem WhatsApp",
    "id": "3EB0C0A1B2C3D4E5F6",
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "route": "POST /messages/text",
    "status": "sent"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Envio da fila não concluído

`queue.failed` · API OnZap, API oficial (Meta)

Uma mensagem da fila falhou, expirou esperando a reconexão ou foi cancelada.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `attempts` | integer | sim |  |
| `id` | string | sim | ID do envio na fila. |
| `route` | string | sim | Rota do envio, ex.: `POST /messages/text`. |
| `status` | string | sim | Valores: `sent`, `failed`, `cancelled`, `expired`. |
| `chatId` | string | não |  |
| `error` | string | não | Motivo da falha. |
| `messageId` | string | não | ID da mensagem no WhatsApp (quando enviada). |

**Exemplo**

```json
{
  "event": "queue.failed",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "attempts": 1,
    "chatId": "5511999999999@c.us",
    "error": "número sem WhatsApp",
    "id": "3EB0C0A1B2C3D4E5F6",
    "messageId": "false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6",
    "route": "POST /messages/text",
    "status": "sent"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```

## Status de template

`template.status` · API oficial (Meta)

Um template foi aprovado, rejeitado, pausado ou desativado pela Meta.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | sim |  |
| `status` | string | sim | APPROVED, REJECTED, PAUSED, DISABLED… |
| `templateId` | string | sim |  |
| `language` | string | não |  |
| `raw` | object | não | Evento original da Meta. |
| `reason` | string | não | Motivo da rejeição, se houver. |

**Exemplo**

```json
{
  "event": "template.status",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "language": "pt_BR",
    "name": "Maria Silva",
    "raw": {},
    "reason": "falhas seguidas",
    "status": "ok",
    "templateId": "1234567890123456"
  },
  "provider": "meta",
  "timestamp": 1767225600000
}
```

## Qualidade do número

`phone.quality` · API oficial (Meta)

A qualidade ou o limite de conversas do número mudou.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `event` | string | sim | FLAGGED, UNFLAGGED, UPGRADE, DOWNGRADE… |
| `currentLimit` | string | não | Limite atual de conversas iniciadas pela empresa. |
| `phone` | string | não | Número (como a Meta exibe). |
| `raw` | object | não | Evento original da Meta. |

**Exemplo**

```json
{
  "event": "phone.quality",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "currentLimit": "TIER_1K",
    "event": "message.any",
    "phone": "5511999999999",
    "raw": {}
  },
  "provider": "meta",
  "timestamp": 1767225600000
}
```

## Evento de teste

`webhook.test` · API OnZap, API oficial (Meta)

Enviado por `POST /webhooks/{webhookId}/test`.

**Campos do payload**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `message` | string | sim |  |
| `webhookId` | string | sim |  |

**Exemplo**

```json
{
  "event": "webhook.test",
  "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
  "instanceId": "i01jabcdefghjkmnpqrstvwxyz",
  "payload": {
    "message": "Olá! Seu pedido foi confirmado.",
    "webhookId": "whk_01jabcdefghjkmnpqrstvwxy"
  },
  "provider": "onzap",
  "timestamp": 1767225600000
}
```


---

# Eventos

> Eventos dos últimos 7 dias, no mesmo formato entregue aos webhooks.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Eventos recentes

`GET /events` · API OnZap, API oficial (Meta)

Eventos dos últimos 7 dias que foram entregues (ou seriam) aos webhooks, do mais novo para o mais antigo.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `type` | query | string | não | Só um tipo de evento (ex.: `message`). |
| `limit` | query | integer | não | Quantidade (padrão 50, máximo 100). |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/events" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Eventos

```json
{
  "data": [
    {
      "event": "message.any",
      "id": "evt_01jabcdefghjkmnpqrstvwxyz0",
      "timestamp": "2026-09-30T14:05:00Z"
    }
  ]
}
```


---

# Templates

> Modelos de mensagem aprovados pela Meta (obrigatórios fora da janela de 24 h).

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Listar templates

`GET /templates` · API oficial (Meta)

Templates da conta do WhatsApp Business, com status de aprovação. Paginação da Meta (`paging.cursors`).

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `status` | query | string | não | APPROVED, PENDING, REJECTED, PAUSED… |
| `name` | query | string | não | Filtra pelo nome (contém). |
| `category` | query | string | não | MARKETING, UTILITY ou AUTHENTICATION. |
| `language` | query | string | não | Ex.: `pt_BR`. |
| `limit` | query | integer | não | Quantidade por página. |
| `after` | query | string | não | Cursor da próxima página. |
| `before` | query | string | não | Cursor da página anterior. |

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/templates" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Templates

```json
{
  "data": [
    {
      "category": "UTILITY",
      "components": [
        {}
      ],
      "id": "1234567890123456",
      "language": "pt_BR",
      "name": "pedido_enviado",
      "parameter_format": "POSITIONAL",
      "quality_score": {},
      "rejected_reason": "NONE",
      "status": "APPROVED"
    }
  ],
  "paging": {}
}
```

## Criar template

`POST /templates` · API oficial (Meta)

Envia o template para aprovação da Meta (formato da [Cloud API](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)). O resultado da análise chega no evento `template.status`.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `category` | string | sim | Valores: `MARKETING`, `UTILITY`, `AUTHENTICATION`. |
| `components` | array de object | sim |  |
| `language` | string | sim | Ex.: `pt_BR`. |
| `name` | string | sim | Letras minúsculas, números e _. |
| `parameter_format` | string | não | Valores: `POSITIONAL`, `NAMED`. |

**Exemplo**

```bash
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/templates" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "UTILITY",
    "components": [
      {
        "example": {
          "body_text": [
            [
              "Maria",
              "#1234"
            ]
          ]
        },
        "text": "Olá {{1}}, seu pedido {{2}} foi enviado!",
        "type": "BODY"
      }
    ],
    "language": "pt_BR",
    "name": "pedido_enviado"
  }'
```

**Resposta 201** — Enviado para análise

```json
{
  "category": "UTILITY",
  "id": "3EB0C0A1B2C3D4E5F6",
  "status": "ok"
}
```

## Excluir template

`DELETE /templates/{name}` · API oficial (Meta)

Sem `id`, exclui todas as traduções com esse nome.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
| `name` | path | string | sim | Nome do template (letras minúsculas, números e _). |
| `id` | query | string | não | Exclui só a tradução com este ID. |

**Exemplo**

```bash
curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/templates/NAME" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```


---

# Perfil comercial

> Descrição, endereço, site e foto do perfil comercial.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Perfil comercial

`GET /business-profile` · API oficial (Meta)

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/business-profile" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Perfil

```json
{
  "data": [
    {
      "about": "Disponível",
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "email": "maria@exemplo.com.br",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/foto.jpg",
      "vertical": "RETAIL",
      "websites": [
        "texto"
      ]
    }
  ]
}
```

## Alterar perfil comercial

`PATCH /business-profile` · API oficial (Meta)

Só os campos enviados mudam.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `about` | string | não | Recado. |
| `address` | string | não |  |
| `description` | string | não |  |
| `email` | string | não |  |
| `vertical` | string | não | Ramo (ex.: RETAIL, HEALTH, EDU). |
| `websites` | array de string | não |  |

**Exemplo**

```bash
curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/business-profile" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Resposta 200** — Perfil atualizado

```json
{
  "data": [
    {
      "about": "Disponível",
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "email": "maria@exemplo.com.br",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/foto.jpg",
      "vertical": "RETAIL",
      "websites": [
        "texto"
      ]
    }
  ]
}
```

## Alterar foto do perfil comercial

`PUT /business-profile/picture` · API oficial (Meta)

JPG ou PNG em base64 (quadrada, mínimo 192×192).

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `file` | object | sim |  |
| `file.data` | string | sim | Imagem em base64 (pode ter o prefixo data:). |
| `file.mimetype` | string | não | Valores: `image/jpeg`, `image/png`. |

**Exemplo**

```bash
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/business-profile/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    }
  }'
```

**Resposta 200** — Perfil atualizado

```json
{
  "data": [
    {
      "about": "Disponível",
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "email": "maria@exemplo.com.br",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61.24694-24/foto.jpg",
      "vertical": "RETAIL",
      "websites": [
        "texto"
      ]
    }
  ]
}
```


---

# Número

> Dados do número na Meta: qualidade, limite de envio e status.

Rotas relativas a `https://app.onzap.io/v1/instances/{instanceId}`, com o header `X-Instance-Token`.

## Dados do número na Meta

`GET /phone-number` · API oficial (Meta)

Consulta a Meta na hora: qualidade, limite de conversas, status do nome e do número.

**Exemplo**

```bash
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/phone-number" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
```

**Resposta 200** — Número

```json
{
  "coexistence": false,
  "createdAt": "2026-09-30T14:05:00Z",
  "displayPhone": "+55 11 4002-8922",
  "messagingLimit": "TIER_1K",
  "mode": "direct",
  "nameStatus": "APPROVED",
  "phoneNumberId": "106540352242922",
  "phoneStatus": "CONNECTED",
  "qualityRating": "GREEN",
  "syncedAt": "2026-09-30T14:05:00Z",
  "updatedAt": "2026-09-30T14:05:00Z",
  "verifiedName": "Minha Loja",
  "verifyToken": "3c59dc048e8850243be8079a5c74d079",
  "wabaId": "102290129340398",
  "webhookUrl": "https://exemplo.com.br/webhooks/onzap"
}
```