# Receber o histórico de Coexistence

`GET /v1/connections/:id/history`

Ao conectar um número por Coexistence, antes de abrir a janela da Meta, o negócio responde se quer que entreguemos o histórico das suas conversas: **até 6 meses, as mensagens das duas partes, sem grupos**. O histórico continua no celular dele: nada é apagado nem movido dali. **A escolha é agora**: a Meta compartilha o histórico uma única vez, quando o número é conectado, e se a resposta for não, depois não dá para pedir. Se a resposta for sim, pedimos à Meta (no app WhatsApp Business é preciso aceitar compartilhá-lo), guardamos **criptografado por até 7 dias** e entregamos a você de duas formas, a que acontecer primeiro:

· **Por webhook:** eventos `history.batch` com até 500 mensagens cada um (no formato da Meta, como `message.received`, com `contact` e `direction`), assinados como os demais, e um `history.completed` quando não sobra nada. Vão por uma fila separada que não atrasa as suas mensagens ao vivo: um histórico grande pode levar horas.
· **Pela API**, se você ainda não tem webhook: GET /v1/connections/{id}/history entrega os lotes em ordem (`limit` de 1 a 5, `after` = o `nextCursor` anterior). Ler não apaga: quando tiver guardado um lote, confirme-o com POST /v1/connections/{id}/history/{batchId}/ack.

Cada lote **é apagado assim que é entregue** (o seu 2xx ou a sua confirmação); o que não for entregue é apagado aos 7 dias de qualquer jeito. Se no quinto dia restarem lotes sem entregar, avisamos UMA vez por número (painel e e-mail) com a data em que serão apagados. Não conta como tráfego nem consome cota. Se o negócio respondeu que não, não pedimos nada à Meta. Se um dia ficarmos sem espaço, deixamos de guardar histórico novo e avisamos com `history.dropped`.

## Exemplos

### cURL

```bash
# 1) read a page (reading does NOT delete)
curl "https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "data": [ { "batchId": "hb_…", "count": 500, "messages": [ … ] } ], "hasMore": true, "nextCursor": 1 }

# 2) once you stored it, confirm it → deleted from WAIA Connect at once
curl -X POST "https://api.waiaconnect.com/v1/connections/conn_…/history/hb_…/ack" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# 3) next page: ?after=1 (the nextCursor) — until hasMore is false
```

### Node.js

```javascript
const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY" };
let after = 0, hasMore = true;
while (hasMore) {
  const page = await (await fetch(`https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1&after=${after}`, { headers: H })).json();
  for (const batch of page.data) {
    await saveMessages(batch.messages);            // your storage; dedupe on batch.batchId
    await fetch(`https://api.waiaconnect.com/v1/connections/conn_…/history/${batch.batchId}/ack`, { method: "POST", headers: H });
  }
  hasMore = page.hasMore;
  after = page.nextCursor;
}
```

### PHP

```php
<?php
$h = ["Authorization: Bearer wc_live_YOUR_API_KEY"];
$after = 0;
do {
  $ch = curl_init("https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1&after=" . $after);
  curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h]);
  $page = json_decode(curl_exec($ch), true);
  foreach ($page["data"] as $batch) {
    save_messages($batch["messages"]); // your storage; dedupe on batchId
    $ack = curl_init("https://api.waiaconnect.com/v1/connections/conn_…/history/" . $batch["batchId"] . "/ack");
    curl_setopt_array($ack, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => $h]);
    curl_exec($ack);
  }
  $after = $page["nextCursor"];
} while ($page["hasMore"]);
```

### Python

```python
import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}
after, has_more = 0, True
while has_more:
    page = requests.get("https://api.waiaconnect.com/v1/connections/conn_…/history", headers=H, params={"limit": 1, "after": after}).json()
    for batch in page["data"]:
        save_messages(batch["messages"])  # your storage; dedupe on batchId
        requests.post(f"https://api.waiaconnect.com/v1/connections/conn_…/history/{batch['batchId']}/ack", headers=H)
    has_more, after = page["hasMore"], page["nextCursor"]
```

## Notas

- **Fotos, áudios e documentos chegam sem o arquivo** (`type: "media_placeholder"`, sem `id`). A Meta manda o arquivo só dos últimos 14 dias, numa mensagem separada com o mesmo `id` de mensagem e o seu `image.id` (ou `.audio.id`, …), e nem sempre manda: se chegar, baixe-o com GET /v1/media/{id} dentro dos 7 dias. Cada um traz o nosso `connect.media`: `{ status: "available", available_until }` se veio com o seu `id`, ou `{ status: "unavailable", reason }` com `older_than_14_days` (a Meta nunca o manda), `meta_failed` (a Meta não conseguiu trazê-lo do celular; esse 131052 já não chega a você como `message.status`) ou `pending` (pode chegar em outro lote).
- **Deduplique por `batchId`**: um lote pode chegar duas vezes (por exemplo, se reiniciarmos no meio de uma entrega).
- Se você integra com links de cadastro, mande `historyDelivery: true|false` ao criar o link se já perguntou ao seu cliente; se não, a página pergunta a ele.
- `history.synced` continua chegando como resumo de cada lote da Meta (`progress: 100` = a Meta terminou).