Persistência e histórico

O PEPINO ZAP persiste todo o histórico das suas conversas (texto e mídia) na nossa infraestrutura. Para o integrador isso significa uma coisa direta: você não precisa manter um banco de dados nem um storage de mídia próprios só para o WhatsApp. Nós somos o system of record; você lê o histórico pela API quando precisar.

Esta página explica o que é guardado, a diferença entre histórico persistido e efêmero, como ler o histórico pela API e o impacto no Inbox/conversas. Os exemplos usam a URL de produção https://api.pepinozap.com.br; no modo teste, troque para https://sandbox.pepinozap.com.br (com uma key pzk_test_). Todas as requisições exigem o header Authorization: Bearer <API_KEY>, e a key precisa casar com o host — ver Autenticação.

O que guardamos

Tudo que passa pelo seu número conectado é gravado e fica vinculado ao seu Projeto, escopado por modo (teste/produção):

O histórico sobrevive a deletar a instância

Apagar (ou desconectar) uma instância remove apenas a sessão do WhatsApp daquele número — o histórico permanece:

Como as conversas são chaveadas pelo contato (número), ao criar uma instância nova e parear o mesmo número, o histórico daquele número continua disponível pela API. Para enviar mensagens você precisa de uma instância conectada; para ler o histórico, não.

Persistido vs. efêmero

Cada Projeto tem um modo de histórico. O padrão — e o recomendado para a maioria das integrações — é persistido. Existe também um modo efêmero, usado em cenários específicos (por exemplo, números de atendimento onde só interessa o que está em aberto agora, sem manter um arquivo durável visível no Inbox).

O estado CONNECTED é o da instância pareada e operacional — ver o ciclo de vida da instância. Qualquer outro estado (DISCONNECTED, CONNECTING, QR_PENDING, BANNED, ERROR) faz, no modo efêmero, as conversas daquela instância saírem da listagem até a reconexão.

O que muda na prática

• Listagem de conversas (GET /v1/inbox/conversations) e contadores das abas (todas/abertas/pendentes/encerradas): no modo efêmero, ambos refletem só as conversas de instâncias CONNECTED. No persistido, refletem tudo.
• Detalhe e mensagens de uma conversa (GET /v1/inbox/conversations/{id} e /messages): respondem normalmente desde que você tenha o id da conversa — esses endpoints não aplicam o filtro de modo. Em outras palavras, mesmo no modo efêmero, se você guardou o id, ainda lê o histórico daquela conversa específica.
• Webhooks e WebSocket: o modo de histórico não muda a entrega de eventos em tempo real. Mensagens recebidas continuam disparando message.received normalmente nos dois modos.

Qual é o padrão e como alterar

O modo padrão de todo Projeto novo é persistido. Em caso de erro transitório ao carregar a configuração do Projeto, a API assume persistido por segurança — para nunca esconder histórico por engano.

O modo de histórico é uma configuração do Projeto definida na criação dele. Não há endpoint público (key pzk_live_/pzk_test_) para o integrador alternar entre persistido e efêmero — não é um liga/desliga self-service como as configurações da instância. Para revisar ou mudar o modo do seu Projeto, fale com o suporte.

Como ler o histórico

Use os endpoints de Inbox (autenticados pela mesma API key). Eles devolvem o histórico persistido, paginado, escopado ao seu Projeto e ao modo (teste/produção) da key. O Inbox lista apenas conversas 1-a-1 — grupos (@g.us), listas de transmissão (@broadcast) e canais (@newsletter) não aparecem.

Listar conversas

GET /v1/inbox/conversations devolve uma conversa por contato, ordenada por atividade (mais recente primeiro), 30 por página. Aceita ?status= (open, pending ou resolved; vazio = todas) e ?page= (padrão 1).

curl "https://api.pepinozap.com.br/v1/inbox/conversations" \
  -H "Authorization: Bearer $YOUR_API_KEY"

# filtrando por status e paginando
curl "https://api.pepinozap.com.br/v1/inbox/conversations?status=open&page=2" \
  -H "Authorization: Bearer $YOUR_API_KEY"

Resposta 200 OK. O bloco counts traz os totais por status de todo o Projeto (não só da página/filtro atual), úteis para os contadores das abas:

{
  "items": [
    {
      "id": "conv_abc123",
      "instanceId": "inst_xyz789",
      "protocol": "2026-000042",
      "contactId": "cont_def456",
      "contactName": "Maria Silva",
      "contactPhone": "5511999999999",
      "contactJid": "5511999999999@s.whatsapp.net",
      "status": "open",
      "assignedUserId": null,
      "unread": 2,
      "lastMessageAt": "2026-06-05T13:40:00Z",
      "lastMessageText": "Perfeito, obrigado!"
    }
  ],
  "page": 1,
  "counts": {
    "all": 37,
    "open": 12,
    "pending": 5,
    "resolved": 20
  }
}

Ler as mensagens de uma conversa

GET /v1/inbox/conversations/{id}/messages devolve as mensagens em ordem cronológica (mais antiga → mais nova), em páginas. Por padrão traz as limit mais recentes (limit padrão 50, máximo 200). Para o histórico completo (scrollback), pagine para trás com o cursor before.

# página mais recente (até 50 mensagens)
curl "https://api.pepinozap.com.br/v1/inbox/conversations/conv_abc123/messages" \
  -H "Authorization: Bearer $YOUR_API_KEY"

# página anterior (mais antigas): use o nextBefore da resposta anterior
curl "https://api.pepinozap.com.br/v1/inbox/conversations/conv_abc123/messages?before=msg_000123&limit=100" \
  -H "Authorization: Bearer $YOUR_API_KEY"

Resposta 200 OK:

{
  "items": [
    {
      "id": "msg_000122",
      "direction": "INBOUND",
      "type": "text",
      "text": "Bom dia, tudo bem?",
      "mediaUrl": null,
      "mediaMime": null,
      "status": "READ",
      "waMessageId": "3EB0XXXXXXXXXXXX",
      "quotedWaMessageId": null,
      "createdAt": "2026-06-05T13:38:00Z"
    },
    {
      "id": "msg_000123",
      "direction": "OUTBOUND",
      "type": "image",
      "text": "Segue a tabela",
      "mediaUrl": "https://s3.amazonaws.com/.../arquivo.jpg?X-Amz-Signature=...",
      "mediaMime": "image/jpeg",
      "status": "DELIVERED",
      "waMessageId": "3EB0YYYYYYYYYYYY",
      "quotedWaMessageId": null,
      "createdAt": "2026-06-05T13:40:00Z"
    }
  ],
  "hasMore": true,
  "nextBefore": "msg_000122"
}

Paginando o histórico completo: repita a chamada passando o nextBefore da resposta anterior em ?before= até hasMore virar false. Quando hasMore é false, nextBefore vem null — você chegou ao início da conversa.

Veja o contrato completo, com playground "Try it", em Lista as conversas e Lista as mensagens.

Erros possíveis (Inbox)

O envelope de erro é { "error": { "code", "message" } }, em que code é um rótulo string derivado do status HTTP (UNAUTHORIZED, FORBIDDEN, NOT_FOUND).

Tempo real, sem polling

Para reagir a mensagens novas e a mudanças de status na hora, use eventos em vez de ficar consultando a API:

• Webhook — entrega garantida com retry (cadastrado por você via POST /v1/webhooks, self-service). Ver Webhooks.
• WebSocket — self-service, conecta com a sua API key. Ver WebSocket.

O Inbox é a fonte do histórico; os eventos são para o tempo real. Juntos, cobrem todo o ciclo sem você manter banco próprio. O modo de histórico (persistido/efêmero) não altera a entrega desses eventos.

Migrando de uma stack própria

Se você hoje mantém infra própria para o WhatsApp (por exemplo, um banco de mensagens, um bucket de mídia e um canal de realtime), ao integrar o PEPINO ZAP você pode descontinuar essas três camadas:

Próximos passos

• Sua primeira instância — criar, parear e configurar a instância.
• Autenticação — API key, modos teste/produção e o fallback ?token=.
• Lista as conversas — referência completa do Inbox.
• Webhooks — receba eventos de mensagens e de status da instância em tempo real.