# PEPINO ZAP — Documentação completa
Este arquivo reúne TODA a documentação do PEPINO ZAP em um único Markdown: os guias e a especificação OpenAPI 3.1 completa da API. É autocontido — você (ou uma IA) pode lê-lo inteiro e construir uma integração sem precisar de mais nada.
Autenticação: toda requisição usa uma API key escopada a um Projeto, no header `Authorization: Bearer pzk_live_...` (produção) ou `pzk_test_...` (teste). O modo é definido pelo host + prefixo da key (têm que casar): base URL de produção `https://api.pepinozap.com.br` (pzk_live_); modo teste `https://sandbox.pepinozap.com.br` (pzk_test_, grátis, teto 100 msgs/dia).
## O que a plataforma faz (resumo)
O PEPINO ZAP NÃO é só um transporte de envio — ele é o *system of record* das suas conversas e expõe o CRM. Com a MESMA API key (escopada ao Projeto) você tem:
- **Enviar**: texto, mídia (por URL ou upload), localização, contato, sticker, enquete, reação — `POST /v1/instances/{id}/messages*`.
- **Conectar / instâncias**: criar, listar, remover números; QR Code; status — `/v1/instances*`.
- **Receber (ao vivo)**: eventos `message.received` / `message.status` / `instance.status` por webhook (`/v1/webhooks`) ou WebSocket (`/v1/ws`).
- **Ler o histórico (system of record)**: conversas e mensagens persistidas, com a mídia hospedada por nós — `GET /v1/inbox/conversations` e `GET /v1/inbox/conversations/{id}/messages` (paginação por cursor `?before=`). Você NÃO precisa manter banco de dados nem storage de mídia próprios.
- **CRM / gestão do atendimento**: etiquetas (`/v1/inbox/labels`), atribuição e status (`/v1/inbox/conversations/{id}/assign` e `/status`), motivos de fechamento (`/v1/inbox/close-reasons`), funil de vendas (`/v1/funnels`) e relatórios (`/v1/inbox/reports/summary`).
Os endpoints de leitura (Inbox) e de CRM aceitam a mesma `pzk_` key — não são exclusivos do painel. O contrato completo de cada um está na seção OpenAPI ao final deste arquivo (procure os paths `/v1/inbox/*` e as tags Inbox, Etiquetas, Justificativas, Funil, Relatorios).
# Introdução (/docs)
O PEPINO ZAP é uma **API REST** que permite conectar números de WhatsApp ao seu sistema e enviar e receber mensagens de forma programática. Você cria **instâncias**, pareia cada uma a um aparelho via **QR Code** e, a partir daí, envia mensagens de texto e mídia por requisições HTTP e recebe os eventos de entrada e de status por **webhook** ou **WebSocket**. Além do transporte, a plataforma é o **system of record** das suas conversas — ela **guarda o histórico** (mensagens + mídia hospedada; você lê pela API, sem banco próprio) e expõe uma camada de **Inbox/CRM** (etiquetas, atribuição a atendentes, funil, relatórios) pela mesma key.
Esta página é o seu mapa mental antes de ir para os guias: o que a API faz, como os recursos se organizam (Organização → Projeto → Instância), a diferença entre os modos **teste** e **produção**, como autenticar e quais pré-requisitos liberam o uso real. Se você é novo por aqui, leia até o fim — cada conceito é retomado nos guias com exemplos prontos para copiar.
**Integrando com auxílio de IA?** Baixe toda a documentação — guias e a especificação OpenAPI
completa — em um [único arquivo Markdown](/llms-full.md). É autocontido: cole o conteúdo em uma IA
e ela tem tudo o que precisa para montar a integração, sem você copiar página por página.
## O que você consegue fazer [#o-que-você-consegue-fazer]
Com uma única API key você cobre todo o ciclo de uma conversa de WhatsApp — do envio à gestão do atendimento:
1. **Conectar um número** — crie uma instância e pareie-a com um aparelho lendo um QR Code (como o "Aparelhos conectados" do WhatsApp).
2. **Enviar mensagens** — texto, mídia (imagem, vídeo, áudio, documento), localização, contato, sticker, reação e enquete, por chamadas HTTP.
3. **Receber mensagens e status** — mensagens de entrada e confirmações de entrega/leitura chegam por **webhook** (entrega garantida, com retry) ou **WebSocket** (tempo real, sem endpoint público).
4. **Ler o histórico** — conversas, mensagens e mídia ficam persistidas na nossa infraestrutura; você **lista e pagina pela API** (`GET /v1/inbox/conversations` e `.../conversations/{id}/messages`, com cursor) quando precisar — sem manter banco próprio.
5. **Gerir o atendimento (CRM)** — além do transporte, a plataforma expõe um **Inbox** completo pela mesma key: **etiquetas**, **atribuição** a atendentes, **status** e **motivos de encerramento**, **funil de vendas** e **relatórios** de gestão.
Como a plataforma é o *system of record* das suas conversas, **você não precisa manter banco de dados nem storage de mídia próprios** só para o WhatsApp — ler do histórico pela API é suficiente para a maioria das integrações. Os metadados de atendimento (etiquetas, atribuição, funil) também vivem aqui. Detalhes em [Persistência e histórico](/docs/get-started/persistencia) e na [Referência da API](/docs/api) (seções **Inbox** e **Gestão**).
## Modelo de recursos [#modelo-de-recursos]
Os recursos seguem uma hierarquia de três níveis. Para integrar, na prática você trabalha sempre no nível do **Projeto** — é a ele que sua API key está amarrada.
| Recurso | O que é | Escopo |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Organização** | A conta da sua empresa na plataforma. É o nível em que vive o cadastro e a cobrança. | Contém um ou mais Projetos. |
| **Projeto** | A unidade de **isolamento** da integração. Agrupa suas instâncias, seus webhooks, suas conversas e a assinatura/créditos. | Contém uma ou mais Instâncias. |
| **Instância** | Um **número de WhatsApp** conectado, pareado a um aparelho via QR Code. | Pertence a um único Projeto. |
A **API key é escopada a um único Projeto**: toda instância, mensagem ou webhook que você cria, lista ou remove com a key pertence ao Projeto dela. A Organização é o container de conta/cobrança acima dos Projetos — ela existe, mas **não aparece nas respostas da API** (os objetos retornam `projectId`, não a organização); você não precisa manipulá-la para integrar.
Quer **isolar ambientes ou clientes** (ex.: um Projeto por cliente final, ou um Projeto para
staging)? Crie Projetos separados e use a key de cada um. Como o Projeto é a fronteira de
isolamento, dados de um nunca vazam para o outro.
A geração de keys é **self-service**: você se cadastra, confirma o e-mail e gera a key no painel. A key crua é exibida **uma única vez** no momento da criação — guarde-a em local seguro, pois não há como recuperá-la depois (se perder, revogue e gere outra). O passo a passo está em [Autenticação](/docs/get-started/authentication).
### Glossário rápido [#glossário-rápido]
Termos que aparecem em toda a documentação:
| Termo | Significado |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Instância** | Um número de WhatsApp conectado dentro do seu Projeto. Você envia mensagens "por uma instância". |
| **`status` da instância** | Em que ponto da conexão a instância está: `DISCONNECTED`, `CONNECTING`, `QR_PENDING`, `CONNECTED`, `BANNED`, `ERROR`. Só envie em `CONNECTED`. |
| **QR Code** | A imagem que você renderiza para o usuário escanear no app do WhatsApp (Aparelhos conectados) e parear o número. |
| **JID** | O identificador interno do WhatsApp para um destino, no formato `5511999999999@s.whatsapp.net`. O campo `to` aceita ele ou só os dígitos (E.164). |
| **Webhook / WebSocket** | Os dois caminhos para **receber** eventos (mensagens de entrada e status). Webhook chama o seu endpoint; WebSocket é uma conexão que você abre. |
| **Créditos da API** | Saldo pré-pago consumido a cada mensagem enviada **pela API** (envios pelo painel não consomem). |
## Modos: teste e produção [#modos-teste-e-produção]
Uma **única conta**, com dois **modos** — igual ao test/live do Stripe. O modo é determinado pela **base URL (host)** da API: hosts que começam com `sandbox.` operam em **teste**; `api.` opera em **produção**. Os dados são **totalmente isolados** entre os modos — instâncias, conversas e webhooks de teste nunca aparecem em produção, e vice-versa.
| Modo | Base URL | Prefixo da API key | Cobrança |
| ------------ | ---------------------------------- | ------------------ | ----------------------- |
| **Teste** | `https://sandbox.pepinozap.com.br` | `pzk_test_` | Grátis, com teto diário |
| **Produção** | `https://api.pepinozap.com.br` | `pzk_live_` | Exige plano ativo |
**É o host que decide o modo, não a key** — mas a key tem que **casar com o host**. Uma key de produção (`pzk_live_`) usada no host de teste (`sandbox.*`), ou o contrário, é rejeitada com `401`. Use sempre a key do mesmo modo da base URL.
```bash
# pzk_live_ no host de teste → 401 (key do modo errado)
curl https://sandbox.pepinozap.com.br/v1/instances \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"
```
```json
{
"error": {
"code": "UNAUTHORIZED",
"message": "chave de API inválida para este ambiente/modo"
}
}
```
**Use o modo Teste para construir.** Em teste, criar instâncias e enviar mensagens **não exige
plano** — você valida a integração inteira de graça. Para evitar que o teste vire "produção de
graça", há um **teto de 100 mensagens/dia por Projeto** (enviadas + recebidas; acima disso,
`429`). Quando estiver pronto para volume real, troque a base URL para `api.*` e a key para
`pzk_live_`, e assine um plano. Veja [Modos: teste e
produção](/docs/get-started/authentication#modos-teste-e-producao).
## Autenticação em uma frase [#autenticação-em-uma-frase]
Envie a API key no header `Authorization` com o esquema `Bearer` em **todas** as chamadas REST:
```bash
curl https://api.pepinozap.com.br/v1/instances \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"
```
As **únicas exceções** são os transportes que o navegador abre sem poder definir headers — o **stream SSE de QR Code** (`GET /v1/instances/{id}/qr`) e o **WebSocket de eventos** (`/v1/ws`). Nesses dois casos, a key vai na query string como `?token=`. Em qualquer outro endpoint, use sempre o header `Authorization`. O detalhamento (inclusive o token efêmero de 2 minutos para não expor a key na URL do SSE) está em [Autenticação](/docs/get-started/authentication).
## Pré-requisitos para operar (402 e 429) [#pré-requisitos-para-operar-402-e-429]
Ter uma API key válida **não basta** para enviar de verdade. As ações de **uso real** — conectar um número e enviar mensagens — passam por gates de negócio; as ações de **leitura** e o **pareamento por QR Code** ficam sempre liberadas.
| Ação | Pré-requisito |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Criar instância (`POST /v1/instances`) | Plano ativo (em produção) |
| Enviar mensagem (texto, mídia, localização, contato, sticker, reação, enquete) | Plano ativo (em produção); em projetos modo API, também consome 1 crédito por envio |
| Listar / detalhar instância, parear via QR, marcar como lida | Nenhum — sempre liberado |
* **`402` `PAYMENT_REQUIRED`** — em **produção**, o Projeto não tem **assinatura ativa**, ou um Projeto no modo API ficou **sem créditos**. Distinga os dois casos pela `message`. Resolução: assinar ou recarregar em **Meu plano**, no painel. Em **teste**, esses gates são liberados (não ocorre `402`).
* **`429` `RATE_LIMITED`** — **apenas em teste**: o teto de 100 mensagens/dia por Projeto foi atingido. Em produção não ocorre.
`402` é um **gate de negócio**, não um erro transitório — **não repita a chamada** em loop. A ação
só volta a funcionar após assinar ou recarregar; o seu código não muda. Detalhes e exemplos de
payload em [Plano ativo (erro 402)](/docs/get-started/authentication#plano-ativo-erro-402).
## Como começar [#como-começar]
Siga os guias nesta ordem — eles formam o caminho mínimo de ponta a ponta:
1. **[Quick start](/docs/get-started/quick-start)** — o fluxo completo num só lugar: obter a key, criar uma instância, parear via QR Code e enviar a primeira mensagem.
2. **[Autenticação](/docs/get-started/authentication)** — gerar e usar a API key no header `Authorization: Bearer`, os modos teste/produção e o fallback `?token=`.
3. **[Sua primeira instância](/docs/get-started/first-instance)** — o ciclo de status de `DISCONNECTED` até `CONNECTED`, o pareamento por QR (polling, recomendado, e SSE) e as configurações da instância.
**Envie só quando a instância estiver `CONNECTED`.** Enviar para uma instância
ainda não conectada **também retorna `202`** (`{ "queued": true }`), mas a
mensagem **não sai** e **não há evento de falha**. Antes de enviar, confirme
`GET /v1/instances/{id}` (`status === "CONNECTED"`) ou o `qr/poll`
(`connected === true`).
## Referência rápida de erros [#referência-rápida-de-erros]
Toda resposta de erro segue o mesmo envelope. Use o campo `code` (estável) no seu tratamento de erros, não a `message` (apenas legível).
```json
{
"error": {
"code": "BAD_REQUEST",
"message": "Body inválido"
}
}
```
| Status | `code` | Quando ocorre |
| ------ | ------------------ | ----------------------------------------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Corpo inválido ou campo obrigatório faltando. |
| `401` | `UNAUTHORIZED` | Key ausente, inválida, revogada, expirada **ou** do modo errado para o host. |
| `402` | `PAYMENT_REQUIRED` | Sem plano ativo **ou** sem créditos da API (só em produção). |
| `403` | `FORBIDDEN` | Projeto inativo ou sem permissão. |
| `404` | `NOT_FOUND` | Recurso não encontrado no Projeto/modo da key. |
| `409` | `CONFLICT` | Ao criar instância: cota de números do plano atingida. Ao enviar: instância `BANNED`/`ERROR`. |
| `429` | `RATE_LIMITED` | **Apenas em teste:** teto diário do Projeto atingido (100 mensagens/dia, enviadas + recebidas). |
## Próximos passos [#próximos-passos]
* **[Referência da API](/docs/api)** — endpoints de instâncias e mensagens (texto, mídia, localização, contato, sticker, reação, enquete), configurações da instância, payloads de requisição e resposta, e erros esperados.
* **[Inbox e Gestão (CRM)](/docs/api)** — ler conversas e mensagens persistidas (system of record) com mídia hospedada, e gerir o atendimento: etiquetas, atribuição, status/motivos, funil e relatórios — tudo pela mesma key.
* **[Persistência e histórico](/docs/get-started/persistencia)** — como a plataforma guarda suas conversas e como ler o histórico pelo Inbox sem manter banco próprio.
* **[Webhooks](/docs/webhooks)** — os dez eventos (mensagem, instância, chamada, grupo, contato e etiqueta), envelope de entrega e verificação de assinatura.
* **[WebSocket](/docs/webhooks/websocket)** — os mesmos eventos em tempo real por conexão persistente, sem endpoint público.
# Visão geral (/docs/api)
Esta é a referência da API REST do PEPINO ZAP. Com ela o seu sistema conecta números de WhatsApp (instâncias) e envia mensagens de forma programática. Cada endpoint da referência traz exemplos de requisição em várias linguagens e um playground "Try it" para testar a chamada direto na página.
Esta página de visão geral reúne as **convenções comuns a toda a API** — as regras que valem para qualquer endpoint: como autenticar, em que ambiente você está (teste ou produção), como escrever o destinatário, como o sucesso e o erro são representados e por que o envio é assíncrono. Leia-a uma vez antes de mergulhar nos endpoints; ela evita a maioria dos tropeços de integração.
Se você ainda não gerou uma API key nem conectou um número, comece pelos
guias passo a passo: [Autenticação](/docs/get-started/authentication) (criar a
conta e gerar a key) e [Sua primeira instância](/docs/get-started/first-instance)
(conectar um número via QR Code). Esta página é a referência das convenções;
aqueles guias são o caminho guiado.
## Antes de começar: os três pré-requisitos [#antes-de-começar-os-três-pré-requisitos]
Para uma chamada de uso real (criar instância ou enviar mensagem) ser aceita, três coisas precisam estar certas ao mesmo tempo:
1. **API key válida** no header `Authorization` (veja [Autenticação](#autenticacao)). Sem ela: `401`.
2. **Host correto para o modo da key** — o host `sandbox.*` é Teste e exige `pzk_test_`; o host `api.*` é Produção e exige `pzk_live_`. Key e host têm que casar. Se não casarem: `401`.
3. **Plano ativo** no Projeto (só em Produção) — criar instâncias e enviar mensagens exigem assinatura ativa. Sem ela: `402`. No modo Teste é grátis (com teto diário).
Leitura (listar/detalhar), pareamento por QR Code e "marcar como lida" só exigem os pré-requisitos 1 e 2 — **não** dependem de plano.
## Base URL e o prefixo `/v1` [#base-url-e-o-prefixo-v1]
Todas as rotas vivem sob o prefixo `/v1`. A URL completa de um endpoint é sempre `/v1/`. A base URL define em qual **modo** (Teste ou Produção) você está operando:
| Modo | Base URL | Prefixo da key | Cobrança |
| ------------------- | ---------------------------------- | -------------- | ------------------------------------------------- |
| **Teste** (sandbox) | `https://sandbox.pepinozap.com.br` | `pzk_test_` | grátis, com teto de 100 mensagens/dia por Projeto |
| **Produção** (live) | `https://api.pepinozap.com.br` | `pzk_live_` | exige plano ativo |
É o **host que decide o modo**: qualquer host que comece com `sandbox` é Teste; os demais (`api.*`) são Produção. A API key **não** decide o modo — ela apenas precisa ser coerente com o host. Por isso uma `pzk_test_` chamando `api.*` (ou uma `pzk_live_` chamando `sandbox.*`) é rejeitada com `401`, mesmo sendo uma key real e válida.
```bash
# Teste (sandbox) — key pzk_test_
curl https://sandbox.pepinozap.com.br/v1/instances \
-H "Authorization: Bearer pzk_test_xxxxxxxxxxxxxxxx"
# Produção (live) — key pzk_live_
curl https://api.pepinozap.com.br/v1/instances \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"
```
Os dois modos são **100% isolados**: instâncias, conversas e webhooks criados
em Teste nunca aparecem em Produção e vice-versa. Inclusive um `id` de
instância de um modo, usado no outro modo, retorna `404` (não vaza entre
ambientes). Valide a integração inteira em `sandbox.*` sem custo e, quando
estiver pronto, troque a base URL para `api.*` e a key para `pzk_live_` — o
resto do código permanece igual.
## Autenticação [#autenticação]
Toda chamada envia a API key no header `Authorization` com o esquema `Bearer`:
```
Authorization: Bearer
```
A key é **escopada a um Projeto**: todas as instâncias e mensagens criadas ou listadas com ela pertencem a esse Projeto. A geração é self-service no painel (Integrações → API Keys), e a key crua aparece **uma única vez** na criação. Detalhes de cadastro, do toggle Teste/Produção e de revogação estão em [Autenticação](/docs/get-started/authentication).
**Exceção — SSE de QR Code.** O único endpoint que **não** usa o header é o stream de QR Code via Server-Sent Events (`GET /v1/instances/{id}/qr`), porque o `EventSource` do navegador não envia headers customizados. Nele a key vai pela query string, `?token=`. Recomenda-se emitir um token efêmero (`POST /v1/instances/{id}/qr-token`, válido \~2 min) para não expor a key crua na URL. Todos os demais endpoints — inclusive o **polling** de QR (`/qr/poll`) — usam o header normalmente. Veja [Autenticação → Fallback `?token=`](/docs/get-started/authentication#fallback-token-apenas-para-sse) e [Sua primeira instância → Parear via QR Code](/docs/get-started/first-instance#parear-via-qr-code).
## Formato do campo `to` [#formato-do-campo-to]
Todos os endpoints de mensagem identificam o destinatário pelo campo `to`. Ele aceita **três formatos**, todos equivalentes — use o que for mais conveniente:
| Formato | Exemplo | Observação |
| ------------------------------ | ------------------------------ | -------------------------------- |
| Apenas dígitos (E.164 sem `+`) | `5511999999999` | Forma mais simples; recomendada. |
| E.164 com `+` | `+5511999999999` | O `+` é aceito. |
| JID completo | `5511999999999@s.whatsapp.net` | Forma "nativa" do WhatsApp. |
O número deve incluir **código do país** e **DDD**, sem espaços, traços ou parênteses. Para o Brasil, o código do país é `55`.
A API **não verifica**, no momento do envio, se o número existe no WhatsApp —
a validação só confirma que o campo `to` não está vazio. Um `to` com número
inexistente é aceito e enfileirado (resposta `202`), mas a mensagem
simplesmente não é entregue, e **não** há evento de falha por número inválido.
Garanta que o `to` está correto antes de enviar. Para envio a **grupos**, use
o JID de grupo recebido nos webhooks; este guia trata de conversas individuais
(1:1).
## Convenções de requisição e resposta [#convenções-de-requisição-e-resposta]
* **Método e corpo.** Endpoints de escrita usam `POST`/`PATCH`/`DELETE`; os de leitura usam `GET`. Requisições com corpo JSON exigem o header `Content-Type: application/json` (a exceção é o upload de mídia por arquivo, que é `multipart/form-data`).
* **Formato.** Pedidos e respostas são JSON (`UTF-8`), salvo o SSE de QR (`text/event-stream`) e o upload de mídia (multipart).
* **Códigos de sucesso por tipo de operação:**
| Operação | Sucesso | Corpo da resposta |
| -------------------------------------- | ---------------- | -------------------------------------------- |
| Criar instância (`POST /v1/instances`) | `201 Created` | A instância criada (objeto completo). |
| Detalhar / listar / atualizar settings | `200 OK` | A instância (ou a lista). |
| Remover instância (`DELETE`) | `204 No Content` | Sem corpo. |
| Enviar qualquer tipo de mensagem | `202 Accepted` | Confirmação de enfileiramento (veja abaixo). |
* **Confirmação de envio.** Os endpoints de envio respondem com um objeto curto que confirma o **enfileiramento**, não a entrega:
```json
{
"queued": true,
"to": "5511999999999"
}
```
Endpoints de mídia e sticker incluem também o campo `type` (ex.: `"type": "image"`). O `to` ecoado é exatamente o que você enviou.
## Envio assíncrono (202) e idempotência [#envio-assíncrono-202-e-idempotência]
O envio de mensagens é **assíncrono**. A resposta `202 Accepted` confirma apenas que a mensagem foi **enfileirada** — não que foi entregue nem lida. O processamento real (envio ao WhatsApp) ocorre logo em seguida, em segundo plano. A confirmação de **entrega e leitura** chega depois pelo evento `message.status` no [webhook](/docs/webhooks).
**A instância precisa estar `CONNECTED` para a mensagem sair.** Enviar para
uma instância que não está conectada (por exemplo, `DISCONNECTED` ou aguardando
QR) **também** retorna `202` — mas a mensagem fica em espera e **não** é
entregue, sem gerar evento de falha. Confirme `status == CONNECTED` (via
`GET /v1/instances/{id}` ou `GET /v1/instances/{id}/qr/poll` com
`connected == true`) **antes** de enviar. Instâncias em estado terminal
(`BANNED`/`ERROR`) são bloqueadas já no envio, com `409` (veja a tabela de
erros).
**Idempotência.** Os endpoints de envio **não são idempotentes**: cada chamada enfileira um novo envio. Se a sua requisição falhar com erro de rede ou timeout **depois** de a API ter aceitado o job, repeti-la pode resultar em mensagem duplicada. Para reenviar com segurança, controle a deduplicação no seu lado (por exemplo, só repita quando tiver certeza de que a chamada anterior **não** retornou `202`). Já os erros `402` (plano/créditos), `401`, `403`, `404`, `409` e `429` são respostas de negócio/validação — **não** os repita em loop: corrija a causa (assinar, recarregar, conectar a instância, corrigir a key) e tente de novo.
## Envelope de erro [#envelope-de-erro]
Toda resposta de erro segue um envelope único e estável:
```json
{
"error": {
"code": "BAD_REQUEST",
"message": "campos to e body são obrigatórios"
}
}
```
O campo `code` identifica a **categoria** de forma estável — programe o seu tratamento de erros em cima dele. O campo `message` é apenas legível por humanos (em português) e pode mudar; **não** faça parsing nem `switch` sobre a `message`, com uma exceção prática anotada na tabela (o `402` de plano vs. créditos).
| Status | `code` | Significado |
| ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Corpo JSON inválido ou campo obrigatório faltando/ inválido (ex.: `to` vazio, `type` de mídia inválido). |
| `401` | `UNAUTHORIZED` | API key ausente, inválida, **ou** do modo errado para o host (`pzk_live_` no sandbox, ou vice-versa). |
| `402` | `PAYMENT_REQUIRED` | Sem plano ativo **ou** sem créditos da API (ver [abaixo](#pre-requisito-plano-ativo-402)). Distinga os dois casos pela `message`. **Não** repita a chamada — exige ação humana (assinar/recarregar). |
| `403` | `FORBIDDEN` | Projeto inativo ou sem permissão. |
| `404` | `NOT_FOUND` | Recurso não encontrado no Projeto da key — inclui o caso de a instância existir, mas pertencer a **outro modo** (teste/produção) ou a outro Projeto. |
| `409` | `CONFLICT` | Ao **criar** instância: cota de números do plano atingida. Ao **enviar**: instância não-operacional (`BANNED` ou `ERROR`). |
| `429` | `RATE_LIMITED` | **Apenas no sandbox:** teto diário do Projeto atingido (100 mensagens/dia por Projeto, enviadas + recebidas; o contador zera à meia-noite no horário de São Paulo). Em produção não ocorre. |
| `5xx` | `INTERNAL_ERROR` | Falha inesperada do servidor. Em geral é transitória — pode ser repetida com recuo (backoff). |
O `404` é deliberadamente "cego" ao motivo: tentar acessar uma instância de
outro modo (ex.: um `id` de produção usando a base URL de sandbox) ou de outro
Projeto retorna `404`, e não um `403`. Isso evita vazar a existência de
recursos entre Projetos e entre ambientes. Se um `id` que você "tem certeza"
que existe dá `404`, confira primeiro se a base URL e o prefixo da key batem
com o modo em que a instância foi criada.
## Pré-requisito: plano ativo (402) [#pré-requisito-plano-ativo-402]
Além da API key, o Projeto precisa de uma **assinatura ativa** para **criar instâncias** e **enviar mensagens** em produção. Sem plano ativo, esses endpoints retornam `402` (`PAYMENT_REQUIRED`):
```json
{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "É necessário um plano ativo para usar este recurso. Assine em \"Meu plano\"."
}
}
```
Endpoints que **exigem** plano ativo (em produção):
* `POST /v1/instances` — criar instância
* `POST /v1/instances/{id}/messages` e todos os demais envios (`/media`, `/media-upload`, `/location`, `/contact`, `/sticker`, `/reaction`, `/poll`)
Endpoints de **leitura** (listar/detalhar instâncias), o **pareamento por QR Code** (SSE, polling e emissão de token) e o **marcar como lida** (`/messages/read`) continuam liberados mesmo sem plano.
**Modo Teste é grátis.** Em `sandbox.*` a assinatura **não** é exigida — você só esbarra no teto diário (`429`). Use o sandbox para validar a integração inteira sem custo.
**Créditos da API (também `402`).** Projetos no modo **API** consomem créditos pré-pagos a cada mensagem **enviada pela API key** (envios pelo painel/inbox **não** consomem). Quando o saldo zera, os endpoints de envio retornam o **mesmo** `402` `PAYMENT_REQUIRED`, mas com a `message` indicando créditos insuficientes (ex.: `"créditos da API insuficientes — recarregue em Meu plano"`). É por isso que, para o `402`, a `message` é o único sinal que distingue os dois casos: **falta de plano** versus **falta de créditos**.
A resolução de ambos (assinar ou recarregar) é em **Meu plano**, no painel — é um gate de negócio que exige ação humana, **não** repita a chamada. Projetos de cortesia (isentos, marcados pelo time PEPINO) nunca recebem este erro. Detalhes em [Autenticação → Plano ativo](/docs/get-started/authentication#plano-ativo-erro-402).
## Como navegar a referência [#como-navegar-a-referência]
Os endpoints abaixo agrupam-se em quatro áreas. Cada link leva à página do endpoint, com todos os campos, exemplos por linguagem e o playground "Try it".
### Instâncias [#instâncias]
Conectar e gerenciar os números de WhatsApp do Projeto.
| Operação | Método e caminho | Referência |
| ------------------------------ | ----------------------------------- | --------------------------------------------------------------------- |
| Listar instâncias | `GET /v1/instances` | [listInstances](/docs/api/instancias/listInstances) |
| Criar instância | `POST /v1/instances` | [createInstance](/docs/api/instancias/createInstance) |
| Detalhar instância | `GET /v1/instances/{id}` | [getInstance](/docs/api/instancias/getInstance) |
| Atualizar configurações | `PATCH /v1/instances/{id}/settings` | [updateInstanceSettings](/docs/api/instancias/updateInstanceSettings) |
| Remover instância | `DELETE /v1/instances/{id}` | [deleteInstance](/docs/api/instancias/deleteInstance) |
| Parear via QR Code (SSE) | `GET /v1/instances/{id}/qr` | [streamInstanceQR](/docs/api/instancias/streamInstanceQR) |
| Parear via QR Code (polling) | `GET /v1/instances/{id}/qr/poll` | [pollInstanceQR](/docs/api/instancias/pollInstanceQR) |
| Token efêmero para o SSE de QR | `POST /v1/instances/{id}/qr-token` | [createQrToken](/docs/api/instancias/createQrToken) |
O ciclo de vida da instância e o pareamento estão detalhados em [Sua primeira instância](/docs/get-started/first-instance).
### Mensagens [#mensagens]
Todos os envios são por `POST /v1/instances/{id}/messages/...`, respondem `202` e são assíncronos.
| Tipo | Caminho | Referência |
| ------------------------- | -------------------------------- | -------------------------------------------------------------- |
| Texto | `POST .../messages` | [sendTextMessage](/docs/api/mensagens/sendTextMessage) |
| Mídia (por URL) | `POST .../messages/media` | [sendMediaMessage](/docs/api/mensagens/sendMediaMessage) |
| Mídia (upload de arquivo) | `POST .../messages/media-upload` | [sendMediaUpload](/docs/api/mensagens/sendMediaUpload) |
| Localização | `POST .../messages/location` | [sendLocationMessage](/docs/api/mensagens/sendLocationMessage) |
| Contato | `POST .../messages/contact` | [sendContactMessage](/docs/api/mensagens/sendContactMessage) |
| Sticker | `POST .../messages/sticker` | [sendStickerMessage](/docs/api/mensagens/sendStickerMessage) |
| Reação | `POST .../messages/reaction` | [sendReactionMessage](/docs/api/mensagens/sendReactionMessage) |
| Enquete | `POST .../messages/poll` | [sendPollMessage](/docs/api/mensagens/sendPollMessage) |
| Marcar como lida | `POST .../messages/read` | [markMessagesRead](/docs/api/mensagens/markMessagesRead) |
Notas úteis: em **mídia**, o campo `type` aceita `image`, `video`, `audio` ou `document`, e um áudio com `ptt: true` vira nota de voz; em **reação**, `emoji` vazio remove a reação; em **enquete**, `options` deve ter de 2 a 12 alternativas. Os campos exatos de cada tipo estão na página da referência correspondente.
### Webhooks [#webhooks]
O integrador **recebe** eventos (mensagem recebida, status de envio e status da instância) em uma URL própria, cadastrada **via API** (self-service):
| Operação | Método e caminho | Referência |
| ----------------- | -------------------------- | ------------------------------------------------- |
| Cadastrar webhook | `POST /v1/webhooks` | [createWebhook](/docs/api/webhooks/createWebhook) |
| Listar webhooks | `GET /v1/webhooks` | [listWebhooks](/docs/api/webhooks/listWebhooks) |
| Remover webhook | `DELETE /v1/webhooks/{id}` | [deleteWebhook](/docs/api/webhooks/deleteWebhook) |
O formato do payload, a assinatura HMAC e a lista de eventos estão em [Webhooks](/docs/webhooks). Para receber eventos em tempo real por conexão persistente em vez de HTTP, veja também o [WebSocket](/docs/webhooks/websocket).
### Inbox (CRM) [#inbox-crm]
Consultar as conversas e mensagens armazenadas pela plataforma e gerir o atendimento (status, atribuição):
| Operação | Método e caminho | Referência |
| ------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| Listar conversas | `GET /v1/inbox/conversations` | [listInboxConversations](/docs/api/inbox/listInboxConversations) |
| Detalhar conversa | `GET /v1/inbox/conversations/{id}` | [getInboxConversation](/docs/api/inbox/getInboxConversation) |
| Listar mensagens da conversa | `GET /v1/inbox/conversations/{id}/messages` | [listInboxMessages](/docs/api/inbox/listInboxMessages) |
| Mudar status (encerrar/reabrir) | `POST /v1/inbox/conversations/{id}/status` | [setConversationStatus](/docs/api/inbox/setConversationStatus) |
| Atribuir a um atendente | `POST /v1/inbox/conversations/{id}/assign` | [assignConversation](/docs/api/inbox/assignConversation) |
### Gestão (CRM) [#gestão-crm]
As ferramentas de gestão do atendimento. O modelo de dados e o passo a passo de cada uma estão no guia [CRM e gestão](/docs/crm):
| Área | O que faz | Referência |
| -------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Relatórios | Métricas agregadas do atendimento | [getReportsSummary](/docs/api/relatorios/getReportsSummary) · [guia](/docs/crm/relatorios) |
| Etiquetas | Classificar e filtrar conversas | [listLabels](/docs/api/etiquetas/listLabels) · [guia](/docs/crm/etiquetas-encerramento) |
| Justificativas | Motivos de encerramento | [listCloseReasons](/docs/api/justificativas/listCloseReasons) |
| Fluxos | Construtor de chatbot por número | [listFlows](/docs/api/fluxos/listFlows) · [guia](/docs/crm/fluxos) |
| Funil | Funil cujas etapas são regras sobre a conversa | [listFunnels](/docs/api/funil/listFunnels) · [guia](/docs/crm/funil) |
## Próximos passos [#próximos-passos]
* [Autenticação](/docs/get-started/authentication) — gerar a API key e entender os modos teste/produção.
* [Sua primeira instância](/docs/get-started/first-instance) — conectar um número via QR Code.
* [Enviar uma mensagem de texto](/docs/api/mensagens/sendTextMessage) — o primeiro envio após o pareamento.
* [Webhooks](/docs/webhooks) — receber eventos de mensagens e de status da instância.
* [CRM e gestão](/docs/crm) — relatórios, etiquetas, encerramento, equipe e o construtor de chatbot.
# Disparo em massa (campanhas) (/docs/campanhas)
Uma **campanha** envia uma mensagem-template para muitos contatos respeitando uma **cadência anti-ban**: a plataforma controla *quando* e *em que ritmo* cada mensagem sai, em vez de despejar tudo de uma vez. Você cria a campanha, configura a cadência, dispara, e acompanha o status de cada destinatário.
Disparo em massa pode levar ao **banimento** do número pela Meta. A cadência reduz o risco, mas
não o elimina: use listas com **opt-in**, conteúdo não-spam e volume moderado. O risco é do
titular da conta. Criar/editar exige o add-on **Disparo em massa**; disparar/retomar exige também
assinatura ativa (no modo teste é liberado para validar a integração).
## Ciclo de vida [#ciclo-de-vida]
```text
DRAFT ──start──> RUNNING ──pause──> PAUSED ──resume──> RUNNING ──> COMPLETED
│ ▲
└── auto-pausa ────┘ (N falhas/inválidos consecutivos)
```
* **DRAFT** — criada, nada foi enviado. Edite e adicione/remova destinatários à vontade.
* **RUNNING** — a engine dispara em background, respeitando a cadência.
* **PAUSED** — pausada (manualmente ou por auto-pausa). Retome quando quiser.
* **COMPLETED** / **CANCELLED** — encerrada; o histórico permanece.
## Tutorial rápido (curl) [#tutorial-rápido-curl]
Fluxo completo de ponta a ponta — criar, (opcional) assinar os eventos, disparar e acompanhar. Comece pelo **sandbox** (liberado para validar a integração); em produção, troque o host e o prefixo da chave.
```bash
# Ambiente. Sandbox para testar; produção quando estiver pronto.
BASE="https://sandbox.pepinozap.com.br" # produção: https://api.pepinozap.com.br
TOKEN="pzk_test_xxx" # produção: pzk_live_xxx
AUTH="Authorization: Bearer $TOKEN"
```
**1. Descubra a instância (número conectado) que vai disparar:**
```bash
curl -s "$BASE/v1/instances" -H "$AUTH"
# pegue o "id" de uma instância com status CONNECTED -> INSTANCE
INSTANCE="cm5x8a9k20001abc123def456"
```
**2. (Opcional, recomendado) Assine os eventos em tempo real.** Cadastre um webhook que recebe `campaign.status` por destinatário (guarde o `secret` para validar a assinatura):
```bash
curl -s "$BASE/v1/webhooks" -H "$AUTH" -H 'Content-Type: application/json' -d '{
"name": "campanhas",
"url": "https://seusistema.com/webhooks/pepino",
"events": ["campaign.status"]
}'
```
**3. Crie a campanha** (volta `DRAFT`). Capture o `id` retornado:
```bash
curl -s "$BASE/v1/campaigns" -H "$AUTH" -H 'Content-Type: application/json' -d "{
\"name\": \"Promo Junho\",
\"instanceId\": \"$INSTANCE\",
\"template\": \"Olá {{nome}}! Aproveite {{desconto}} só hoje.\",
\"recipients\": [
{ \"phone\": \"+55 11 99999-0001\", \"name\": \"Maria\", \"vars\": { \"desconto\": \"20% off\" } },
\"5511999990002\"
],
\"cadence\": {
\"warmup\": { \"base\": 20, \"factor\": 1.2, \"cap\": 200 },
\"window\": { \"start\": \"08:00\", \"end\": \"23:00\", \"tz\": \"America/Sao_Paulo\" },
\"pacing\": { \"baseSeconds\": 60, \"jitterPct\": 0.2 },
\"autoPause\":{ \"consecutiveThreshold\": 5 },
\"validateNumbers\": true
}
}"
# -> { "id": "camp_...", "totalRecipients": 2 }
CAMPAIGN="camp_..."
```
**4. Dispare.** A engine assume em background (responde `202` na hora):
```bash
curl -s -X POST "$BASE/v1/campaigns/$CAMPAIGN/start" -H "$AUTH"
# -> { "started": true }
```
**5. Acompanhe.** Pelos eventos `campaign.status` (passo 2) ou por polling:
```bash
# Agregado (totais por status + runtime: dia, teto de hoje, próximo envio)
curl -s "$BASE/v1/campaigns/$CAMPAIGN" -H "$AUTH"
# Por destinatário (paginado; filtre por status)
curl -s "$BASE/v1/campaigns/$CAMPAIGN/recipients?status=FAILED&page=1" -H "$AUTH"
```
**6. Controle quando precisar:**
```bash
curl -s -X POST "$BASE/v1/campaigns/$CAMPAIGN/pause" -H "$AUTH" # pausar
curl -s -X POST "$BASE/v1/campaigns/$CAMPAIGN/resume" -H "$AUTH" # retomar
curl -s -X POST "$BASE/v1/campaigns/$CAMPAIGN/complete" -H "$AUTH" # encerrar
```
No **sandbox** o recurso é liberado para validar a integração (com um teto diário por projeto). Em
**produção**, criar/editar exige o add-on “Disparo em massa” e disparar/retomar exige também
assinatura ativa — sem isso a API responde `402`.
## Criando uma campanha [#criando-uma-campanha]
`POST /v1/campaigns` cria em **DRAFT**. A mensagem é um **template** com variáveis por destinatário, e cada destinatário pode ser só o número ou um objeto com `phone`, `name` e `vars`:
```json
{
"name": "Promo Junho",
"instanceId": "cm5x8a9k20001abc123def456",
"template": "Olá {{nome}}! Aproveite {{desconto}} só hoje.",
"recipients": [
{ "phone": "+55 11 99999-0001", "name": "Maria", "vars": { "desconto": "20% off" } },
"5511999990002"
],
"cadence": {
"warmup": { "base": 20, "factor": 1.2, "cap": 200 },
"window": { "start": "08:00", "end": "23:00", "tz": "America/Sao_Paulo" },
"pacing": { "baseSeconds": 60, "jitterPct": 0.2 },
"autoPause": { "consecutiveThreshold": 5 },
"validateNumbers": true
}
}
```
* **Variáveis** — `{{nome}}` vem do `name`; qualquer `{{chave}}` vem de `vars.chave`. Variável ausente vira string vazia.
* **Destinatários** — números em qualquer formato (mantemos só os dígitos); vazios e duplicados são descartados. Mínimo 1, máximo **10.000** por campanha.
* **`cadence` é opcional** — campos omitidos usam os defaults abaixo.
## A cadência anti-ban [#a-cadência-anti-ban]
| Recurso | Campo | O que faz |
| ------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Warmup** | `warmup.{base,factor,cap}` | Teto diário **crescente**: `cap_do_dia = min(cap, ceil(base * factor^dia))`. Ex.: base 20, fator 1.2, teto 200 — começa em 20/dia e cresce até 200. |
| **Janela horária** | `window.{start,end,tz}` | Só envia no intervalo (no timezone). Fora dele, **pausa e retoma** na próxima abertura. |
| **Ritmo (pacing)** | `pacing.{baseSeconds,jitterPct}` | Intervalo entre envios = `baseSeconds` ± `jitterPct` (aleatório, sem rajada). Ex.: 60s ±20%. |
| **Auto-pausa** | `autoPause.consecutiveThreshold` | Pausa a campanha após **N falhas/inválidos consecutivos** (default 5). O motivo fica em `pausedReason`. |
| **Validação** | `validateNumbers` | Confere no WhatsApp **antes** de enviar; número sem conta vira `invalid` e **não consome** o teto do dia. |
O **dia da campanha** (`dayIndex`) avança no virar do dia, no timezone configurado — junto reseta o contador `sentToday`. Acompanhe `sentToday`/`capToday` e o `nextSendAt` em `GET /v1/campaigns/{id}`.
Defaults quando você omite a `cadence`: warmup base 20 / fator 1.2 / teto 200; janela 08:00–23:00
America/Sao\_Paulo; ritmo 60s ±20%; auto-pausa em 5; validação **ligada**. A janela não pode virar
a meia-noite (início precisa ser antes do fim).
## Disparando e controlando [#disparando-e-controlando]
| Ação | Endpoint |
| ------------------------------------- | --------------------------------------------------- |
| Disparar (DRAFT/SCHEDULED → RUNNING) | `POST /v1/campaigns/{id}/start` |
| Pausar (RUNNING → PAUSED) | `POST /v1/campaigns/{id}/pause` |
| Retomar (PAUSED → RUNNING) | `POST /v1/campaigns/{id}/resume` |
| Encerrar / cancelar | `POST /v1/campaigns/{id}/complete` (`?cancel=true`) |
| Editar (só DRAFT/PAUSED) | `PATCH /v1/campaigns/{id}` |
| Adicionar destinatários | `POST /v1/campaigns/{id}/recipients` |
| Remover destinatário (ainda pendente) | `DELETE /v1/campaigns/{id}/recipients/{sendId}` |
`start` responde `202` e a engine assume — o envio é assíncrono.
## Acompanhando o resultado [#acompanhando-o-resultado]
**Agregado** — `GET /v1/campaigns/{id}` traz `totals` por status (`pending`, `sent`, `delivered`, `read`, `responded`, `failed`, `invalid`) e o `runtime` (dia, teto e enviados de hoje, último e próximo envio).
**Por destinatário** — `GET /v1/campaigns/{id}/recipients` lista cada contato com seu `status`, motivo de erro e marcos de tempo (paginado, filtrável por `?status=`).
**Tempo real** — assine o evento [`campaign.status`](/docs/webhooks/events#campaignstatus) (webhook ou WebSocket) para receber a mudança de status de cada destinatário (`sent`, `delivered`, `read`, `responded`, `failed`, `invalid`) assim que acontece.
```json
{
"event": "campaign.status",
"instanceId": "cm5x8a9k20001abc123def456",
"data": { "campaignId": "camp_3Hk9Zq2pVxL", "recipient": "5511999999999", "status": "delivered" }
}
```
## Próximos passos [#próximos-passos]
* [Referência da API — Campanhas](/docs/api/campanhas/createCampaign)
* [Eventos de webhook](/docs/webhooks/events) — inclusive `campaign.status`
* [Inbox e histórico](/docs/crm/inbox) — as respostas dos contatos ficam registradas
# Departamentos (/docs/crm/departamentos)
Um **departamento** agrupa atendentes por área (Suporte, Financeiro, Comercial…). Cada atendente fica vinculado a um departamento; cada conversa "está" em um departamento e pode ser **transferida** entre eles. O caso típico: o contato cai no Suporte, o atendente percebe que é uma questão financeira e **transfere a conversa para o Financeiro** — ela sai da visão do Suporte e entra na fila do Financeiro.
Departamentos são **escopados ao Projeto** da sua API key e seguem a mesma autenticação por
`Authorization: Bearer` do resto da API. O CRUD e a transferência também estão disponíveis para
integradores via API key.
## O modelo [#o-modelo]
* **Atendente → 1 departamento.** Cada membro da equipe pode estar vinculado a um departamento (ou a nenhum). Definido na página **Equipe** do painel (ou via API do painel).
* **Conversa → 1 departamento (ou nenhum).** Uma conversa "está" em um departamento por vez. **Sem departamento = fila geral**, visível a todos os atendentes.
* **Como a conversa cai num departamento:** (1) pelo **número** — cada instância pode ter um departamento padrão (no cadastro da instância) que o ticket novo herda; (2) pelo **chatbot** — o nó "Transferir" do [construtor de fluxo](/docs/crm/fluxos) pode mandar pra um departamento; (3) por **transferência manual** (botão no topo do chat) ou pela API. Sem nenhum desses, a conversa fica na **fila geral** (sem departamento, visível a todos).
* **Roteamento automático respeita o departamento:** quando a [Equipe](/docs/crm/equipe) usa atribuição automática (menos ocupado / rodízio), o atendente escolhido sai **do departamento da conversa**; na fila geral, de qualquer atendente online.
### Visibilidade por departamento [#visibilidade-por-departamento]
A regra de quem enxerga o quê depende da permissão `ver_todas_conversas`:
| Quem | Enxerga |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Dono/Admin, ou atendente com `ver_todas_conversas` | **Todas** as conversas do Projeto. |
| Atendente **sem** `ver_todas_conversas` | As conversas **atribuídas a ele** + as **sem dono** do **seu departamento** + as **sem dono da fila geral** (sem departamento). |
Ou seja: ao transferir uma conversa do Suporte para o Financeiro, ela **deixa de aparecer** para os atendentes do Suporte (que não têm "ver todas") e passa a aparecer para os do Financeiro. Conversas **sem departamento** ficam visíveis para todos — é a fila de triagem.
## Transferir uma conversa [#transferir-uma-conversa]
Transferir é o caminho principal e foi feito para ser rápido:
* **No painel:** no topo do chat, ao lado das etiquetas, há um botão com o departamento atual. Clique e escolha o destino (ou **"Fila geral"** para tirar o departamento).
* **Na API:** `POST /v1/inbox/conversations/{id}/department` com `{ "departmentId": "..." }`.
A transferência **solta o atendente atual**: a conversa volta para a **fila do departamento de
destino** (sem dono), para que alguém daquele departamento assuma. Envie `departmentId: null` para
mandar para a fila geral.
## No painel [#no-painel]
| Ação | Onde |
| ------------------------------------- | ----------------------------------------------------------------------- |
| Criar/excluir departamento | Inbox → engrenagem **Configurar atendimento** → aba **Deptos** |
| Vincular atendente a um departamento | **Equipe** → seletor de departamento no atendente |
| Departamento padrão do número | **Instâncias** → seletor "Departamento padrão" na instância |
| Transferir a conversa | **Inbox** → botão de departamento no topo do chat |
| Filtrar o inbox por departamento | **Inbox** → chips de departamento acima da lista |
| Chatbot transfere pra um departamento | **Fluxos** → nó **Transferir** → campo "Transferir para o departamento" |
Gerenciar o catálogo de departamentos e vincular atendentes exige um usuário **dono ou administrador**. **Transferir** uma conversa é liberado a qualquer atendente com acesso à conversa.
## Na API [#na-api]
| Operação | Método e rota |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| Listar departamentos | [`GET /v1/inbox/departments`](/docs/api/departamentos/listDepartments) |
| Criar departamento | [`POST /v1/inbox/departments`](/docs/api/departamentos/createDepartment) |
| Atualizar departamento | [`PATCH /v1/inbox/departments/{id}`](/docs/api/departamentos/updateDepartment) |
| Remover departamento | [`DELETE /v1/inbox/departments/{id}`](/docs/api/departamentos/deleteDepartment) |
| Transferir a conversa | [`POST /v1/inbox/conversations/{id}/department`](/docs/api/departamentos/transferConversationDepartment) |
A conversa no [Inbox](/docs/api/inbox/listInboxConversations) traz `departmentId` e `departmentName`; a listagem aceita o filtro `?departmentId=` para ver só um departamento. O **vínculo do atendente** a um departamento é feito pelo painel (não exposto na API de integração).
### Exemplos [#exemplos]
Criar um departamento:
```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/departments \
-H "Authorization: Bearer pzk_sua_chave" \
-H "Content-Type: application/json" \
-d '{ "name": "Financeiro", "description": "Cobrança, boletos e notas fiscais" }'
```
Transferir uma conversa para esse departamento:
```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
-H "Authorization: Bearer pzk_sua_chave" \
-H "Content-Type: application/json" \
-d '{ "departmentId": "dep_financeiro" }'
```
Devolver a conversa para a fila geral (sem departamento):
```bash
curl -X POST https://api.pepinozap.com.br/v1/inbox/conversations/conv_123/department \
-H "Authorization: Bearer pzk_sua_chave" \
-H "Content-Type: application/json" \
-d '{ "departmentId": null }'
```
## Pontos importantes [#pontos-importantes]
* **Soft-delete:** remover um departamento o desativa. As conversas que estavam nele **voltam para a fila geral** e os atendentes vinculados perdem o vínculo — nada de histórico quebra.
* **Nome único** por Projeto (case-insensitive); nome repetido retorna `409`.
* **Departamentos e [etiquetas](/docs/crm/etiquetas-encerramento) são ortogonais:** o departamento diz *qual fila* atende a conversa; a etiqueta é uma *marcação* livre. Uma conversa pode ter os dois.
Veja também **[Equipe e permissões](/docs/crm/equipe)** (atendentes, presença e a permissão `ver_todas_conversas` que rege a visibilidade acima).
# Equipe e permissões (/docs/crm/equipe)
O atendimento é feito por uma **equipe**: cada usuário do painel é um atendente com um **cargo** e, opcionalmente, **permissões granulares**. A presença (online/offline) e a política de **roteamento** decidem para quem as conversas novas vão.
Equipe, presença e permissões são geridos **no painel** (seção Equipe), sob a
sessão do usuário logado — **não** pela API key de integração. Esta página
documenta o **modelo**, para você entender como o roteamento e a visibilidade
das conversas se comportam.
## Cargos [#cargos]
| Cargo | Pode |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Dono** (OWNER) | Tudo, incluindo cobrança e gestão de administradores. Único por conta. |
| **Administrador** (ADMIN) | Tudo no atendimento e na equipe, exceto mexer em outros administradores e na cobrança. |
| **Atendente** (MEMBER) | O que as **permissões granulares** liberarem. Sem restrição definida = acesso de atendimento completo. |
Dono e administrador têm **acesso total** por definição — as permissões granulares só se aplicam a **atendentes**. Só o **dono** promove/rebaixa administradores.
## Permissões granulares [#permissões-granulares]
Para um atendente, o gestor marca exatamente o que ele pode. As chaves:
| Permissão | Libera |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `ver_todas_conversas` | Ver as conversas de **toda** a equipe. Sem ela, o atendente só vê as **atribuídas a ele** ou **sem dono**. |
| `atribuir` | Atribuir/transferir conversas a atendentes. |
| `encerrar` | Encerrar (resolver) e reabrir conversas. |
| `ver_relatorios` | Acessar a seção de [Relatórios](/docs/crm/relatorios). |
| `disparar_campanha` | Criar e disparar campanhas (disparo em massa). |
| `gerenciar_instancias` | Conectar/remover números (instâncias). |
A permissão `ver_todas_conversas` é também um limite de **visibilidade de
dados**: um atendente sem ela tem a listagem do Inbox filtrada no servidor
para as próprias conversas — não é só esconder na interface. Gestão de
equipe e cobrança **nunca** são delegáveis a atendente; ficam fora dessa lista.
## Presença (online/offline) [#presença-onlineoffline]
Cada atendente tem um estado de **presença** que o painel mantém por um *heartbeat* enquanto a aba está aberta. A presença é **efêmera**: expira sozinha em \~90 segundos sem sinal (fechou o navegador, caiu a rede → fica offline automaticamente). Ela alimenta o roteamento: conversas novas só são direcionadas a quem está **online**.
## Roteamento automático [#roteamento-automático]
Quando uma conversa nova chega **sem** um fluxo de chatbot ativo decidindo o destino (veja [Construtor de fluxo](/docs/crm/fluxos)), a plataforma a direciona segundo a **política do Projeto**:
| Política | Comportamento |
| ------------- | -------------------------------------------------------------------------------- |
| `manual` | Ninguém é atribuído automaticamente; a conversa entra na fila para alguém pegar. |
| `least_busy` | Vai para o atendente **online** com **menos** conversas em aberto. |
| `round_robin` | **Rodízio** entre os atendentes online, distribuindo por igual. |
As duas políticas automáticas só consideram atendentes **online**. Se ninguém estiver online, a conversa fica na fila até alguém entrar ou pegá-la manualmente. Uma atribuição **manual** (pelo painel ou via [`assign`](/docs/api/inbox/assignConversation)) sempre prevalece sobre o automático para aquela conversa.
Quando há um **fluxo de chatbot ativo** na instância, ele tem **precedência**:
o bot atende primeiro e só entrega ao humano (segundo a política acima) quando
o fluxo chega a um nó de **transferência**. Detalhes em
[Construtor de fluxo](/docs/crm/fluxos).
# Etiquetas e encerramento (/docs/crm/etiquetas-encerramento)
Duas ferramentas organizam o Inbox: **etiquetas** classificam conversas de forma transversal (VIP, Suporte, Vendas…) e as **justificativas de encerramento** registram *por que* cada atendimento foi resolvido. Ambas são catálogos do Projeto e podem ser geridas pela API.
## Etiquetas [#etiquetas]
Uma etiqueta tem **nome** e **cor**. A relação com conversas é **M:N**: uma conversa pode ter várias etiquetas e uma etiqueta classifica várias conversas.
```json
{ "id": "lbl_01HV...", "name": "VIP", "color": "amber" }
```
A **paleta de cores é fixa** (casa com o design do painel):
`gray` · `green` · `blue` · `purple` · `amber` · `red` · `cyan` · `pink`
Uma cor fora dessa lista cai para `gray`. O `name` é único no Projeto (máx. 40 caracteres) — repetir retorna `409`.
### Endpoints [#endpoints]
| Operação | Método e caminho |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Listar | [`GET /v1/inbox/labels`](/docs/api/etiquetas/listLabels) |
| Criar | [`POST /v1/inbox/labels`](/docs/api/etiquetas/createLabel) |
| Atualizar | [`PATCH /v1/inbox/labels/{id}`](/docs/api/etiquetas/updateLabel) |
| Remover | [`DELETE /v1/inbox/labels/{id}`](/docs/api/etiquetas/deleteLabel) |
| Aplicar à conversa | [`PUT /v1/inbox/conversations/{id}/labels/{labelId}`](/docs/api/etiquetas/assignConversationLabel) |
| Remover da conversa | [`DELETE /v1/inbox/conversations/{id}/labels/{labelId}`](/docs/api/etiquetas/unassignConversationLabel) |
Aplicar é **idempotente** — aplicar a mesma etiqueta de novo não duplica. As etiquetas de uma conversa vêm no campo `labels` ao [detalhar a conversa](/docs/api/inbox/getInboxConversation).
### Filtrar o Inbox por etiqueta [#filtrar-o-inbox-por-etiqueta]
A listagem de conversas aceita `labelId`: [`GET /v1/inbox/conversations?labelId=lbl_01HV...`](/docs/api/inbox/listInboxConversations) traz só as conversas com aquela etiqueta — útil para montar filas segmentadas (ex.: "todas as VIP em aberto") a partir do seu sistema.
**Soft-delete.** Remover uma etiqueta a **desativa**: ela some da paleta e das
conversas ativas, mas o histórico que já a referenciava não quebra. Não há
"lixeira" — para voltar a usar, crie de novo.
## Justificativas de encerramento [#justificativas-de-encerramento]
São os **motivos** que o atendente escolhe ao resolver uma conversa (ex.: "Resolvido", "Sem resposta do cliente", "Duplicado"). Catálogo do Projeto:
```json
{ "id": "cr_01HV...", "name": "Resolvido", "position": 0 }
```
`name` é único (máx. 60 caracteres); `position` é a ordem de exibição. Mesmo soft-delete das etiquetas: remover desativa, sem quebrar conversas já encerradas com aquele motivo.
| Operação | Método e caminho |
| -------- | ----------------------------------------------------------------------------------- |
| Listar | [`GET /v1/inbox/close-reasons`](/docs/api/justificativas/listCloseReasons) |
| Criar | [`POST /v1/inbox/close-reasons`](/docs/api/justificativas/createCloseReason) |
| Remover | [`DELETE /v1/inbox/close-reasons/{id}`](/docs/api/justificativas/deleteCloseReason) |
## Status da conversa e encerramento [#status-da-conversa-e-encerramento]
Toda conversa tem um **status**: `open`, `pending` ou `resolved`. Você o muda com [`POST /v1/inbox/conversations/{id}/status`](/docs/api/inbox/setConversationStatus).
Ao **resolver** (`status: resolved`), anexe a justificativa:
```json
{
"status": "resolved",
"closeReasonId": "cr_01HV...",
"closeNotes": "Cliente resolveu pelo app."
}
```
* `closeReasonId` — opcional, mas precisa ser um motivo **existente** do Projeto; inválido retorna `400`.
* `closeNotes` — observação livre, opcional.
* **Reabrir** (voltar para `open`/`pending`) **limpa** a justificativa anterior.
## Atribuir a um atendente [#atribuir-a-um-atendente]
Direcione a conversa a um atendente com [`POST /v1/inbox/conversations/{id}/assign`](/docs/api/inbox/assignConversation):
```json
{ "userId": "usr_01HV..." } // null desatribui
```
O atendente precisa pertencer ao mesmo Projeto. A atribuição manual **fixa o dono** daquela conversa e convive com o roteamento automático configurado na [Equipe](/docs/crm/equipe).
Pela **API key** (integração), as ações de status e atribuição não checam
permissão de atendente — a key tem escopo de Projeto. As permissões granulares
valem para **usuários do painel**; veja [Equipe e permissões](/docs/crm/equipe).
# Construtor de fluxo (chatbot) (/docs/crm/fluxos)
O **construtor de fluxo** é um chatbot visual: você desenha, num canvas, o caminho que uma conversa percorre — uma saudação, um menu de opções, uma pergunta, uma condição, uma espera — e a plataforma executa esse fluxo **automaticamente** quando uma mensagem chega, antes de qualquer atendente humano. É o mesmo recurso do editor de Fluxos no painel; esta página explica o **modelo** e como operá-lo pela API.
* **No painel:** Fluxos → (novo/editar) — editor visual com arrastar-e-soltar.
* **Na API:** [Fluxos](/docs/api/fluxos/listFlows) — o editor usa exatamente estes endpoints.
## Anatomia de um fluxo [#anatomia-de-um-fluxo]
Um **fluxo** é um cabeçalho (nome, instância, gatilho, ativo) + um conjunto de **nós** ligados por arestas. Regras:
* Um fluxo é **vinculado a uma instância** (número) — ou a nenhuma, valendo para qualquer número do Projeto.
* **Só 1 fluxo pode ficar ATIVO por instância.** Ativar um desativa os outros daquela instância automaticamente.
* O nó de **menor `ordem`** é o ponto de partida.
* Cada nó tem uma posição no canvas (`posicaoX`/`posicaoY`) — puramente visual — e um `conteudo` (objeto JSON) cujo formato depende do **tipo**.
### O gatilho [#o-gatilho]
Quando o fluxo dispara para uma conversa nova:
| `triggerType` | Dispara quando |
| ------------- | ------------------------------------------------------------------------------------ |
| `any` | **Qualquer** mensagem recebida inicia o fluxo. |
| `keyword` | Só quando o texto recebido **contém** o `triggerValue` (sem diferenciar maiúsculas). |
## Tipos de nó [#tipos-de-nó]
Cada nó tem um `tipo` e um `conteudo`. Os formatos:
### `message` — envia um texto [#message--envia-um-texto]
```json
{ "texto": "Olá {{nome}}, tudo bem? Bem-vindo à Loja X." }
```
Envia a mensagem e segue para o próximo nó (aresta padrão). Suporta [variáveis](#variáveis).
### `menu` — oferece opções numeradas [#menu--oferece-opções-numeradas]
```json
{
"texto": "Como posso ajudar?",
"options": [
{ "id": "opt_1", "numero": 1, "texto": "Falar com vendas", "targetNodeId": "nd_vendas" },
{ "id": "opt_2", "numero": 2, "texto": "Suporte", "targetNodeId": "nd_suporte" }
]
}
```
Envia o `texto` seguido das opções **numeradas automaticamente** (`1. Falar com vendas` …) e **espera a resposta**. O contato pode responder pelo **número** (`1`) ou pelo **texto** da opção. A resposta leva ao `targetNodeId` daquela opção. Resposta que não casa com nenhuma opção → o menu é **reenviado**.
### `input` — pergunta e guarda a resposta [#input--pergunta-e-guarda-a-resposta]
```json
{ "texto": "Qual o seu nome?", "variavel": "nome_cliente" }
```
Envia a pergunta, **espera a resposta** e guarda o que o contato digitar na variável indicada (aqui, `{{nome_cliente}}`), disponível nos próximos nós. Depois segue pela aresta padrão.
### `condition` — bifurca o caminho [#condition--bifurca-o-caminho]
```json
{ "variavel": "nome_cliente", "operador": "contem", "valor": "João", "onTrue": "nd_a", "onFalse": "nd_b" }
```
Avalia `variavel valor` e vai para `onTrue` ou `onFalse`. Operadores: `==` (igual), `!=` (diferente), `contem` (substring, sem diferenciar maiúsculas). Não envia mensagem — só decide o ramo.
### `delay` — espera antes de seguir [#delay--espera-antes-de-seguir]
```json
{ "segundos": 30 }
```
Pausa o fluxo pelo tempo indicado e **depois** segue. A espera é **não-bloqueante**: a sessão fica agendada e um agendador a retoma quando o tempo vence — não trava o atendimento. `0` segue na hora; o teto é **24 horas** (86400s).
### `action` — gancho de automação [#action--gancho-de-automação]
Nó reservado para automações (ex.: criar um negócio no funil). Hoje apenas **segue** para o próximo nó; é o ponto de extensão para evoluções.
### `transfer` — entrega ao humano [#transfer--entrega-ao-humano]
Encerra a parte automática e **transfere para um atendente**, seguindo a [política de roteamento](/docs/crm/equipe#roteamento-automático) do Projeto (menos ocupado, rodízio ou manual). É como o bot "passa o bastão".
### `close` — encerra a conversa [#close--encerra-a-conversa]
Finaliza o fluxo e marca a conversa como **resolvida**. Use ao fim de um autoatendimento que não precisa de humano.
## Variáveis [#variáveis]
No início de cada sessão, o fluxo já recebe dados do contato, usáveis com `{{chave}}` em qualquer `texto`:
| Variável | Conteúdo |
| ---------------------- | -------------------------------------------------- |
| `{{nome}}` | Nome do contato (push name do WhatsApp). |
| `{{numero}}` | Número do contato. |
| `{{numero_formatado}}` | Número do contato (formatado). |
| `{{mensagem_inicial}}` | O texto da primeira mensagem que disparou o fluxo. |
Nós do tipo `input` **adicionam** novas variáveis (o que o contato responder). Uma variável inexistente é substituída por vazio.
## Comportamento em tempo de execução [#comportamento-em-tempo-de-execução]
**O bot tem precedência sobre o roteamento humano.** Se há um fluxo ativo na
instância, ele decide o atendimento; o roteamento automático para atendentes
só entra quando o fluxo chega a um nó `transfer`.
* **Convivência com humano.** Se a conversa **já tem um atendente atribuído**, o bot **pausa** — não atropela o atendimento humano em andamento.
* **Uma sessão por conversa.** O estado (nó atual, variáveis, espera agendada) é mantido por conversa enquanto o fluxo roda.
* **Envio durável.** As mensagens do bot saem pela fila de envio confiável (com retries), igual aos demais envios da API.
* **Proteção contra laço.** Um fluxo mal montado (ciclo entre nós que não esperam resposta) é interrompido após um limite de passos, em vez de rodar para sempre.
* **Apagar o fluxo** encerra as sessões que estiverem rodando nele.
## Montando um fluxo pela API [#montando-um-fluxo-pela-api]
O editor visual faz isto nos bastidores; você pode reproduzir programaticamente:
1. **Crie o fluxo** — [`POST /v1/flows`](/docs/api/fluxos/createFlow) com `name`, `instanceId` e `triggerType`. Nasce **inativo**.
2. **Adicione os nós** — [`POST /v1/flows/{id}/nodes`](/docs/api/fluxos/createFlowNode), um por nó, com `tipo`, `conteudo`, posição e `ordem` (o menor é o início).
3. **Ligue os nós** — a aresta padrão (linear) com [`PATCH .../nodes/{nodeId}/connection`](/docs/api/fluxos/setFlowNodeConnection) (`proximoNodeId`); as saídas de um **menu** com [`PATCH .../nodes/{nodeId}/option-connection`](/docs/api/fluxos/setFlowNodeOptionConnection) (liga cada `optionId` a um nó).
4. **Ative** — [`PATCH /v1/flows/{id}`](/docs/api/fluxos/updateFlow) com `active: true`. Isso desativa os outros fluxos da mesma instância (conflito retorna `409`).
Ao **ativar**, garanta que o fluxo tem um nó inicial (a menor `ordem`) e que as
ligações levam a um nó terminal (`transfer` ou `close`) — senão a conversa
pode ficar no bot sem saída para um humano. Teste no ambiente **sandbox** antes
de ativar em produção.
# Funil configurável (/docs/crm/funil)
O funil do PEPINO ZAP não é um quadro de cards que você arrasta à mão: é **configurável por regras**. Você cria **etapas** e, em cada uma, define **uma regra sobre a conversa**. As conversas se distribuem sozinhas pelas etapas conforme atendem (ou não) a cada regra — então o funil reflete o estado real do atendimento, sem ninguém mover nada.
* **No painel:** Funil → (criar/editar) — canvas com arrastar-e-soltar, no mesmo estilo do [construtor de fluxo](/docs/crm/fluxos).
* **Na API:** [Funil](/docs/api/funil/listFunnels) — o editor visual usa exatamente estes endpoints.
## Como uma conversa cai numa etapa [#como-uma-conversa-cai-numa-etapa]
Cada etapa tem uma `position` (ordem). Uma conversa é colocada na **etapa de maior `position` cuja regra ela satisfaz**. É isso que dá o **formato de funil**: as etapas iniciais pegam muitas conversas, as finais (mais avançadas) pegam menos, e a queda entre elas é a sua taxa de conversão.
* Uma conversa fica em **uma** etapa (a mais avançada que casa).
* Conversas que não casam com nenhuma etapa ficam **fora do funil** (`unplaced`).
* A avaliação é feita **na leitura** ([`GET /v1/funnels/{id}/data`](/docs/api/funil/getFunnelData)), sobre as conversas mais recentes do escopo (instância opcional do funil).
## A regra de uma etapa [#a-regra-de-uma-etapa]
A regra combina condições com **E (AND)** — a conversa precisa satisfazer **todas** as condições presentes. Condição vazia/"any" = sem restrição.
| Critério | Valores | A conversa entra quando… |
| --------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| **Origem** | `any` · `inbound` · `outbound` | foi **receptiva** (o cliente iniciou) ou **ativa** (a empresa iniciou). |
| **Status** | `any` · `open` · `pending` · `resolved` | está aberta, pendente ou resolvida. |
| **Etiqueta** | `labelId` | tem a etiqueta indicada (ex.: "Proposta enviada"). |
| **Posição no fluxo de bot** | ver abaixo | está/passou por um ponto do seu [fluxo de chatbot](/docs/crm/fluxos). |
### Posição no fluxo de bot (`flowMode`) [#posição-no-fluxo-de-bot-flowmode]
| `flowMode` | Significado |
| ------------- | ------------------------------------------------------------------ |
| `any` | Não considera o fluxo. |
| `in_flow` | A conversa está num fluxo ativo (opcional: `flowId` específico). |
| `at_node` | Está **no nó** `nodeId` do fluxo `flowId` (um ponto exato do bot). |
| `completed` | **Concluiu** o fluxo (`flowId` específico ou qualquer um). |
| `not_in_flow` | Não está em nenhum fluxo. |
Combine os critérios para etapas precisas. Exemplos:
• "Novos leads" → `origin: inbound`, `flowMode: in_flow`.
• "Qualificados" → `flowMode: at_node` no nó "Quer orçamento?" do seu fluxo.
• "Proposta enviada" → `labelId` da etiqueta Proposta, `status: open`.
• "Ganhos" → `status: resolved`, `labelId` da etiqueta Fechado.
## Visualização (canvas) [#visualização-canvas]
O funil é desenhado num **canvas** (igual ao editor de fluxo): cada etapa é um nó com o **nome**, a **contagem** de conversas e um resumo da regra. Você **arrasta** as etapas para organizar, **liga** uma na outra (aresta visual) e, ao **clicar numa etapa**, vê as conversas que chegaram ali. A ligação entre etapas é apenas cosmética — quem decide o conteúdo da etapa é a **regra**, não a aresta.
## Montando um funil pela API [#montando-um-funil-pela-api]
1. **Crie o funil** — [`POST /v1/funnels`](/docs/api/funil/createFunnel) com `name` e, opcionalmente, `instanceId` (limita a uma instância).
2. **Adicione as etapas** — [`POST /v1/funnels/{id}/stages`](/docs/api/funil/createFunnelStage), uma por etapa, com `name`, `color`, a `rule` e `position` (a ordem; maior = mais avançada).
3. **(Opcional) Ligue as etapas** no canvas com [`PATCH .../stages/{stageId}/connection`](/docs/api/funil/setFunnelStageConnection).
4. **Leia os dados** — [`GET /v1/funnels/{id}/data`](/docs/api/funil/getFunnelData): contagem e até 50 conversas por etapa, mais `unplaced` e `totalEvaluated`.
```bash
# Cria o funil
curl -X POST https://api.pepinozap.com.br/v1/funnels \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Funil de vendas" }'
# Adiciona uma etapa "Proposta" (conversas abertas com a etiqueta X)
curl -X POST https://api.pepinozap.com.br/v1/funnels/fnl_.../stages \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Proposta", "color": "amber", "position": 2,
"rule": { "status": "open", "labelId": "lbl_..." } }'
# Lê o funil (contagem + conversas por etapa)
curl https://api.pepinozap.com.br/v1/funnels/fnl_.../data \
-H "Authorization: Bearer pzk_live_xxxxxxxxxxxxxxxx"
```
A avaliação é **on-read** sobre as **5.000 conversas mais recentes** do escopo.
Como cada conversa fica na etapa **mais avançada** que casa, etapas com regras
mais "amplas" (ex.: só `status: open`) devem ter `position` **menor** que
etapas mais específicas — senão elas "capturam" conversas que deveriam aparecer
mais à frente.
# Inbox — conversas e mensagens (/docs/crm/inbox)
O inbox é o **sistema de registro** das conversas: todo o histórico de mensagens, a mídia hospedada e os metadados de cada contato ficam acessíveis pela API `/v1/inbox/*`, independente de qual instância (número) recebeu cada mensagem.
As conversas **não** ficam sob a instância. Não procure por `/instances/{id}/conversations` — o
caminho é **`/v1/inbox/conversations`**. A instância é apenas o número que enviou/recebeu; o
histórico é centralizado no inbox.
**As conversas seguem o modo (teste/produção) da instância** — é o mesmo [isolamento de dados por
modo](/docs/get-started/authentication#isolamento-de-dados-por-modo) das instâncias e webhooks. A
conversa de uma instância de **teste** só aparece pela **API de teste**
(`sandbox.pepinozap.com.br` + key `pzk_test_`); o **Inbox do painel é sempre Produção**, então
conversa de instância de teste **não aparece lá** — não é bug, é o modo. Para vê-la no painel, use
uma instância de **produção** (key `pzk_live_` / host `api.*`).
## Listar conversas [#listar-conversas]
[`GET /v1/inbox/conversations`](/docs/api/inbox/listInboxConversations) devolve as conversas com o **resumo** (último trecho, não-lidas, status, etiquetas, atendente/departamento atribuído) — **sem** o corpo das mensagens. Aceita filtros por `status` (`open`/`pending`/`resolved`), `label` e `department`, e ecoa os **contadores** por status para os badges das abas.
Use essa lista para a coluna da esquerda do seu inbox e re-busque-a periodicamente (ou por evento de WebSocket) para manter os badges e o último trecho atualizados.
## Carregar as mensagens de uma conversa [#carregar-as-mensagens-de-uma-conversa]
[`GET /v1/inbox/conversations/{id}/messages`](/docs/api/inbox/listInboxMessages) devolve a **leva mais recente** de mensagens da conversa (texto, mídia, direção, timestamps, status de entrega). Para o histórico mais antigo:
| Como | Endpoint |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| Paginar para trás | `GET .../messages?before=` (mais antigas que aquela mensagem) |
| Puxar histórico do WhatsApp | [`POST /v1/inbox/conversations/{id}/history`](/docs/api/inbox/requestConversationHistory) |
Cada mensagem tem uma **direção** (`inbound`/`outbound`). O `outbound` inclui tanto o que sua
integração/painel envia quanto o que a equipe responde **direto no celular** — o número é
multi-device, então o que sai de qualquer aparelho é espelhado aqui (e conta no tempo de resposta
dos relatórios). O webhook [`message.received`](/docs/webhooks/events) dispara **só para
`inbound`**; mensagem que sai não gera `message.received`.
## Padrões para um inbox responsivo [#padrões-para-um-inbox-responsivo]
A diferença entre um inbox que "abre na hora" e um que pisca a cada clique está no **cliente**, não no endpoint. Quatro padrões que valem a pena seguir:
### 1. Cache por conversa (stale-while-revalidate) [#1-cache-por-conversa-stale-while-revalidate]
Não re-busque do zero (com skeleton) toda vez que o usuário abre uma conversa que **já viu nesta sessão**. Guarde as mensagens por `conversationId` no cliente:
* **Ao abrir:** se há cache para aquela conversa, mostre-o **na hora** (sem skeleton) e dispare o fetch em background para revalidar — atualize a tela se algo mudou.
* **Skeleton só na primeira** abertura de cada conversa (cold load).
Isso mantém a navegação entre conversas instantânea e evita o "pisca-skeleton" a cada clique. Limpar tudo e mostrar skeleton em **toda** abertura é a causa nº 1 de inbox que "ficou lento".
### 2. Preserve as URLs de mídia [#2-preserve-as-urls-de-mídia]
A `mediaUrl` de cada mensagem é uma URL **presigned, reassinada a cada resposta** (e que expira). Se você trocar o `src` de uma `![]()
`/`