Pular para o conteúdo
D-APITestar grátis

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-demand dispara um pedido de sincronização sob demanda. O parâmetro de query count define quantas mensagens buscar, com padrão de 50.
  • POST /api/v1/history/full-sync pede 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, webhookUrl passa a ser obrigatório e precisa ser uma URL http(s).
  • Filtros. where.messageTimestamp com gte e lte (segundos ou milissegundos) e where.isGroup para separar grupos de conversas individuais.
  • Mídia. Mensagens com media_url armazenada vão com a mídia.
  • Vazão. delivery.maxRps limita 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, o syncJobId e o progresso do job em andamento.
  • Nada a enviar. Quando o filtro não encontra mensagens, a resposta volta com total: 0 e syncing: 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 id e no sessionId.
  • Resposta rápida. Responda 2xx e 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.