histórico pela api
Sincronizar histórico de conversas do WhatsApp no seu SaaS
Sincronize o histórico de conversas do WhatsApp quando o seu cliente conecta o número: o seu SaaS recebe chats, contatos e mensagens antigas e abre o inbox com contexto, sem começar do zero.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Backfill ao conectar
Com historySync ligado na criação da sessão, a conexão traz conversas, contatos e mensagens anteriores do aparelho.
Reenvio em massa para o webhook
O POST /api/v1/history/sync reentrega o histórico armazenado no formato messages.received, com filtro por data e por grupo.
Vazão sob o seu controle
delivery.maxRps limita as requisições por segundo no seu endpoint, com padrão de 100 e teto de 500.
Progresso consultável
Uma rota de status mostra página atual, mensagens processadas, páginas com falha e percentual do job.
Sincronizar o histórico de conversas do WhatsApp resolve o momento mais delicado da adoção de um SaaS: o primeiro dia. O seu cliente, uma clínica, uma imobiliária ou uma loja, conecta o número e espera ver no seu produto as conversas que já tinha no celular. Se o inbox abre vazio, o atendente não sabe o que o paciente pediu ontem, o corretor perde o fio da negociação e a primeira impressão do seu software é de que falta alguma coisa.
A D-API oferece três caminhos para trazer esse passado para dentro do seu sistema: o backfill automático ao conectar, os pedidos de sincronização sob demanda e o reenvio em massa do histórico armazenado para o seu webhook. Todos usam o mesmo sessionId da sessão do seu cliente, como o resto da API de WhatsApp.
Por que o histórico importa para o seu SaaS
Três cenários aparecem com frequência entre clientes SaaS:
- Onboarding de cliente novo. O dono da clínica conecta o número no seu painel e o atendente já encontra as conversas recentes com contexto.
- Migração de ferramenta. O cliente vem de outro sistema e quer manter o registro de atendimento. Você recarrega o histórico no seu banco em vez de pedir que ele exporte arquivos.
- Recuperação depois de incidente no seu lado. Seu worker ficou fora do ar por uma hora e perdeu eventos. O reenvio filtrado por intervalo de datas preenche a lacuna.
Backfill ao conectar o número
Na criação da sessão, o campo historySync (padrão false) liga a sincronização do histórico de conversas do aparelho. Ao conectar, a sessão faz o backfill de conversas, contatos e mensagens anteriores.
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "imobiliaria-4821",
"connectionMode": "qr",
"webhookUrl": "https://seu-saas.com.br/webhooks/whatsapp/imobiliaria-4821",
"historySync": true
}'
O detalhe que muda o desenho do seu consumidor é a forma de entrega. Para não despejar milhares de chamadas no seu endpoint durante o backfill, a D-API trata os eventos de histórico de forma diferente no webhook e no RabbitMQ:
| Evento | No webhook | No RabbitMQ |
|---|---|---|
history.message.upsert |
Suprimido | Entregue, quando configurado |
history.message.received |
Suprimido | Entregue, quando configurado |
history.messages.sent |
Vira messages.received com fromMe: true, só se tiver menos de 5 minutos |
Entregue com o nome original |
history_sync |
Entregue | Entregue |
O history_sync é o sinal de conclusão, com os arrays chats, contacts e messages. Os itens de chats e contacts seguem o mesmo formato de chats.update e contacts.update. As mensagens do backfill chegam sem mídia, porque ela é filtrada durante a sincronização, e com os JIDs normalizados.
Na prática: se você quer cada mensagem antiga como evento individual, consuma pela fila RabbitMQ da sessão. A página de integração com RabbitMQ mostra essa configuração.
Pedir mais histórico sob demanda
Depois da conexão, duas rotas pedem ao aparelho mais histórico:
POST /api/v1/history/on-demanddispara um pedido de sincronização sob demanda. O parâmetro de querycountdefine quantas mensagens buscar, com padrão de 50.POST /api/v1/history/full-syncpede a sincronização completa do histórico.
As duas recebem só o sessionId no corpo e aceitam execução assíncrona. Use o pedido sob demanda quando o atendente rolar até o fim de uma conversa e quiser ver mais para trás, e o completo em processos de onboarding em que o cliente pediu o histórico inteiro.
Reenvio em massa do histórico para o seu webhook
O POST /api/v1/history/sync resolve outro problema: reentregar, no formato messages.received da D-API, as mensagens que já estão armazenadas para a instância. O seu consumidor de webhook não precisa de código novo, porque o payload é o mesmo que ele já trata em tempo real.
{
"sessionId": "imobiliaria-4821",
"where": {
"messageTimestamp": { "gte": 1767225600, "lte": 1769817600 },
"isGroup": false
},
"webhookUrl": "https://seu-saas.com.br/webhooks/backfill",
"delivery": { "maxRps": 50 }
}
O comportamento, conforme a referência e o código da rota:
- Destino. Sem
webhookUrl, vale o webhook da sessão. Na configuração por evento, é usada a URL do evento de mensagem recebida. Se a instância não tem webhook,webhookUrlpassa a ser obrigatório e precisa ser uma URL http(s). - Filtros.
where.messageTimestampcomgteelte(segundos ou milissegundos) ewhere.isGrouppara separar grupos de conversas individuais. - Mídia. Mensagens com
media_urlarmazenada vão com a mídia. - Vazão.
delivery.maxRpslimita as requisições por segundo no seu endpoint, com padrão de 100 e máximo de 500. O limite soma todos os syncs da conta para o mesmo destino, então dois reenvios em paralelo não dobram a carga no seu servidor. - Um por vez. Se já existe um job pendente ou em processamento para a instância, a resposta traz
syncing: true, osyncJobIde o progresso do job em andamento. - Nada a enviar. Quando o filtro não encontra mensagens, a resposta volta com
total: 0esyncing: false.
O processamento roda em fila, fora do request, em páginas de até 1.000 mensagens. A resposta da chamada sai logo, com o syncJobId.
Acompanhar o progresso do job
O GET /api/v1/history/sync/{sessionId}/status mostra o último job da instância. O status vai de pending a processing e termina em completed ou failed. O bloco progress traz currentPage, totalPages, totalMessages, processedMessages, failedPages e percent, e o campo errors lista o que falhou. Com isso, o seu painel mostra uma barra de “importando conversas” para o cliente, em vez de uma tela parada sem feedback.
Cuidados no seu consumidor
Histórico é volume, e volume pede alguns cuidados no lado do seu SaaS:
- Idempotência por ID da mensagem. Reenvio, retentativa de webhook e evento em tempo real podem trazer a mesma mensagem. Grave com chave única no
ide nosessionId. - Resposta rápida. Responda
2xxe processe em fila própria. O webhook da D-API tem timeout de 30 segundos por tentativa, e o artigo sobre webhooks da API de WhatsApp explica a política de retentativa. - maxRps compatível com a sua infra. Comece baixo, observe a latência do endpoint e suba. O padrão de 100 req/s pode ser demais para um worker pequeno.
- Armazenamento ligado. O reenvio em massa lê o que está armazenado. Se a conexão usa
disableMessageStorage, o conteúdo das mensagens não é persistido na D-API e não há o que reenviar.
Os detalhes de cada evento estão na documentação da D-API. Com o histórico no seu banco, o passo seguinte é dar ao atendente as ferramentas de inbox da API de chats.
Time D-API. Atualizado em .
Perguntas frequentes
As mensagens do backfill chegam no webhook uma por uma?
Não. Os eventos history.message.upsert e history.message.received são suprimidos no webhook para evitar uma enxurrada de chamadas e ficam disponíveis via RabbitMQ, quando configurado. No webhook chega o history_sync com os agregados.
Posso rodar dois reenvios em massa ao mesmo tempo para a mesma conexão?
Não. Se já existe um job pendente ou em processamento para a instância, a chamada devolve syncing: true com o syncJobId e o progresso do job em andamento, sem abrir outro.
Em que unidade vão os timestamps do filtro?
O filtro where.messageTimestamp aceita gte e lte em segundos ou em milissegundos. Valores abaixo de 1e12 são tratados como segundos.
O reenvio em massa inclui imagens e documentos?
Inclui a mídia quando a mensagem armazenada tem media_url. No backfill feito ao conectar, a mídia é filtrada durante a sincronização.
Preciso ter webhook configurado na sessão para usar o reenvio?
Não. Sem webhook na sessão, envie webhookUrl no corpo da chamada. Com webhook configurado, ele é usado por padrão, e o webhookUrl do corpo sobrescreve.