Histórico de conversas do WhatsApp pela API: listar, exportar e fazer backup

Pela API não oficial do WhatsApp você lista todos os chats de um número com GET /chat, pagina as mensagens de cada conversa com GET /chat/messages (até 100 por página), baixa a mídia com GET /message/{id}/media e, se algo faltar, força uma ressincronização com POST /instance/resync. Com essas quatro peças dá para exportar o histórico para CSV, importar num CRM, montar uma auditoria ou simplesmente ter um backup que não depende do celular.

É um dos recursos em que a camada não oficial mais se diferencia: como ela se conecta como um aparelho vinculado, enxerga as conversas do número — não só as mensagens trocadas depois que a integração começou.

A camada não oficial não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Para que serve exportar o histórico

Os motivos mais comuns que aparecem no suporte:

• Migrar para um CRM. A empresa atendia pelo celular por anos e agora vai para um sistema. Sem o histórico, o atendente começa cada conversa no escuro.
• Auditoria e qualidade. Revisar como a equipe atende, encontrar promessas feitas ao cliente, resolver disputas ("vocês disseram que o frete era grátis").
• Backup. O número é um ativo da empresa. Se o aparelho some, perder o número já é ruim; perder a memória das conversas junto é pior.
• Análise. Quais perguntas se repetem, quanto tempo leva para responder, o que vira venda. Matéria-prima para um bot ou para uma base de conhecimento de IA.

Passo 1: listar os chats

curl "https://us.api-wa.me/SUA_KEY/chat?provider=whatsapp"

A resposta traz os chats do canal pedido — individuais e grupos — com o horário da última mensagem, a quantidade de mensagens, o canal e o contato por trás do chat (contact com telefone e nome; o nome vem vazio quando o número não está na agenda).

O parâmetro provider importa: se a instância também tem Instagram ou Messenger conectados, as conversas dos três canais ficam no mesmo armazenamento. Sem escolher o canal, um identificador do Instagram poderia se misturar com um telefone. Pedir um canal que a instância não tem conectado retorna 422.

Passo 2: paginar as mensagens de cada chat

curl "https://us.api-wa.me/SUA_KEY/chat/[email protected]&page=1&limit=100"

• chatId é o JID da conversa: [email protected] para individual, [email protected] para grupo.
• limit vai até 100 por página (o padrão é 50).
• page avança até vir uma página vazia.

Um exportador completo em Node.js, que grava uma linha por mensagem num arquivo JSONL:

import { createWriteStream } from 'node:fs';

const BASE = 'https://us.api-wa.me/SUA_KEY';
const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

async function get(path) {
  const res = await fetch(`${BASE}${path}`);
  if (!res.ok) throw new Error(`${path} → ${res.status}`);
  return res.json();
}

async function exportar() {
  const saida = createWriteStream('./historico.jsonl');
  const chats = await get('/chat?provider=whatsapp');

  // A lista vem em `chats`; cada item traz o `chatId` e o `contact` por trás dele.
  for (const { chatId } of chats.chats ?? []) {
    for (let page = 1; ; page++) {
      const r = await get(`/chat/messages?chatId=${encodeURIComponent(chatId)}&page=${page}&limit=100`);
      // As mensagens vêm em `messages`, e `pagination.hasMore` diz se há próxima página.
      const mensagens = r.messages ?? [];

      for (const m of mensagens) saida.write(JSON.stringify({ chatId, ...m }) + '\n');
      if (!r.pagination?.hasMore) break;
      await esperar(300); // leitura sem pressa: ninguém precisa do backup em 3 segundos
    }
  }
  saida.end();
}

await exportar();

Repare nos dois cuidados: o formato exato da lista fica isolado em poucas linhas (confira os nomes de campo na documentação), e há uma pausa entre páginas. Exportar histórico é leitura, não envio — não pesa no anti-spam —, mas não há motivo para martelar a API.

JSONL é um bom formato intermediário: uma mensagem por linha, fácil de reprocessar. Dele você converte para CSV, importa num banco ou manda para um CRM.

Passo 3: baixar a mídia

Mensagem de foto, áudio ou documento tem conteúdo que não cabe numa linha de texto. Com o id da mensagem:

# JSON com o arquivo em base64 (padrão)
curl "https://us.api-wa.me/SUA_KEY/message/ID_DA_MENSAGEM/media"

# Arquivo cru, direto para o disco
curl "https://us.api-wa.me/SUA_KEY/message/ID_DA_MENSAGEM/media?format=binary" -o arquivo.bin

Para o backup, format=binary é o mais prático: salve no seu storage com o id da mensagem no nome e guarde o caminho junto da linha da mensagem. Se precisar dos detalhes de uma mensagem isolada — conteúdo, metadados, status de entrega —, use GET /message/{messageId}.

Os limites de tamanho por tipo de mídia e o fluxo de download pelo webhook estão em mídia no webhook do WhatsApp.

Quando o histórico parece incompleto

Logo depois de conectar um número, o histórico ainda está chegando: o WhatsApp sincroniza as conversas antigas com o aparelho vinculado aos poucos. Duas ferramentas ajudam:

Receber o histórico por webhook. Configure a URL de histórico junto com os outros webhooks:

curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookMessage": "https://seu-sistema.com/webhook/mensagens",
    "webhookHistory": "https://seu-sistema.com/webhook/historico",
    "webhookFormat": "meta"
  }'

Assim o seu sistema recebe os lotes conforme a sincronização acontece, sem precisar ficar consultando.

Forçar ressincronização. Se os dados parecem desatualizados ou faltando pedaços:

curl -X POST "https://us.api-wa.me/SUA_KEY/instance/resync"

Isso puxa de novo mensagens, contatos e chats dos servidores do WhatsApp. Use quando precisar — não é algo para rodar em cron a cada minuto.

Do backup para o dia a dia

Exportar uma vez resolve a migração. Para manter o histórico sempre completo, a combinação que funciona é:

1. Carga inicial com GET /chat + GET /chat/messages, como acima.
2. Webhook de mensagens para tudo que chega a partir de agora.
3. Webhook de mensagens enviadas (webhookMessageFromMe) para registrar também o que a equipe responde — inclusive pelo celular. Essas chegam marcadas com from_me: true.
4. Deduplicação pelo id da mensagem, porque a carga inicial e o webhook podem se sobrepor. O padrão está em webhook em produção: idempotência.

Se a ideia é guardar tudo no seu próprio banco desde a origem, a instância também pode usar um MongoDB seu como armazenamento — está em MongoDB próprio na API do WhatsApp.

LGPD: exportar não é guardar para sempre

Conversa de WhatsApp é dado pessoal — às vezes sensível (saúde, finanças). Exportar muda onde esse dado mora, e a responsabilidade vai junto. O mínimo:

• Finalidade clara. Atendimento, auditoria, continuidade do relacionamento. "Pode ser útil um dia" não é finalidade.
• Acesso restrito. O arquivo exportado não vai para o drive compartilhado de todo mundo.
• Criptografia em repouso no storage onde o backup fica.
• Prazo de retenção. Defina quanto tempo guarda e apague depois.
• Atenda pedidos de exclusão. Se o cliente pedir, a conversa sai do backup também.

Para quem entrega isso a clientes, os pontos de contrato estão em API de WhatsApp e LGPD.

E o risco de bloqueio?

Ler histórico é uma das operações mais tranquilas da API: não envia nada para ninguém, então não gera denúncia nem se parece com disparo. O risco de bloqueio num número usado para atendimento com exportação de histórico é muito baixo quando o uso é o certo. O que derruba número continua sendo o que se envia — o panorama está em o que realmente derruba um número.

Conclusão

Exportar o histórico de conversas do WhatsApp pela API não oficial é uma sequência simples: GET /chat para listar, GET /chat/messages para paginar até 100 mensagens por vez, GET /message/{id}/media para a mídia e POST /instance/resync quando faltar algo. Com o webhook de histórico e o de mensagens enviadas ligados, o backup deixa de ser um evento e vira rotina. Trate o resultado como o que ele é — dado pessoal de cliente — e você ganha memória, auditoria e matéria-prima para automação sem depender do celular. Os detalhes de cada endpoint estão na documentação.