> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Histórico de conversas

> Evento history: as conversas que já existiam no celular.

O evento **`history`** entrega as conversas anteriores do aplicativo do WhatsApp Business, depois que a sincronização é solicitada em [Sincronizar histórico](https://developers.datafyapi.com.br/api-reference/whatsapp/sincronizacao/sincronizar-historico.md).

O conteúdo não chega de uma vez: ele é dividido em **muitas entregas**, cada uma com um pedaço das conversas.

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1234567890123456",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511988887777",
              "phone_number_id": "1234567890123456"
            },
            "history": [
              {
                "metadata": { "phase": 0, "chunk_order": 1, "progress": 55 },
                "threads": [
                  {
                    "id": "5511999999999",
                    "messages": [
                      {
                        "from": "5511988887777",
                        "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
                        "timestamp": "1739230955",
                        "type": "text",
                        "text": { "body": "Segue o orçamento que combinamos." },
                        "history_context": { "status": "READ" }
                      },
                      {
                        "from": "5511999999999",
                        "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0",
                        "timestamp": "1739230970",
                        "type": "text",
                        "text": { "body": "Perfeito, obrigada!" },
                        "history_context": { "status": "READ" }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          "field": "history"
        }
      ]
    }
  ]
}
```

## Como as conversas vêm organizadas

| Campo | Descrição |
| - | - |
| `history[].threads[]` | Cada item é uma conversa |
| `threads[].id` | Número do cliente daquela conversa |
| `threads[].messages[]` | Mensagens da conversa, com o formato das mensagens normais |
| `messages[].from` | Quem enviou: o seu número ou o do cliente |
| `messages[].history_context.status` | Situação da mensagem no histórico: `READ`, `DELIVERED` ou `PLAYED` |

## Acompanhar o progresso

O objeto `history[].metadata` é o que permite saber em que ponto a sincronização está:

| Campo | Descrição |
| - | - |
| `phase` | Período coberto por aquele bloco: `0`, `1` ou `2`, abrangendo até 180 dias de conversas |
| `chunk_order` | Número de ordem do bloco |
| `progress` | Percentual concluído, de `0` a `100` |

A sincronização termina quando chega um bloco com `progress: 100`.

> [!WARNING]
>
> Os blocos podem chegar **fora de ordem**. Use o `chunk_order` para ordenar e o `timestamp` de cada mensagem para montar a conversa, em vez de confiar na ordem de chegada das entregas.

## Mídia no histórico

Mensagens que continham imagem, áudio, vídeo ou documento chegam com `type: "media_placeholder"` e sem o arquivo:

```json theme={null}
{
  "from": "5511988887777",
  "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
  "timestamp": "1739230970",
  "type": "media_placeholder",
  "history_context": { "status": "PLAYED" }
}
```

O marcador indica que houve uma mídia naquele ponto da conversa, mas **o arquivo não é sincronizado** e não pode ser recuperado depois. Mídias enviadas e recebidas a partir da conexão seguem o caminho normal, descrito em [Mensagens recebidas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/mensagens.md).

> [!NOTE]
>
> O volume desse evento é alto: uma conta com muitas conversas gera milhares de entregas em poucos minutos. Responda `200` de imediato e processe em fila, ou as entregas passam a estourar o tempo limite.

## Se a entrega falhar

Como o histórico é uma sincronização única, as entregas de `history` que falham são reenviadas automaticamente, com intervalos crescentes: `10s`, `1min`, `5min` e `30min`. Enquanto a sua URL responder `200`, os blocos seguem chegando normalmente.

Se a URL ficar indisponível além dessa janela, o pedido de sincronização **não se repete sozinho**. A forma garantida de recuperar o histórico é desconectar o número e [refazer a conexão](https://developers.datafyapi.com.br/guias/meta/conexao/coexistencia.md), solicitando a sincronização de novo.

A referência completa está na [documentação do webhook history da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/history).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.