Enviar e receber

Histórico de conversas

Quando um número é pareado, o WhatsApp entrega ao Nuntis as conversas que já existiam naquele aparelho. O Nuntis guarda esse histórico e o expõe pela API — mas não o anuncia por webhook. Esta página explica de onde ele vem, por que chega em silêncio, e como trazê-lo para o seu produto.

1. De onde vem o histórico

Há dois momentos em que mensagens anteriores ao pareamento entram no Nuntis:

O que o WhatsApp envia no pareamento é decidido pelo WhatsApp, não pelo Nuntis: é um recorte das conversas mais recentes, e o tamanho desse recorte varia por conta. O Nuntis não pede mais do que isso ao canal — pedir histórico adicional ao WhatsApp é um sinal que expõe o número, e o Nuntis não emite esse sinal em nome de ninguém.

2. Histórico não dispara webhook — de propósito

A consequência prática é uma decisão de arquitetura do seu lado: o webhook é um aviso de que algo aconteceu agora; a API é a fonte. Um produto que mantém cópia local das mensagens alimentada apenas por webhook está, por construção, cego para tudo o que não é tempo real — histórico do pareamento, eventos perdidos numa janela de indisponibilidade do seu endpoint, correções. Se a cópia local existe, ela precisa ser ressincronizada a partir da API, e a seção seguinte mostra como.

3. Ler o histórico pela API

GET /v1/messages

Lista mensagens de todas as conversas de todos os números do seu tenant, em ordem cronológica crescente, paginadas por cursor. Aceita três parâmetros:

# primeira página: sem cursor
curl -H "x-api-key: $NUNTIS_API_KEY" \
  "https://api.nuntis.com.br/v1/messages?limit=100"

# páginas seguintes: repasse cursor.next até ele vir null
curl -H "x-api-key: $NUNTIS_API_KEY" \
  "https://api.nuntis.com.br/v1/messages?limit=100&since=eyJjIjoi..."

{
  "data": [
    {
      "id": "msg_18273",
      "conversationId": "conv_991",
      "numberId": "num_7",
      "direction": "inbound",
      "type": "text",
      "from": { "phoneE164": "+5585999998888", "pushname": "Ana" },
      "text": { "body": "Bom dia, ainda tem vaga?" },
      "timestamp": "2026-06-14T13:02:11.000Z",
      "timestampUnix": 1781485331,
      "status": "received"
    }
  ],
  "cursor": { "next": "eyJjIjoiMjAyNi0wNi0xNFQxMzowMjoxMS4wMDBaIn0" }
}

O cursor que você guardou não alcança o histórico

O cursor é posicional: marca um ponto na linha do tempo e a página seguinte traz o que vem depois dele. O histórico entra com a data real de cada mensagem — que é anterior ao ponto onde o seu cursor parou. Continuar paginando de onde você estava, portanto, nunca chega ao histórico: ele ficou para trás.

Para trazê-lo, faça uma varredura a partir do início — sem since — ou por conversa, com conversationId, que também começa do início daquela conversa. Deduplique pelo id da mensagem: é o mesmo identificador que chega em data.id no webhook e em GET /v1/messages/{id}, estável para sempre. Uma mensagem que você já tem é ignorada; uma que você não tem é histórico (ou evento perdido — e a cura é a mesma).

Quando fazer a varredura

• Depois de cada pareamento. Observe GET /v1/numbers/{id}/status até connected. O WhatsApp entrega o histórico nos minutos seguintes; uma varredura alguns minutos depois de connected o encontra. O contrato ainda não expõe um sinal de "histórico concluído" — se uma varredura vier incompleta, repita mais tarde; a deduplicação pelo id torna a repetição barata.
• Uma vez agora, para os números que já estavam em operação antes de 02/09/2026 e receberam o histórico importado.
• Sempre que o seu endpoint de webhook tiver ficado fora do ar por mais tempo do que a janela de retentativa descrita em Garantias de entrega.

4. O que vem no histórico, e o que não vem

Rotas desta página

Nuntis — serviço de mensageria multicanal da Devari.