---
title: "Histórico de conversas do WhatsApp pela API: listar, exportar e fazer backup"
description: "Como listar chats, paginar mensagens, baixar mídia e exportar o histórico de conversas do WhatsApp pela API não oficial, com cuidados de LGPD."
url: "https://wame.api.br/blog/historico-conversas-whatsapp-api-exportar"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-28"
modified_time: "2026-09-28"
author: "Raphael Serafim"
keywords: "api whatsapp não oficial, api não oficial whatsapp, exportar conversas whatsapp api, histórico de conversas whatsapp, backup whatsapp api, listar mensagens whatsapp api, importar conversas whatsapp crm"
reading_time: "9 min de leitura"
---

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

> Como listar chats, paginar mensagens, baixar mídia e exportar o histórico de conversas do WhatsApp pela API não oficial, com cuidados de LGPD.

**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](/blog/quanto-custa-perder-numero-whatsapp) 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](/blog/criar-bot-whatsapp-api-nao-oficial) ou para uma [base de conhecimento de IA](/blog/rag-whatsapp-base-conhecimento-ia).

## Passo 1: listar os chats

```bash
curl "https://server.wame.api.br/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

```bash
curl "https://server.wame.api.br/SUA_KEY/chat/messages?chatId=5511999999999@s.whatsapp.net&page=1&limit=100"
```

- `chatId` é o JID da conversa: `numero@s.whatsapp.net` para individual, `id@g.us` 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:

```js
import { createWriteStream } from 'node:fs';

const BASE = 'https://server.wame.api.br/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](/docs)), 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:

```bash
# JSON com o arquivo em base64 (padrão)
curl "https://server.wame.api.br/SUA_KEY/message/ID_DA_MENSAGEM/media"

# Arquivo cru, direto para o disco
curl "https://server.wame.api.br/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](/blog/midia-webhook-whatsapp-baixar-limites).

## 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:

```bash
curl -X PUT "https://server.wame.api.br/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:

```bash
curl -X POST "https://server.wame.api.br/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](/blog/webhook-producao-assinatura-retry-idempotencia).

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](/blog/mongodb-proprio-whatsapp-api-dados).

## 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](/blog/whatsapp-api-lgpd-contrato-cliente).

## 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](/blog/api-whatsapp-nao-oficial-bane-o-que-derruba-numero).

## 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](/docs).

## Perguntas frequentes

### Como listar todas as conversas de um número pela API?

Faça um GET em /{key}/chat?provider=whatsapp. A resposta traz os chats individuais e de grupo com o horário da última mensagem, a quantidade de mensagens e o contato por trás de cada chat (telefone e nome, quando está na agenda).

### Como pego as mensagens de uma conversa específica?

Use GET /{key}/chat/messages?chatId=5511999999999@s.whatsapp.net com os parâmetros page e limit. Cada página traz até 100 mensagens (o padrão é 50). Percorra as páginas até vir uma página vazia para ter a conversa inteira.

### Consigo baixar fotos, áudios e documentos do histórico?

Sim. Com o id da mensagem, faça GET /{key}/message/{messageId}/media. Por padrão vem em JSON com base64; com ?format=binary vem o arquivo cru, pronto para salvar no seu storage.

### O histórico parece incompleto. O que fazer?

Force uma ressincronização com POST /{key}/instance/resync, que puxa de novo mensagens, contatos e chats dos servidores do WhatsApp. Para receber o histórico conforme ele sincroniza, configure o webhookHistory em PUT /{key}/instance.

### Exportar conversas de clientes é permitido pela LGPD?

Pode ser, desde que haja base legal e finalidade clara, como atendimento, auditoria ou continuidade do relacionamento. Guarde só o necessário, restrinja o acesso, defina prazo de retenção e apague quando a finalidade acabar. Conversa exportada continua sendo dado pessoal.